# Script API

> Talos 0.6

359 pages.

| Name | Summary |
|---|---|
| ActionBinding | What one action is bound to right now, in the shape `meta.input` writes it. |
| ActionState | One frame of an action button. |
| AnimationEndEvent | `data` of the event a one-shot raises when it ends: `"animation-end"` unless it names its own. |
| Animator | Present on `ctx.animator` when the entity has an animator component. |
| AnimatorComponent |  |
| AnimatorError | Thrown at load for an animator that cannot be run. |
| AnimatorMachine |  |
| AnimatorOptions |  |
| AnimatorPlayOptions | How a one-shot started by {@link Animator.play} leaves. |
| AnimatorProps |  |
| AnimEvent |  |
| AnimIk | One two-bone IK chain: a leg or an arm, solved so its end bone sits on a point. |
| AnimLookAt | A head-and-spine aim. |
| AnimLookAtLimits | How far a look-at may turn a head away from where the clip put it, in degrees. |
| AnimOnce | How a one-shot state leaves: `once` on a state. |
| AnimParam |  |
| AnimPelvis | Lower the hips so a foot out of reach can still be planted. |
| AnimRetarget | A map from the canonical humanoid's bone names onto this rig's. |
| AnimSpeedParam | `speedParam` on a state: the rate follows `max(0, parameter × scale)`. |
| AnimState |  |
| AnimTransition |  |
| AudioBusHandle | One bus of the mixer graph, by name. |
| AudioComponent |  |
| AudioDirector |  |
| AudioDirectorOptions |  |
| AudioHandle | Mixer control: the bus graph, its snapshots, the music layers, and one-shot cues. |
| AudioMusicHandle | The score. |
| AudioOptions |  |
| AudioProps |  |
| AudioRampOptions | Options of {@link AudioHandle.setPitch} and {@link AudioHandle.setVolume}. |
| Author | The one capability an authoring script has. |
| AuthorEntitySpec | A plain entity: {@link AuthorPlacement}, its tags and its components. |
| AuthorHandle | What a.entity and a.instance hand back: pass it as another entity's `parent`. |
| AuthorImportSettings | How a model is brought in: `asset.import`'s settings. |
| AuthorInstanceSpec | A prefab instance: {@link AuthorPlacement} and its overrides, as `prefab.place` takes them. |
| AuthorPlacement | Where an entity goes, relative to its parent. |
| AxisParts | One axis action this tick, split by the kind of motion that produced it (`ctx.input.axisParts`). |
| Behavior | What a behavior module exports as `default`. |
| BEHAVIOR_CATALOGUE |  |
| BehaviorEntry | The behavior catalogue: the modules a scene can name in `script.module`. |
| Behaviour | The base of a behaviour written as a class. |
| Bindings | This behavior's name → the `ctx.input` action name(s) it reads. |
| BlendInfo |  |
| BlendPoint |  |
| BlendTree |  |
| BobConfig | The walk bob: a cycle that advances with the distance the target walks, at an amplitude that grows with its speed. |
| BobState | The bob this tick, for a view-model to apply in its own units. |
| BusCharacterSqueezed | Payload of the engine-published `"character-squeezed"` event: a moving body is closing on a character ({@link Controller.squeezedBy}) — a door coming down on it, a lift carrying it up into a ceiling. |
| BusCollision | Payload of the engine-published `"collision"` bus event. |
| BusCue | Ramp one bus of `meta.audio.buses`. |
| BusEventMap | The bus names the engine itself publishes, and what each one's `data` is. |
| BusHoldBroken | Payload of the engine-published `"hold-broken"` event: a hold made with {@link WorldQuery.hold \| ctx.world.hold} has ended, for any reason. |
| BusTeleported | Payload of the engine-published `"teleported"` event: a tool moved an entity outright with `POST /entity/{id}/teleport` — a bench putting the player on a mark, an editor. |
| BusTriggerEvent | Payload of the engine-published `"trigger"` bus event: {@link TriggerEvent} plus both scene ids. |
| BusUiActivated | Payload of the engine-published `"ui-activated"` event: a node on a screen was activated — a click, a tap, Return or Space on the focused node, the pad's `uiActivate`, or `POST /ui/activate`. |
| CameraArm | {@link CameraHandle.arm}: what the engine rig's boom is doing this frame. |
| CameraBlend |  |
| CameraComponent |  |
| CameraDirector |  |
| CameraDirectorInit |  |
| CameraHandle | The active camera rig. |
| CameraParams | Settings for {@link CameraHandle.set}. |
| CameraProps |  |
| CameraRig |  |
| CameraRigSettings |  |
| CastOptions | Options for {@link WorldQuery.raycast} and {@link WorldQuery.shapeCast}. |
| Collision | Payload of {@link Behavior.onCollision}. |
| Controller | Present on `ctx.controller` when the entity has a character-controller component (kinematic capsule). |
| ControllerComponent |  |
| Ctx | Everything a behavior can reach. |
| Cue |  |
| DataHandle | `ctx.data`: values a behaviour publishes for a data recording (`argus run --record-data`) — the signals a test-and-evaluation run or an engineering analysis wants beside the transforms: an altitude error, a controller's command, a phase name. |
| distance | Straight-line distance between two points (three.js `distanceTo`). |
| EmitEvent | A behavior called `events.emit`. |
| EntityHandle | The entity a behavior is attached to, or any entity returned by a query. |
| EnvironmentInfo | The sky the scene is lit by. |
| EventBus | The global event bus. |
| FilesHandle | The project's own data files, read-only: a table of enemy stats, a level list, a drop table as CSV. |
| FirstPersonConfig |  |
| FirstPersonRig |  |
| FixedConfig |  |
| FixedRig |  |
| Follow2DConfig |  |
| Follow2DRig |  |
| followGround | Keep this entity on the ground: cast from above its own position, put it on what the cast found and return what was decided (`position` in the world frame). |
| FollowGroundOptions |  |
| FootProp | One foot: the IK chain it drives, and where it sits in the character's own frame. |
| GameEvent | A game event as delivered to `onEvent` and to `events.on` handlers. |
| GoalComponent |  |
| GoalSpec |  |
| GroundFollow | What one tick of ground-following decided. |
| GroundingProps |  |
| GroundingState |  |
| Hit | Result of a raycast or shape cast. |
| HoldOptions | Options for {@link WorldQuery.hold}. |
| HudComponent |  |
| HudController |  |
| HudHandle | HUD overlay. |
| HudOptions |  |
| HudProps |  |
| InputActionDoc | One action's bindings, as `meta.input.contexts.<context>.<action>` spells them. |
| InputConfig |  |
| InputMap | A logical action map over `ctx.input`; rebinding is a data edit, not a code edit. |
| InputMapInit |  |
| InputState | Present on `ctx.input` only for the player entity. |
| InstanceStore |  |
| IntegerLens | The lens a {@link PixelScaleConfig} asks for in a viewport `pixelHeight` tall. |
| Joint | Present on `ctx.joint` while the entity's `joint` component is in force: a hinge, a slide or a weld from this entity's body to another's or to the world. |
| JointMotorOptions | {@link Joint.setMotor}'s options. |
| JointMotorState | {@link Joint.motor}, as it stands. |
| LabelComponent |  |
| LabelDirector |  |
| LabelDirectorOptions |  |
| LabelProps |  |
| LabelsHandle | World-space text labels. |
| LocomotionProps |  |
| LocomotionState |  |
| MusicCue | Change music layer at the next bar line. |
| MusicOptions |  |
| NavAgent | Present on `ctx.nav` when the entity has a nav-agent component. |
| OrbitConfig |  |
| OrbitRig |  |
| OrbitShotSpec | What {@link orbitShot} builds a shot from. |
| PARTICLE_PARAMS | The preset table. |
| ParticleDirector |  |
| ParticleParams |  |
| ParticlesComponent |  |
| ParticlesHandle |  |
| ParticlesProps |  |
| PathProps |  |
| PathState |  |
| PickOptions | Options for {@link WorldQuery.pick}. |
| PixelScaleConfig | A whole-number pixel scale: see {@link Follow2DConfig.pixelScale}. |
| PlayerProps |  |
| PlayerState |  |
| Quat | Quaternion `[x, y, z, w]`. |
| QueryFilter | Filter for {@link WorldQuery.query}; every given field must match. |
| Rect2 | An axis-aligned rectangle in the XY plane, world units. |
| ReleaseOptions | Options for {@link WorldQuery.release}. |
| RenderHandle | Data-only writes to the parameters of shaders (`*.shader.wgsl`, docs/SHADERS.md). |
| RigidBody | Present on `ctx.body` when the entity has a physics body — a `rigidbody` component, or a `collider`, which makes a static one. |
| RigInput | The per-tick input a rig consumes. |
| RoadBarrier | A road's wall as its file asked for it: `RoadLine.barrier`. |
| RoadClosest | Where a position is relative to a road's centre line: what {@link RoadLine.closest} returns. |
| RoadEdge | The road's edges at one distance: what {@link RoadLine.edge} returns. |
| RoadLine | A road's centre line, from `ctx.world.road(id)`. |
| RoadSample | One point on a road's centre line: what {@link RoadLine.at} returns. |
| Roll |  |
| rollFromMotion | The spin a sphere of `radius` needs to roll along `displacement` without slipping. |
| rollRotation | `rotation` after rolling along `displacement`: {@link rollFromMotion}'s `delta` applied in the world frame, renormalised. |
| SaveHandle | A small JSON store that outlives the run: a best score, an unlocked level, a chosen setting. |
| SceneInputDoc | A whole `meta.input` document. |
| ScriptErrorEvent | A behavior threw, blew its budget, or was interrupted; it is disabled from `frame` on — unless `disabled` is false (a stale handle in a per-tick hook, which ends that call only). |
| SessionHandle | The run itself, rather than anything in the world. |
| Shot | One shot: its keys, how long it lasts, and how it begins. |
| ShotKey | One keyframe of a shot. |
| ShotList | A shot list, sampled by time. |
| ShotListOptions |  |
| ShotSample | What a shot list says the camera is doing at one time. |
| ShotsProps |  |
| ShotsState |  |
| SnapshotCue | Cross-fade every bus to a named `meta.audio.snapshots` entry. |
| SpawnLikeOptions | {@link SpawnOptions} that copy a live entity. |
| SpawnPlacement | What both forms of {@link SpawnOptions} take. |
| SpawnPrefabOptions | {@link SpawnOptions} that spawn a copy of a prefab file (docs/SPEC.md, "Prefabs"). |
| Sprite | Present on `ctx.sprite` when the entity has a `sprite` component: a 2D picture in the world that turns to the camera, shows the view of its frame nearest the camera's direction, and plays the named animations the component declares. |
| SpriteAnimationEndEvent | `data` of the event a non-looping sprite animation raises when it ends. |
| SpritePlayOptions | How an animation started by {@link Sprite.play} ends. |
| Strings | A read-only string table. |
| StringsHandle |  |
| StringTable |  |
| StringTableOptions |  |
| ThirdPersonConfig |  |
| ThirdPersonRig |  |
| Tilemap | Present on `ctx.tilemap` when the entity has a `tilemap` component: a grid of tiles in the entity's XY plane. |
| TimeInfo | Simulation clock. |
| TouchBindingDoc | A touch source: a screen region (normalised 0..1, origin top left) and what a finger in it does. |
| TransitionOptions |  |
| TriggerEvent | Payload of {@link Behavior.onTrigger}. |
| UiHandle | `ctx.ui` — the game UI's screen stack. |
| UiNode | One node of a screen description. |
| UiProp | What `ctx.ui.set` can write. |
| UiScreenDescription | A whole screen, as `ctx.ui.screen` takes it. |
| UiScreenOptions | Screen-level options, carried in the root node's `props`. |
| Vec3 | `[x, y, z]` in metres, Y up, right-handed, forward is -Z. |
| Vehicle | Present on `ctx.vehicle` while the entity is a running vehicle: a `vehicle` component on a dynamic body with a collider. |
| VehicleDrive | {@link Vehicle.drive}: what a behaviour asks of a vehicle; every field 0 when left out. |
| ViewModel |  |
| ViewModelConfig |  |
| ViewModelFrame | One frame: an image of the project and where its pivot is. |
| ViewSize | `ctx.camera.viewSize`: an orthographic view's extent in world units, and the viewport in pixels. |
| Wheel | Present on `ctx.wheel` while the entity is a running wheel: a `wheel` component on an entity with a dynamic body above it in the hierarchy. |
| WheelContact | {@link Wheel.contact}: where the tyre touches the ground. |
| WorldQuery | Read access to every entity plus the physics and navigation queries. |
| WritableComponents | The component types {@link EntityHandle.set} can write, and the fields each one takes. |

### ActionName 

*Since 0.6*

#### Signature

```ts
export type ActionName = BuiltInAction | (string & {})
```

Import: `import type { ActionName } from "@argus/gameplay"`

### add 

*Since 0.6*

`a + b`, a new tuple.

#### Signature

```ts
export function add(a: Vec3, b: Vec3): Vec3
```

Import: `import { add } from "@argus/gameplay"`

### angleDelta 

*Since 0.6*

The shortest signed difference between two angles, in radians, wrapped to (-pi, pi].

#### Signature

```ts
export function angleDelta(from: number, to: number): number
```

Import: `import { angleDelta } from "@argus/gameplay"`

### angularVelocityBetween 

*Since 0.6*

The angular velocity, rad/s about a world axis, that turns `from` into `to` in `dt` seconds: the shorter way round, so a turn is read correctly while it is under half a revolution per `dt`.

#### Signature

```ts
export function angularVelocityBetween(from: Quat, to: Quat, dt: number): Vec3
```

Import: `import { angularVelocityBetween } from "@argus/gameplay"`

### animatorBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/animator.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const animatorBehavior: Behavior<Record<string, never>, AnimatorProps>
```

Import: `import { animatorBehavior } from "@argus/gameplay"`

### animatorMachine 

*Since 0.6*

The machine running on an entity, for tests and for behaviors that want to drive it directly.

#### Signature

```ts
export function animatorMachine(ctx: Ctx<any, any>): AnimatorMachine | null
```

Import: `import { animatorMachine } from "@argus/gameplay"`

### AnimParamSource 

*Since 0.6*

Where a blend-tree parameter gets its value when no behavior writes one.

#### Signature

```ts
export type AnimParamSource = "speed" | "strafeX" | "strafeY" | "verticalSpeed" | "grounded" | "inputSpeed" | "inputStrafeX" | "inputStrafeY"
```

Import: `import type { AnimParamSource } from "@argus/gameplay"`

### applyControllerEvent 

*Since 0.6*

Feed one controller event to a machine: the authored transition first, then the humanoid fallback.

Returns the state entered, or null when nothing matched.

#### Signature

```ts
export function applyControllerEvent(machine: AnimatorMachine, event: ControllerEvent, animator: Animator | null, fallbackBlend = FALLBACK_BLEND): string | null
```

Import: `import { applyControllerEvent } from "@argus/gameplay"`

### applyDeadzone 

*Since 0.6*

Apply a radial deadzone and rescale the remainder to 0..1, so there is no jump at the edge.

#### Signature

```ts
export function applyDeadzone(axis: Vec2, deadzone: number): Vec2
```

Import: `import { applyDeadzone } from "@argus/gameplay"`

### applyQuaternion 

*Since 0.6*

`v` rotated by the quaternion `q` (three.js `Vector3.applyQuaternion`).

`applyQuaternion([0, 0, -1], rot)` is where an entity with rotation `rot` faces.

#### Signature

```ts
export function applyQuaternion(v: Vec3, q: Quat): Vec3
```

Import: `import { applyQuaternion } from "@argus/gameplay"`

### audioBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/audio.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const audioBehavior: Behavior<Record<string, never>, AudioProps>
```

Import: `import { audioBehavior } from "@argus/gameplay"`

### AudioBus 

*Since 0.6*

A bus in the scene's `meta.audio` graph.

Any name the scene declares is valid; the three suggested here are the ones a scene gets when it declares none.

#### Signature

```ts
export type AudioBus = "master" | "sfx" | "music" | (string & {})
```

Import: `import type { AudioBus } from "@argus/api"`

### AudioCue 

*Since 0.6*

Anything an event can be bound to: a sound to play, a bus to ramp, a snapshot to enter, a music layer to change to.

All four are plain JSON, so a scene's `triggers` prop can carry any of them and a designer never writes a line of TypeScript to duck the music when a boss appears.

#### Signature

```ts
export type AudioCue = Cue | MixerCue
```

Import: `import type { AudioCue } from "@argus/gameplay"`

### audioDirector 

*Since 0.6*

The director running on an entity, for tests and for behaviors that want to play something.

#### Signature

```ts
export function audioDirector(ctx: Ctx<any, any>): AudioDirector | null
```

Import: `import { audioDirector } from "@argus/gameplay"`

### AuthorVec3 

*Since 0.6*

Three numbers: a position or a scale.

#### Signature

```ts
export type AuthorVec3 = [number, number, number];
```

Import: `import type { AuthorVec3 } from "@argus/api"`

### axisMagnitude 

*Since 0.6*

Length of a 2D axis, used for deadzones and for "is the stick pushed at all".

#### Signature

```ts
export function axisMagnitude(axis: Vec2): number
```

Import: `import { axisMagnitude } from "@argus/gameplay"`

### BEHAVIOR_ENTRIES 

*Since 0.6*

Module name → source entry.

#### Signature

```ts
export const BEHAVIOR_ENTRIES: Readonly<Record<string, string>> = Object.freeze(
  Object.fromEntries(BEHAVIOR_CATALOGUE.map((e) => [e.module, e.entry])),
)
```

Import: `import { BEHAVIOR_ENTRIES } from "@argus/gameplay"`

### Binding 

*Since 0.6*

What {@link InputState.rebind} accepts.

Three spellings, because three things are natural to write. A single token — `"K"`, or `"pad:south"` / `"mouse:left"` / `"key:Left"` when a name belongs to two devices — replaces the keyboard, gamepad or mouse half. A list of key names replaces the key list, which is what an `axis2` takes four of. An object sets the halves it names and leaves the rest alone, with `null` clearing one.

#### Signature

```ts
export type Binding =
  | string
  | string[]
  | { keys?: string[]; mouse?: MouseBinding | null; gamepad?: GamepadBinding | null }
```

Import: `import type { Binding } from "@argus/api"`

### BlendKind 

*Since 0.6*

How a blend tree turns its parameters into one weight per clip.

#### Signature

```ts
export type BlendKind = "linear" | "cartesian"
```

Import: `import type { BlendKind } from "@argus/gameplay"`

### BOB_DEFAULTS 

*Since 0.6*

#### Signature

```ts
export const BOB_DEFAULTS: Required<BobConfig> = { stride: 2, fullSpeed: 4, camera: 0 }
```

Import: `import { BOB_DEFAULTS } from "@argus/gameplay"`

### bodyRadius 

*Since 0.6*

The radius a ball-shaped entity rolls with: its sphere collider's, else half its box or capsule height, else half a unit mesh — each times the entity's largest scale.

#### Signature

```ts
export function bodyRadius(ctx: Ctx<any, any>): number
```

Import: `import { bodyRadius } from "@argus/gameplay"`

### BUILT_IN_ACTIONS 

*Since 0.6*

The five actions the built-in behaviors use.

Any other string works too; these are just the defaults.

#### Signature

```ts
export const BUILT_IN_ACTIONS = ["move", "look", "jump", "crouch", "interact"] as const
```

Import: `import { BUILT_IN_ACTIONS } from "@argus/gameplay"`

### BUILT_IN_CONTEXTS 

*Since 0.6*

Both built-in context names, in the order the built-in map declares them.

#### Signature

```ts
export const BUILT_IN_CONTEXTS = [GAMEPLAY_CONTEXT, MENU_CONTEXT] as const
```

Import: `import { BUILT_IN_CONTEXTS } from "@argus/gameplay"`

### BuiltInAction 

*Since 0.6*

#### Signature

```ts
export type BuiltInAction = (typeof BUILT_IN_ACTIONS)[number]
```

Import: `import type { BuiltInAction } from "@argus/gameplay"`

### BusPayload 

*Since 0.6*

`data` for a bus event of name `N`: the engine's payload for a name it publishes, `unknown` for anything a behavior emitted — which is what `emit` promises and no more.

A lookup rather than overloads on {@link EventBus}, deliberately. An overload set would stop every existing *implementation* of `EventBus` from satisfying the interface — the mock Ctx in `packages/gameplay` and anything an author writes to test a behavior declare one general `on`, and a single general signature is not assignable to a narrowed overload. This form narrows for a literal name and collapses to exactly the old signature for `string`.

#### Signature

```ts
export type BusPayload<N extends string> = N extends keyof BusEventMap ? BusEventMap[N] : unknown
```

Import: `import type { BusPayload } from "@argus/api"`

### camera2dBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/camera-2d.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const camera2dBehavior: Behavior<Record<string, never>, Camera2DProps>
```

Import: `import { camera2dBehavior } from "@argus/gameplay"`

### camera2dDirector 

*Since 0.6*

The director running a `camera-2d` entity's rig, for tests and for behaviors that want to read it.

#### Signature

```ts
export function camera2dDirector(ctx: { entity: { id: string } }): CameraDirector | null
```

Import: `import { camera2dDirector } from "@argus/gameplay"`

### Camera2DProps 

*Since 0.6*

#### Signature

```ts
export type Camera2DProps = Partial<Follow2DConfig>
```

Import: `import type { Camera2DProps } from "@argus/gameplay"`

### CAMERA_KINDS 

*Since 0.6*

#### Signature

```ts
export const CAMERA_KINDS = ["first-person", "third-person", "fixed", "orbit"] as const
```

Import: `import { CAMERA_KINDS } from "@argus/gameplay"`

### CAMERA_ONLY_TAG 

*Since 0.6*

The tag for collision geometry that is there for the camera alone: an invisible hull that keeps a follow camera out of a cliff, a smoothed shell over rough rocks.

The camera casts against it; ground and movement casts should not, and {@link followGround} and the `path` behavior skip it by default. A tag decides what a *cast* sees, not what the solver collides: a camera-only mesh is still a static collider that blocks the player and dynamic bodies, so keep it where bodies do not go. `docs/API.md` says more.

#### Signature

```ts
export const CAMERA_ONLY_TAG = "camera-only"
```

Import: `import { CAMERA_ONLY_TAG } from "@argus/gameplay"`

### cameraBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/camera.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const cameraBehavior: Behavior<{ yaw?: number; pitch?: number }, CameraProps>
```

Import: `import { cameraBehavior } from "@argus/gameplay"`

### cameraDirector 

*Since 0.6*

The director running on an entity, for tests and for behaviors that want to switch rigs.

#### Signature

```ts
export function cameraDirector(ctx: Ctx<any, any>): CameraDirector | null
```

Import: `import { cameraDirector } from "@argus/gameplay"`

### CameraKind 

*Since 0.6*

#### Signature

```ts
export type CameraKind = "third-person" | "first-person" | "fixed" | "orbit"
```

Import: `import type { CameraKind } from "@argus/api"`

### CameraPose 

*Since 0.6*

What a rig produces each tick, and what is handed to `ctx.camera.set`.

#### Signature

```ts
export type CameraPose = {
  /** Eye position in world space. */
  position: Vec3
  /** The point the eye looks at. */
  target: Vec3
  /** Vertical field of view in **degrees**, matching the scene contract's `camera.fov`. */
  fov: number
  /** Heading in **radians**; 0 looks down -Z, positive turns left. */
  yaw: number
  /**
   * Elevation in **radians**; positive looks up. An orbiting rig resting above its subject therefore has a
   * small negative pitch, because it is looking down at it.
   */
  pitch: number
  /** Eye-to-target distance in metres (0 for first-person). */
  distance: number
}
```

Import: `import type { CameraPose } from "@argus/gameplay"`

### CameraTarget 

*Since 0.6*

Where a rig points.

`null` means the entity the behavior is attached to.

#### Signature

```ts
export type CameraTarget = Vec3 | EntityHandle | string | null
```

Import: `import type { CameraTarget } from "@argus/gameplay"`

### CastShape 

*Since 0.6*

Shape for {@link WorldQuery.shapeCast}.

#### Signature

```ts
export type CastShape = { sphere: number } | { capsule: [radius: number, halfHeight: number] } | { box: Vec3 }
```

Import: `import type { CastShape } from "@argus/api"`

### clamp 

*Since 0.6*

`v` limited to `lo..hi` (three.js `MathUtils.clamp`).

#### Signature

```ts
export function clamp(v: number, lo: number, hi: number): number
```

Import: `import { clamp } from "@argus/gameplay"`

### ColorValue 

*Since 0.6*

A colour as {@link EntityHandle.set} takes it: the scene's own spelling, or numbers.

#### Signature

```ts
export type ColorValue = string | [r: number, g: number, b: number] | [r: number, g: number, b: number, a: number]
```

Import: `import type { ColorValue } from "@argus/api"`

### componentOf 

*Since 0.6*

Read one component off an entity as a plain record, or null when the entity does not carry it.

#### Signature

```ts
export function componentOf(entity: EntityHandle, type: string): Record<string, unknown> | null
```

Import: `import { componentOf } from "@argus/gameplay"`

### CONTROLLER_EVENTS 

*Since 0.6*

#### Signature

```ts
export const CONTROLLER_EVENTS = ["moving", "idle", "jump", "land"] as const
```

Import: `import { CONTROLLER_EVENTS } from "@argus/gameplay"`

### ControllerEvent 

*Since 0.6*

#### Signature

```ts
export type ControllerEvent = (typeof CONTROLLER_EVENTS)[number]
```

Import: `import type { ControllerEvent } from "@argus/gameplay"`

### controllerEvent 

*Since 0.6*

Recognise a controller event by name, tolerating the prefixes an engine build might use (`controller-moving`).

Returns null for anything that is not one of the four.

#### Signature

```ts
export function controllerEvent(name: string): ControllerEvent | null
```

Import: `import { controllerEvent } from "@argus/gameplay"`

### createRig 

*Since 0.6*

Build a rig from a kind plus plain config data (props, a scene `camera` component).

#### Signature

```ts
export function createRig(kind: CameraKind, config: Record<string, unknown> = {}): CameraRig
```

Import: `import { createRig } from "@argus/gameplay"`

### cross 

*Since 0.6*

Cross product `a × b` (right-handed).

#### Signature

```ts
export function cross(a: Vec3, b: Vec3): Vec3
```

Import: `import { cross } from "@argus/gameplay"`

### damp 

*Since 0.6*

Exponentially smooth a scalar toward `target`.

#### Signature

```ts
export function damp(current: number, target: number, lambda: number, dt: number): number
```

Import: `import { damp } from "@argus/gameplay"`

### dampFactor 

*Since 0.6*

Frame-rate independent exponential smoothing: the fraction of the remaining distance to cover this tick for a given half-life-ish `lambda` (larger is snappier).

`lambda <= 0` means "no smoothing", i.e. snap.

#### Signature

```ts
export function dampFactor(lambda: number, dt: number): number
```

Import: `import { dampFactor } from "@argus/gameplay"`

### dampVec3 

*Since 0.6*

Exponentially smooth a point toward `target`.

#### Signature

```ts
export function dampVec3(current: Vec3, target: Vec3, lambda: number, dt: number): Vec3
```

Import: `import { dampVec3 } from "@argus/gameplay"`

### DEFAULT_INPUT_CONFIG 

*Since 0.6*

#### Signature

```ts
export const DEFAULT_INPUT_CONFIG: InputConfig = {
  bindings: IDENTITY_BINDINGS,
  deadzone: 0,
  lookSensitivity: [1, 1],
  invertLook: [false, false],
}
```

Import: `import { DEFAULT_INPUT_CONFIG } from "@argus/gameplay"`

### DEG 

*Since 0.6*

#### Signature

```ts
export const DEG = Math.PI / 180
```

Import: `import { DEG } from "@argus/gameplay"`

### deg 

*Since 0.6*

Radians to degrees.

#### Signature

```ts
export function deg(radians: number): number
```

Import: `import { deg } from "@argus/gameplay"`

### distanceXZ 

*Since 0.6*

Distance between two places on the ground plane, height ignored; an entity is read at its world position.

#### Signature

```ts
export function distanceXZ(a: Target, b: Target): number
```

Import: `import { distanceXZ } from "@argus/gameplay"`

### dot 

*Since 0.6*

Dot product.

#### Signature

```ts
export function dot(a: Vec3, b: Vec3): number
```

Import: `import { dot } from "@argus/gameplay"`

### Ease 

*Since 0.6*

#### Signature

```ts
export type Ease = "linear" | "smoothstep" | "ease-in" | "ease-out"
```

Import: `import type { Ease } from "@argus/gameplay"`

### ease 

*Since 0.6*

#### Signature

```ts
export function ease(t: number, kind: Ease): number
```

Import: `import { ease } from "@argus/gameplay"`

### easeValue 

*Since 0.6*

An easing curve on 0..1.

#### Signature

```ts
export function easeValue(ease: ShotEase, u: number): number
```

Import: `import { easeValue } from "@argus/gameplay"`

### extendBehavior 

*Since 0.6*

`base` with the hooks in `overrides` put in place of its own, and every other hook of `base` kept.

`ts import { extendBehavior, playerBehavior } from "@argus/gameplay" export default extendBehavior(playerBehavior, { update(ctx, dt) { if (ctx.state.dead) return // skip the base: a dead player does not move playerBehavior.update?.(ctx, dt) // … this game's own per-tick work }, }) ```

#### Signature

```ts
export function extendBehavior<S extends Record<string, any> = Record<string, any>, P extends Record<string, any> = Record<string, any>>(base: Behavior<any, any>, overrides: Behavior<S, P>): Behavior<S, P>
```

Import: `import { extendBehavior } from "@argus/gameplay"`

### FALLBACK_BLEND 

*Since 0.6*

Default blend, in seconds, for a fallback transition (an authored transition uses its own `blend`).

#### Signature

```ts
export const FALLBACK_BLEND = 0.15
```

Import: `import { FALLBACK_BLEND } from "@argus/gameplay"`

### FIRST_PERSON_DEFAULTS 

*Since 0.6*

#### Signature

```ts
export const FIRST_PERSON_DEFAULTS: FirstPersonConfig = {
  target: null,
  eyeHeight: 1.7,
  eyeOffset: [0, 0, 0],
  pitchMinDeg: -85,
  pitchMaxDeg: 85,
  yawSpeedDeg: 180,
  pitchSpeedDeg: 120,
  yaw: 0,
  pitch: 0,
}
```

Import: `import { FIRST_PERSON_DEFAULTS } from "@argus/gameplay"`

### FIXED_DEFAULTS 

*Since 0.6*

#### Signature

```ts
export const FIXED_DEFAULTS: FixedConfig = {
  position: [0, 3, 6],
  lookAt: null,
  fov: 55,
}
```

Import: `import { FIXED_DEFAULTS } from "@argus/gameplay"`

### flatForwardFromYaw 

*Since 0.6*

The forward direction flattened onto the ground plane, for movement that ignores where the camera looks.

#### Signature

```ts
export function flatForwardFromYaw(yaw: number): Vec3
```

Import: `import { flatForwardFromYaw } from "@argus/gameplay"`

### FOLLOW_2D_DEFAULTS 

*Since 0.6*

#### Signature

```ts
export const FOLLOW_2D_DEFAULTS: Follow2DConfig = {
  target: null,
  offset: [0, 0],
  deadzone: [0, 0],
  lookAhead: [0, 0],
  lookAheadMinSpeed: 0.5,
  lookAheadLambda: 3,
  followLambda: 8,
  bounds: null,
  z: 10,
  pixelScale: null,
}
```

Import: `import { FOLLOW_2D_DEFAULTS } from "@argus/gameplay"`

### ForceSpace 

*Since 0.6*

The axes a {@link RigidBody} push is written in.

`"world"` (the default) is the world's. `"local"` is the body's own: its rotation, and for a point its origin (the entity's) — metres along the body's axes, **not** scaled by the entity's scale, so a rotor 0.2 m out on a model scaled ×10 is at `[2, 0, 0]`.

#### Signature

```ts
export type ForceSpace = "world" | "local"
```

Import: `import type { ForceSpace } from "@argus/api"`

### forwardFromYawPitch 

*Since 0.6*

The unit forward direction for a yaw/pitch pair.

`yaw = 0, pitch = 0` looks down -Z; positive yaw turns left (toward -X), positive pitch looks up.

#### Signature

```ts
export function forwardFromYawPitch(yaw: number, pitch: number): Vec3
```

Import: `import { forwardFromYawPitch } from "@argus/gameplay"`

### GamepadBinding 

*Since 0.6*

The gamepad source an action reads, in the SDL layout.

Face buttons are named by POSITION, not by letter, so one map fits an Xbox pad, a DualSense and a Switch pad: `south` is A / Cross / B.

#### Signature

```ts
export type GamepadBinding =
  | "left-stick"
  | "right-stick"
  | "dpad"
  | "south"
  | "east"
  | "north"
  | "west"
  | "left-bumper"
  | "right-bumper"
  | "left-trigger"
  | "right-trigger"
  | "left-thumb"
  | "right-thumb"
  | "select"
  | "start"
  | "mode"
  | "dpad-up"
  | "dpad-down"
  | "dpad-left"
  | "dpad-right"
```

Import: `import type { GamepadBinding } from "@argus/api"`

### gameplay.CameraKind 

*Since 0.6*

#### Signature

```ts
export type CameraKind = (typeof CAMERA_KINDS)[number]
```

Import: `import type { gameplay.CameraKind } from "@argus/gameplay"`

### gameplay.CameraParams 

*Since 0.6*

Params as sent to `ctx.camera.set`: the pose, plus `blend` while a transition is in flight.

Spelled out rather than `CameraPose & { blend }` so it keeps the implicit index signature that makes it assignable to the `Record<string, unknown>` the Ctx method takes.

#### Signature

```ts
export type CameraParams = {
  position: Vec3
  target: Vec3
  fov: number
  yaw: number
  pitch: number
  distance: number
  /** 0..1 progress of a transition between rigs; absent when no transition is running. */
  blend?: number
}
```

Import: `import type { gameplay.CameraParams } from "@argus/gameplay"`

### gameplay.ParticlePreset 

*Since 0.6*

#### Signature

```ts
export type ParticlePreset = (typeof PARTICLE_PRESETS)[number]
```

Import: `import type { gameplay.ParticlePreset } from "@argus/gameplay"`

### GAMEPLAY_CONTEXT 

*Since 0.6*

The context names the built-in map ships, mirrored from `packages/contract/src/input.ts`.

Behaviors use them as defaults — `player` switches to `MENU_CONTEXT` when a menu opens — so a scene that keeps the built-in map needs no configuration, and a scene that renames its contexts says so in props.

#### Signature

```ts
export const GAMEPLAY_CONTEXT = "gameplay"
```

Import: `import { GAMEPLAY_CONTEXT } from "@argus/gameplay"`

### goalIdOf 

*Since 0.6*

Pull the goal id out of the shapes a `goal-reached` payload plausibly takes.

#### Signature

```ts
export function goalIdOf(ev: GameEvent): string | null
```

Import: `import { goalIdOf } from "@argus/gameplay"`

### groundingBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/grounding.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const groundingBehavior: Behavior<Record<string, never>, GroundingProps>
```

Import: `import { groundingBehavior } from "@argus/gameplay"`

### groundingState 

*Since 0.6*

This entity's grounding state, for tests and for a debug overlay.

#### Signature

```ts
export function groundingState(ctx: Ctx<any, any>): GroundingState | null
```

Import: `import { groundingState } from "@argus/gameplay"`

### groundStep 

*Since 0.6*

One tick of ground-following, without a `Ctx`: `position` is where the body is after this tick's move across the ground, `prev` what the last tick returned (null on the first), `body` the id so the cast passes through it.

{@link followGround} is this with the entity's own state.

#### Signature

```ts
export function groundStep(world: Pick<WorldQuery, "raycast" | "shapeCast">, body: string | null, position: Vec3, prev: GroundFollow | null, dt: number, opts: FollowGroundOptions = {}): GroundFollow
```

Import: `import { groundStep } from "@argus/gameplay"`

### HostEvent 

*Since 0.6*

#### Signature

```ts
export type HostEvent = EmitEvent | ScriptErrorEvent
```

Import: `import type { HostEvent } from "@argus/api"`

### HUD_ELEMENTS 

*Since 0.6*

#### Signature

```ts
export const HUD_ELEMENTS = ["objective", "prompt", "timer", "score", "custom"] as const
```

Import: `import { HUD_ELEMENTS } from "@argus/gameplay"`

### hudBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/hud.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const hudBehavior: Behavior<Record<string, never>, HudProps>
```

Import: `import { hudBehavior } from "@argus/gameplay"`

### hudController 

*Since 0.6*

The controller running on an entity, for tests and for behaviors that want to set fields.

#### Signature

```ts
export function hudController(ctx: Ctx<any, any>): HudController | null
```

Import: `import { hudController } from "@argus/gameplay"`

### HudElement 

*Since 0.6*

#### Signature

```ts
export type HudElement = (typeof HUD_ELEMENTS)[number]
```

Import: `import type { HudElement } from "@argus/gameplay"`

### HudField 

*Since 0.6*

Built-in HUD fields; any other string is a custom overlay element bound in the scene.

#### Signature

```ts
export type HudField = "objective" | "prompt" | "timer" | "score" | (string & {})
```

Import: `import type { HudField } from "@argus/api"`

### HUMANOID_FALLBACK 

*Since 0.6*

Candidate state names per event, in preference order, for an animator with no transition table.

#### Signature

```ts
export const HUMANOID_FALLBACK: Readonly<Record<ControllerEvent, readonly string[]>> = {
  moving: ["walk", "walking", "move", "moving", "run"],
  idle: ["idle", "stand", "idling"],
  jump: ["jump", "jumping", "jump-start", "air"],
  land: ["land", "landing", "idle"],
}
```

Import: `import { HUMANOID_FALLBACK } from "@argus/gameplay"`

### IDENTITY_BINDINGS 

*Since 0.6*

The identity map: every name reads the `ctx.input` action of the same name.

#### Signature

```ts
export const IDENTITY_BINDINGS: Bindings = { axes: {}, buttons: {} }
```

Import: `import { IDENTITY_BINDINGS } from "@argus/gameplay"`

### InputKind 

*Since 0.6*

What an action produces.

#### Signature

```ts
export type InputKind = "axis2" | "axis1" | "button"
```

Import: `import type { InputKind } from "@argus/gameplay"`

### instanceStore 

*Since 0.6*

#### Signature

```ts
export function instanceStore<T>(): InstanceStore<T>
```

Import: `import { instanceStore } from "@argus/gameplay"`

### integerPixelScale 

*Since 0.6*

The largest whole-number scale at which `minHeight` units of art `texelsPerUnit` texels a unit fit in `pixelHeight` pixels; 1 when not even that fits, so the view then shows less than `minHeight`.

#### Signature

```ts
export function integerPixelScale(pixelHeight: number, texelsPerUnit: number, minHeight: number): IntegerLens
```

Import: `import { integerPixelScale } from "@argus/gameplay"`

### isCameraKind 

*Since 0.6*

#### Signature

```ts
export function isCameraKind(v: string): v is CameraKind
```

Import: `import { isCameraKind } from "@argus/gameplay"`

### isParticlePreset 

*Since 0.6*

#### Signature

```ts
export function isParticlePreset(v: string): v is ParticlePreset
```

Import: `import { isParticlePreset } from "@argus/gameplay"`

### isSceneInputDoc 

*Since 0.6*

Is this a well-formed `meta.input` document?

Used before reading one out of props.

#### Signature

```ts
export function isSceneInputDoc(value: unknown): value is SceneInputDoc
```

Import: `import { isSceneInputDoc } from "@argus/gameplay"`

### JointKind 

*Since 0.6*

{@link Joint.kind}: what the joint leaves free.

#### Signature

```ts
export type JointKind = "fixed" | "revolute" | "prismatic"
```

Import: `import type { JointKind } from "@argus/api"`

### JointMotorMode 

*Since 0.6*

What a {@link Joint} motor drives towards: a speed, or a place on the free axis.

#### Signature

```ts
export type JointMotorMode = "velocity" | "position"
```

Import: `import type { JointMotorMode } from "@argus/api"`

### labelBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/label.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const labelBehavior: Behavior<Record<string, never>, LabelProps>
```

Import: `import { labelBehavior } from "@argus/gameplay"`

### labelDirector 

*Since 0.6*

The director running on an entity, for tests and for behaviors that want to place a label.

#### Signature

```ts
export function labelDirector(ctx: Ctx<any, any>): LabelDirector | null
```

Import: `import { labelDirector } from "@argus/gameplay"`

### length 

*Since 0.6*

Length of a vector.

#### Signature

```ts
export function length(a: Vec3): number
```

Import: `import { length } from "@argus/gameplay"`

### lerp 

*Since 0.6*

Linear interpolation from `a` to `b` by `t` (not clamped): three.js `MathUtils.lerp`.

#### Signature

```ts
export function lerp(a: number, b: number, t: number): number
```

Import: `import { lerp } from "@argus/gameplay"`

### lerpAngle 

*Since 0.6*

Interpolate between two angles the short way round.

#### Signature

```ts
export function lerpAngle(from: number, to: number, t: number): number
```

Import: `import { lerpAngle } from "@argus/gameplay"`

### lerpVec3 

*Since 0.6*

#### Signature

```ts
export function lerpVec3(a: Vec3, b: Vec3, t: number): Vec3
```

Import: `import { lerpVec3 } from "@argus/gameplay"`

### locomotionBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/locomotion.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const locomotionBehavior: Behavior<Record<string, never>, LocomotionProps>
```

Import: `import { locomotionBehavior } from "@argus/gameplay"`

### locomotionState 

*Since 0.6*

This entity's locomotion state, for tests and for behaviors that want the step count.

#### Signature

```ts
export function locomotionState(ctx: Ctx<any, any>): LocomotionState | null
```

Import: `import { locomotionState } from "@argus/gameplay"`

### lookRotation 

*Since 0.6*

The rotation whose forward (-Z) points along `dir`, keeping `up` (default +Y) as near up as it can: the familiar look-rotation, on Argus's axes.

A zero `dir` gives the identity. Assign it to `entity.rotation`; for yaw only, flatten `dir` first or use {@link yawTo} with {@link quatFromYaw}.

#### Signature

```ts
export function lookRotation(dir: Vec3, up: Vec3 = [0, 1, 0]): Quat
```

Import: `import { lookRotation } from "@argus/gameplay"`

### MENU_CONTEXT 

*Since 0.6*

The context the built-in map puts menu navigation in.

#### Signature

```ts
export const MENU_CONTEXT = "menu"
```

Import: `import { MENU_CONTEXT } from "@argus/gameplay"`

### MISSING_STRING_EVENT 

*Since 0.6*

The event name the critic listens for.

#### Signature

```ts
export const MISSING_STRING_EVENT = "missing-string"
```

Import: `import { MISSING_STRING_EVENT } from "@argus/gameplay"`

### missingText 

*Since 0.6*

What an unresolved key renders as.

#### Signature

```ts
export function missingText(key: string): string
```

Import: `import { missingText } from "@argus/gameplay"`

### MixerCue 

*Since 0.6*

A cue that moves the mixer rather than starting a sound.

#### Signature

```ts
export type MixerCue = BusCue | SnapshotCue | MusicCue
```

Import: `import type { MixerCue } from "@argus/gameplay"`

### MouseBinding 

*Since 0.6*

The mouse source an action reads; `delta` and `wheel` are axes, the rest are buttons.

#### Signature

```ts
export type MouseBinding = "delta" | "wheel" | "left" | "right" | "middle"
```

Import: `import type { MouseBinding } from "@argus/api"`

### MoveBasis 

*Since 0.6*

Which heading "stick up" means: away from the drawn view, the world's -Z, or where the entity faces.

#### Signature

```ts
export type MoveBasis = "camera" | "world" | "entity"
```

Import: `import type { MoveBasis } from "@argus/gameplay"`

### moveDirection 

*Since 0.6*

Turn a 2D move axis (`[strafe, forward]`, each -1..1) into a world direction relative to `yaw`.

The result is normalised, so diagonal input is not faster than straight input; a zero axis gives `[0, 0, 0]`, which callers treat as "no movement this tick".

#### Signature

```ts
export function moveDirection(axis: Vec2, yaw: number): Vec3
```

Import: `import { moveDirection } from "@argus/gameplay"`

### moveInput 

*Since 0.6*

The `move` axis (or `action`) as a world direction on the ground plane, y 0: stick up is away from the camera with the default `"camera"` basis (the frame an `inputBasis: "camera"` controller uses, `ctx.camera.viewYaw`), world -Z with `"world"`, and the entity's own forward with `"entity"`.

The length is the stick's, capped at 1, so half a push walks at half speed and diagonals are not faster: `ctx.controller.move(moveInput(ctx), speed)` moves at up to `speed` m/s. `[0, 0, 0]` with no input (an entity that is not the player has `ctx.input === null`).

#### Signature

```ts
export function moveInput(ctx: Ctx, basis: MoveBasis = "camera", action = "move"): Vec3
```

Import: `import { moveInput } from "@argus/gameplay"`

### moveTowards 

*Since 0.6*

`current` moved toward `target` by at most `maxDelta`, never past it (unitless).

A constant-rate approach, where {@link damp} eases.

#### Signature

```ts
export function moveTowards<T extends number | Vec3>(current: T, target: T, maxDelta: number): T
```

Import: `import { moveTowards } from "@argus/gameplay"`

### nearPlaneRadius 

*Since 0.6*

Radius of the smallest sphere around the eye that holds the whole near plane, for a vertical field of view in degrees: a sweep at least this wide cannot leave a corner of the near plane inside a wall.

#### Signature

```ts
export function nearPlaneRadius(fovDeg: number, near = CAMERA_NEAR, aspect = WIDEST_ASPECT): number
```

Import: `import { nearPlaneRadius } from "@argus/gameplay"`

### NO_RIG_INPUT 

*Since 0.6*

#### Signature

```ts
export const NO_RIG_INPUT: RigInput = { look: [0, 0], zoom: 0 }
```

Import: `import { NO_RIG_INPUT } from "@argus/gameplay"`

### normalize 

*Since 0.6*

Unit vector, or `[0, 0, 0]` for a zero-length input (never NaN).

#### Signature

```ts
export function normalize(a: Vec3): Vec3
```

Import: `import { normalize } from "@argus/gameplay"`

### ORBIT_DEFAULTS 

*Since 0.6*

#### Signature

```ts
export const ORBIT_DEFAULTS: OrbitConfig = {
  target: null,
  pivotOffset: [0, 0, 0],
  distance: 3,
  minDistance: 1,
  maxDistance: 10,
  pitchMinDeg: -80,
  pitchMaxDeg: 20,
  orbitSpeedDeg: 120,
  pitchSpeedDeg: 90,
  zoomSpeed: 3,
  autoRotateDeg: 0,
  autoRotateDelay: 2,
  fov: 45,
  yaw: 0,
  // A turntable looks slightly down at what it is orbiting.
  pitch: rad(-20),
}
```

Import: `import { ORBIT_DEFAULTS } from "@argus/gameplay"`

### orbitShot 

*Since 0.6*

A shot that circles a point: keys along the arc, linear between them so the speed is even.

The flythrough a trailer opens on, for any scene with a centre and a size.

#### Signature

```ts
export function orbitShot(spec: OrbitShotSpec): Shot
```

Import: `import { orbitShot } from "@argus/gameplay"`

### PARTICLE_PRESETS 

*Since 0.6*

The eight built-in particle presets, in `@argus/contract` order.

#### Signature

```ts
export const PARTICLE_PRESETS = ["smoke", "fire", "sparks", "dust", "steam", "drips", "debris", "glow"] as const
```

Import: `import { PARTICLE_PRESETS } from "@argus/gameplay"`

### particleDirector 

*Since 0.6*

The director running on an entity, for tests and for behaviors that want to emit.

#### Signature

```ts
export function particleDirector(ctx: Ctx<any, any>): ParticleDirector | null
```

Import: `import { particleDirector } from "@argus/gameplay"`

### particleParams 

*Since 0.6*

The preset's parameters with overrides applied.

Never returns the table's own object.

#### Signature

```ts
export function particleParams(preset: ParticlePreset, overrides: Partial<ParticleParams> = {}): ParticleParams
```

Import: `import { particleParams } from "@argus/gameplay"`

### ParticlePreset 

*Since 0.6*

The eight built-in particle presets; mirrors `particles.preset` in the scene contract (@argus/contract).

#### Signature

```ts
export type ParticlePreset = "smoke" | "fire" | "sparks" | "dust" | "steam" | "drips" | "debris" | "glow"
```

Import: `import type { ParticlePreset } from "@argus/api"`

### particlesBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/particles.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const particlesBehavior: Behavior<Record<string, never>, ParticlesProps>
```

Import: `import { particlesBehavior } from "@argus/gameplay"`

### pathBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/path.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const pathBehavior: Behavior<PathState, PathProps>
```

Import: `import { pathBehavior } from "@argus/gameplay"`

### pathLength 

*Since 0.6*

The path's length in metres, with the closing chord when `closed`.

#### Signature

```ts
export function pathLength(points: readonly Vec3[], closed = false): number
```

Import: `import { pathLength } from "@argus/gameplay"`

### playerBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/player.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const playerBehavior: Behavior<PlayerState, PlayerProps>
```

Import: `import { playerBehavior } from "@argus/gameplay"`

### playerInstance 

*Since 0.6*

Exposed for tests and for behaviors that want the same mapping the player uses.

#### Signature

```ts
export function playerInstance(ctx: Ctx<PlayerState, PlayerProps>): Runtime | null
```

Import: `import { playerInstance } from "@argus/gameplay"`

### pointAlong 

*Since 0.6*

The point `s` metres along the chords.

#### Signature

```ts
export function pointAlong(points: readonly Vec3[], s: number, closed = false): Vec3
```

Import: `import { pointAlong } from "@argus/gameplay"`

### quatFromAxisAngle 

*Since 0.6*

The rotation by `angle` radians about `axis` (normalised here; a zero axis gives the identity).

#### Signature

```ts
export function quatFromAxisAngle(axis: Vec3, angle: number): Quat
```

Import: `import { quatFromAxisAngle } from "@argus/gameplay"`

### quatFromYaw 

*Since 0.6*

The rotation that turns by `yaw` radians about +Y and nothing else: 0 faces -Z, positive turns left.

#### Signature

```ts
export function quatFromYaw(yaw: number): Quat
```

Import: `import { quatFromYaw } from "@argus/gameplay"`

### quatMultiply 

*Since 0.6*

`a * b`: the rotation `b` followed by `a`.

#### Signature

```ts
export function quatMultiply(a: Quat, b: Quat): Quat
```

Import: `import { quatMultiply } from "@argus/gameplay"`

### quatNormalize 

*Since 0.6*

Unit length, or the identity for a zero quaternion, so repeated multiplication cannot drift.

#### Signature

```ts
export function quatNormalize(q: Quat): Quat
```

Import: `import { quatNormalize } from "@argus/gameplay"`

### rad 

*Since 0.6*

Degrees to radians.

#### Signature

```ts
export function rad(degrees: number): number
```

Import: `import { rad } from "@argus/gameplay"`

### readAnimator 

*Since 0.6*

The entity's `animator` component, or null.

States and transitions are copied, not aliased.

#### Signature

```ts
export function readAnimator(entity: EntityHandle): AnimatorComponent | null
```

Import: `import { readAnimator } from "@argus/gameplay"`

### readAudio 

*Since 0.6*

The entity's `audio` component with its defaults filled in, or null.

#### Signature

```ts
export function readAudio(entity: EntityHandle): AudioComponent | null
```

Import: `import { readAudio } from "@argus/gameplay"`

### readController 

*Since 0.6*

The entity's `controller` component with its defaults filled in, or null.

#### Signature

```ts
export function readController(entity: EntityHandle): ControllerComponent | null
```

Import: `import { readController } from "@argus/gameplay"`

### readGoal 

*Since 0.6*

The entity's `goal` component, or null.

#### Signature

```ts
export function readGoal(entity: EntityHandle): GoalComponent | null
```

Import: `import { readGoal } from "@argus/gameplay"`

### readLabel 

*Since 0.6*

The entity's `label` component, or null.

#### Signature

```ts
export function readLabel(entity: EntityHandle): LabelComponent | null
```

Import: `import { readLabel } from "@argus/gameplay"`

### readParticles 

*Since 0.6*

The entity's `particles` component, or null.

#### Signature

```ts
export function readParticles(entity: EntityHandle): ParticlesComponent | null
```

Import: `import { readParticles } from "@argus/gameplay"`

### resolveStrings 

*Since 0.6*

The string table a behavior should use, plus the `missing-string` wiring.

Sources, in order: an explicit table, `ctx.strings` if the host provides it, `ctx.props.strings`, then an empty table.

#### Signature

```ts
export function resolveStrings(ctx: Ctx, override?: Strings | Record<string, string>): Strings
```

Import: `import { resolveStrings } from "@argus/gameplay"`

### rightFromYaw 

*Since 0.6*

The unit direction to the camera's right for a yaw (the pitch does not tilt the rig).

#### Signature

```ts
export function rightFromYaw(yaw: number): Vec3
```

Import: `import { rightFromYaw } from "@argus/gameplay"`

### RigidBodyKind 

*Since 0.6*

{@link RigidBody.kind}: how the solver treats the body.

Only a dynamic one is moved by a force.

#### Signature

```ts
export type RigidBodyKind = "dynamic" | "kinematic" | "static"
```

Import: `import type { RigidBodyKind } from "@argus/api"`

### routeControllerEvent 

*Since 0.6*

Route a game event to the machine when it is one of the controller's four and it is about this entity.

Events raised by the engine carry `by: null`; events emitted by another entity's behavior are ignored.

#### Signature

```ts
export function routeControllerEvent(machine: AnimatorMachine, ev: GameEvent, animator: Animator | null, selfId: string, fallbackBlend = FALLBACK_BLEND): string | null
```

Import: `import { routeControllerEvent } from "@argus/gameplay"`

### scale 

*Since 0.6*

`a * s`, a new tuple.

#### Signature

```ts
export function scale(a: Vec3, s: number): Vec3
```

Import: `import { scale } from "@argus/gameplay"`

### ShaderParamValue 

*Since 0.6*

A shader param value: a number, a boolean, an array of numbers (a vector or a linear colour), or a `"#RRGGBB"` colour.

#### Signature

```ts
export type ShaderParamValue = number | boolean | number[] | string
```

Import: `import type { ShaderParamValue } from "@argus/api"`

### shotDuration 

*Since 0.6*

A shot's length: its `duration`, else its last key's time, else one second.

#### Signature

```ts
export function shotDuration(shot: Shot): number
```

Import: `import { shotDuration } from "@argus/gameplay"`

### ShotEase 

*Since 0.6*

How a value travels from the previous key to this one.

#### Signature

```ts
export type ShotEase = "linear" | "in" | "out" | "inOut" | "hold"
```

Import: `import type { ShotEase } from "@argus/gameplay"`

### shotList 

*Since 0.6*

The list running on an entity, for tests and for behaviors that want its length.

#### Signature

```ts
export function shotList(ctx: Ctx<any, any>): ShotList | null
```

Import: `import { shotList } from "@argus/gameplay"`

### shotListProblems 

*Since 0.6*

Checks a shot list, so a typo in a scene's props is one clear message rather than a camera at NaN.

Answers the problems found; an empty array is a list that samples.

#### Signature

```ts
export function shotListProblems(shots: unknown): string[]
```

Import: `import { shotListProblems } from "@argus/gameplay"`

### shotSample 

*Since 0.6*

Where the `shots` behavior on this entity says the camera is now, or null before it starts.

#### Signature

```ts
export function shotSample(ctx: Ctx<ShotsState, ShotsProps>): ShotSample | null
```

Import: `import { shotSample } from "@argus/gameplay"`

### shotsBehavior 

*Since 0.6*

The built-in behaviour packages/gameplay/src/behaviors/shots.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it.

#### Signature

```ts
const shotsBehavior: Behavior<ShotsState, ShotsProps>
```

Import: `import { shotsBehavior } from "@argus/gameplay"`

### SkyKind 

*Since 0.6*

#### Signature

```ts
export type SkyKind = "procedural" | "hdr" | "color" | "atmosphere"
```

Import: `import type { SkyKind } from "@argus/api"`

### SpawnOptions 

*Since 0.6*

Options for {@link WorldQuery.spawn}: exactly one of `like` (a live entity to copy) or `prefab` (a project prefab file to spawn a copy of).

Both, or neither, throws.

#### Signature

```ts
export type SpawnOptions = SpawnLikeOptions | SpawnPrefabOptions
```

Import: `import type { SpawnOptions } from "@argus/api"`

### sub 

*Since 0.6*

`a - b`, a new tuple.

#### Signature

```ts
export function sub(a: Vec3, b: Vec3): Vec3
```

Import: `import { sub } from "@argus/gameplay"`

### Target 

*Since 0.6*

A point in world space, or an entity, which is read at its `worldPosition` (through its parents).

#### Signature

```ts
export type Target = Vec3 | EntityHandle
```

Import: `import type { Target } from "@argus/api"`

### targetEntity 

*Since 0.6*

Resolve a target spec to an entity, or null when it names a point (or names nothing that exists).

#### Signature

```ts
export function targetEntity(ctx: Ctx, target: CameraTarget): EntityHandle | null
```

Import: `import { targetEntity } from "@argus/gameplay"`

### targetHeading 

*Since 0.6*

The way a target faces, as a yaw (0 down -Z, positive turning left), or null for a point, which faces nowhere.

Read from the entity's rotation — the way it visibly faces, which the `player` behaviour turns with `lookAt` and a moving platform turns with it — as the engine rig does.

#### Signature

```ts
export function targetHeading(ctx: Ctx, target: CameraTarget): number | null
```

Import: `import { targetHeading } from "@argus/gameplay"`

### targetPoint 

*Since 0.6*

Resolve a target spec to a world-space point.

A dangling entity id falls back to the behavior's entity.

#### Signature

```ts
export function targetPoint(ctx: Ctx, target: CameraTarget): Vec3
```

Import: `import { targetPoint } from "@argus/gameplay"`

### TargetResolver 

*Since 0.6*

Resolves an entity id to a world point, or null when there is no such entity.

#### Signature

```ts
export type TargetResolver = (id: string) => Vec3 | null
```

Import: `import type { TargetResolver } from "@argus/gameplay"`

### THIRD_PERSON_DEFAULTS 

*Since 0.6*

#### Signature

```ts
export const THIRD_PERSON_DEFAULTS: ThirdPersonConfig = {
  target: null,
  distance: 4,
  minDistance: 0.6,
  maxDistance: 8,
  pivotOffset: [0, 1.6, 0],
  shoulderOffset: 0,
  pitchMinDeg: -70,
  pitchMaxDeg: 35,
  yawSpeedDeg: 180,
  pitchSpeedDeg: 120,
  zoomSpeed: 4,
  collisionRadius: 0.25,
  collisionBuffer: 0.1,
  followLambda: 14,
  distanceLambda: 4,
  fov: 60,
  yaw: 0,
  // Slightly negative: the rig rests a little above the pivot, looking down at it.
  pitch: rad(-10),
  recenterDelay: null,
  recenterSpeedDeg: 90,
  lookAhead: 0,
  lookAheadMax: 2,
  lookAheadLambda: 3,
  fadeStart: null,
  fadeFull: null,
  recoverRate: null,
  collapseShoulder: null,
  avoidWalls: false,
}
```

Import: `import { THIRD_PERSON_DEFAULTS } from "@argus/gameplay"`

### tilemapBounds 

*Since 0.6*

A `tilemap` entity's extent in world units: its widest layer's columns and tallest layer's rows times `cellSize` (default the tile's pixels at 100 a unit) times the entity's scale, from its origin, which is the top-left corner of cell (0, 0).

Null when the entity has no tilemap. An unrotated tilemap is assumed.

#### Signature

```ts
export function tilemapBounds(entity: EntityHandle): Rect2 | null
```

Import: `import { tilemapBounds } from "@argus/gameplay"`

### turnTowards 

*Since 0.6*

The yaw `current` turned toward `target` by at most `maxStep` radians, the short way round; `target` once within reach.

Radians, positive left (unlike the degree-based `MoveTowardsAngle` of other engines).

#### Signature

```ts
export function turnTowards(current: number, target: number, maxStep: number): number
```

Import: `import { turnTowards } from "@argus/gameplay"`

### UiReadable 

*Since 0.6*

The properties {@link UiHandle.get} reads (U4).

#### Signature

```ts
export type UiReadable = "value" | "length" | "caret" | "selection" | "composition" | "text"
```

Import: `import type { UiReadable } from "@argus/api"`

### UiRole 

*Since 0.6*

A node's role in a described screen.

Mirrors `argus_ui::Role`.

#### Signature

```ts
export type UiRole =
  | "container"
  | "text"
  | "image"
  | "button"
  | "list"
  | "list-row"
  | "dialog"
  | "toast"
  /** An editable run of text with a caret and a selection (U4). Focusable by default. */
  | "text-field"
```

Import: `import type { UiRole } from "@argus/api"`

### v3 

*Since 0.6*

A `Vec3` tuple, `[0, 0, 0]` by default.

Annotate vectors as `Vec3`, not `number[]`.

#### Signature

```ts
export function v3(x = 0, y = 0, z = 0): Vec3
```

Import: `import { v3 } from "@argus/gameplay"`

### Vec2 

*Since 0.6*

`[x, y]` for 2D input axes.

#### Signature

```ts
export type Vec2 = [number, number]
```

Import: `import type { Vec2 } from "@argus/api"`

### worldPoint 

*Since 0.6*

A place as a point: a `Vec3` as given, an entity handle as its `worldPosition` — the same conversion the engine applies to every `Target` parameter, so a parented entity is where it is in the world.

#### Signature

```ts
export function worldPoint(target: Target): Vec3
```

Import: `import { worldPoint } from "@argus/gameplay"`

### wrapAngle 

*Since 0.6*

Wrap an angle to (-pi, pi].

#### Signature

```ts
export function wrapAngle(a: number): number
```

Import: `import { wrapAngle } from "@argus/gameplay"`

### yawFromForward 

*Since 0.6*

The yaw that looks along `dir` (its Y component is ignored).

#### Signature

```ts
export function yawFromForward(dir: Vec3): number
```

Import: `import { yawFromForward } from "@argus/gameplay"`

### yawOf 

*Since 0.6*

The heading of a rotation, radians: the yaw its forward (-Z) points along on the ground plane, as three.js's `rotation.y` reads for an object turned only about Y.

0 faces -Z, positive is to the left. Pitch and roll are ignored; a rotation looking straight up or down takes its heading from its right axis.

#### Signature

```ts
export function yawOf(q: Quat): number
```

Import: `import { yawOf } from "@argus/gameplay"`

### yawTo 

*Since 0.6*

The yaw that faces from `from` toward `to` on the ground plane (height ignored); 0 when they coincide.

Either may be an entity, which is read at its world position.

#### Signature

```ts
export function yawTo(fromTarget: Target, toTarget: Target): number
```

Import: `import { yawTo } from "@argus/gameplay"`