# Script API > Talos 0.7 469 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. | | AfterOptions | Options of {@link TimeInfo.after}. | | 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 | | | AnimatorWarpOptions | What {@link Animator.warp} aims the playing state's root motion at. | | AnimEvent | | | AnimIk | One two-bone IK chain: a leg or an arm, solved so its end bone sits on a point. | | AnimLayer | A second playback over the base animator's, on some of the bones. | | 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`). | | BannerShow | How one showing of a banner goes. | | Batch | The instances an `updateAll` steps: index `k` is one instance, the same `k` in each list. | | 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. | | BonePose | Where a bone is, as {@link Animator.bone} reports it. | | 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`. | | BusUiFocused | Payload of the engine-published `"ui-focused"` event: focus moved on a screen — the arrow keys or the pad, Tab, a click on a focusable node, or the first focus a screen takes when it comes up. | | BusVehicleRecovered | Payload of the engine-published `"vehicle-recovered"` event: a vehicle with a `recovery` block was flipped, stuck, fell out of the world, drowned or broke the physics, and the engine put it back where it can go on (its last good spot, the nearest road, or upright where it was). | | 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}. | | CameraPickOptions | Options for `ctx.camera.pick`: the raycast options, plus the view, a range and a ground plane. | | CameraProps | | | CameraRig | | | CameraRigSettings | | | CastOptions | Options for {@link WorldQuery.raycast} and {@link WorldQuery.shapeCast}. | | Collision | Payload of {@link Behavior.onCollision} and {@link Behavior.onCollisionStay}: one point of the contact, the one that carried the most impulse. | | 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. | | DebugHandle | `ctx.debug`: diagnostics a behavior reads for itself, never for gameplay. | | 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, its end bone, and where it sits in the character's own frame. | | FrameAccel | The carrier's acceleration along its own axes, m/s²: forward (its -Z), right (+X), up (+Y). | | FrameParams | {@link ViewsHandle.frame}'s options. | | 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 | | | HudFieldOptions | How one stock-HUD field reads (`ctx.hud.set(field, value, options)`). | | HudHandle | HUD overlay. | | HudOptions | | | HudProps | | | InputActionDoc | One action's bindings, as `meta.input.contexts..` spells them. | | InputConfig | | | InputMap | A logical action map over `ctx.input`; rebinding is a data edit, not a code edit. | | InputMapInit | | | InputPointer | `ctx.input.pointer`: the mouse in one view's cell. | | InputState | Present on `ctx.input` only for the player entity. | | InstanceInput | An instance to add, or the fields to change in {@link Instances.update}. | | InstanceRecord | One instance of an instanced mesh, as {@link Instances.get} returns it. | | Instances | The instances of an `instancedMesh` entity: what `ctx.world.instances(entity)` returns. | | InstanceStore | | | IntegerLens | The box a {@link PixelScaleConfig} asks for in a view `pixelHeight` tall (the reference view's 1080). | | JOIN_STRINGS | The default text. | | JoinScreen | The join screen's controller: owns the readiness, choices and start of one lobby over `ctx.players`. | | JoinScreenOptions | The join screen's settings: the `join-screen` behavior's props. | | JoinSlotProps | The `join-slot` behavior's props. | | JoinStart | What `join-start` carries. | | 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. | | ListenOptions | Options of {@link EventBus.on} and {@link EventBus.once}. | | LocalPlayer | One local player, as `ctx.players.list()` reports them. | | LocomotionProps | | | LocomotionState | | | MinimapBounds | The world area a minimap image shows, on the ground plane (x and z, metres). | | MinimapOptions | The minimap controller's settings. | | MinimapRun | The marker mover `minimap` hands back. | | 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 | | | Pedals | Throttle and brake, 0..1, as `ctx.vehicle.drive` takes them. | | PickHit | What `ctx.camera.pick` answers: a {@link Hit}, whose `entity` is `null` for the ground-plane fallback. | | PickOptions | Options for {@link WorldQuery.pick}. | | PixelScaleConfig | A whole-number pixel scale: see {@link Follow2DConfig.pixelScale}. | | PlayerProps | | | PlayersHandle | The local players on the couch (`meta.players`) and the entity each drives. | | PlayerState | | | Quat | Quaternion `[x, y, z, w]`. | | QueryFilter | Filter for {@link WorldQuery.query}; every given field must match. | | RaceBannerRun | The banner controller `banner` hands back. | | Ray | A world ray: `dir` is unit length. | | 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. | | RoadDriverProps | The built-in `road-driver` behaviour's props: which road it follows and how it takes it. | | RoadDriverState | What the `road-driver` behaviour keeps in `ctx.state` between ticks (read it, do not set it). | | RoadEdge | The road's edges at one distance: what {@link RoadLine.edge} returns. | | RoadLine | A road's centre line, from `ctx.world.road(id)`. | | RoadPose | A road entity's pose in the world: what its samples are relative to. | | RoadProgress | One entity's progress along a road, from {@link RoadLine.progress}. | | RoadSample | One point on a road's centre line: what {@link RoadLine.at} returns. | | RoadStanding | One row of {@link RoadLine.standings}. | | 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. | | RouletteFrame | What an item roulette shows at one moment: `rouletteItem`'s answer. | | RouletteOptions | How long a spin lasts and how fast it starts. | | 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. | | SharedParams | {@link ViewsHandle.shared}'s options: the framing camera's, and when to split. | | SharedSplit | {@link ViewsHandle.shared}'s `split` options: when the shared camera splits into one view per target, and when it merges back. | | 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 | | | SlotView | One slot as the screen shows it. | | 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. | | StartCountdownOptions | The start countdown's settings. | | StartCountdownRun | The 3-2-1-GO! | | stepWedge | One tick of noticing a wedge, given the metres `progress` it made along the road this tick (in the way it drives; `NaN` when it is not on a road). | | Strings | A read-only string table. | | StringsHandle | | | StringTable | | | StringTableOptions | | | SwayChannel | One spring-damped channel: where it is and how fast it moves. | | SwayKick | A shove to the springs: how fast each channel is set moving, on top of whatever it was doing. | | SwayKickProps | One entry of {@link SwayProps.kicks}: the shove, and what in the event steers and scales it. | | SwayPose | The three channels: radians of pitch (nose up positive), radians of roll, metres of bob (up positive). | | SwayProps | The `sway` behavior's props: any {@link SwayTuning} field, plus where it tips and what counts as a teleport. | | SwayState | What the `sway` behavior keeps in `ctx.state` (it survives a hot reload, so the rest pose is never re-read from a swayed body). | | SwayTuning | How a body sways: a gain and a limit per channel, and the spring they share. | | 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. | | VehicleLanding | {@link Vehicle.landing}: the last touchdown. | | VehicleWater | {@link Vehicle.water}: a watercraft's or an amphibious vehicle's water handling, as of the last tick. | | ViewModel | | | ViewModelConfig | | | ViewModelFrame | One frame: an image of the project and where its pivot is. | | ViewRect | A view's rectangle, fractions of the window from its top-left corner. | | ViewsHandle | `ctx.views`: split screen for local multiplayer. | | ViewSize | `ctx.camera.viewSize`: the box an orthographic lens frames in the reference view, world units and pixels. | | ViewsMergedEvent | `views-merged`'s `data`: the shared camera went back to one view. | | ViewsSplitEvent | `views-split`'s `data`: the shared camera ({@link ViewsHandle.shared}) split the window. | | WaterHandle | The scene's water, read-only: the sea, its lakes and rivers, exactly as the engine floats `buoyancy` bodies on them, at `ctx.time.now`. | | WaterSample | The water at one point, as {@link WaterHandle.sample} reads it. | | WedgeOptions | How {@link stepWedge} judges a wedge; every field has a default. | | WedgeState | {@link stepWedge}'s memory: keep it in `ctx.state`. | | WedgeStep | What {@link stepWedge} says to do this tick. | | 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. | | WindHandle | The scene's wind (`meta.environment.air.wind`), read-only, at `ctx.time.now`: the air the dry probes of `buoyancy` bodies are dragged against. | | 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, 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): 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, 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): AudioDirector | null ``` Import: `import { audioDirector } from "@argus/gameplay"` ### AudioListenerPolicy *Since 0.7* How several listeners hear one spatial sound: the nearest decides, or every listener adds up. #### Signature ```ts export type AudioListenerPolicy = "nearest" | "sum" ``` Import: `import type { AudioListenerPolicy } from "@argus/api"` ### AudioListenFrom *Since 0.7* Where `ctx.audio` listens from: one listener per split-screen view, or view 1's camera alone. #### Signature ```ts export type AudioListenFrom = "views" | "camera" ``` Import: `import type { AudioListenFrom } from "@argus/api"` ### 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"` ### banner *Since 0.7* Make a banner controller for the `RaceBanner` at `id` (default `banner`). #### Signature ```ts export function banner(ctx: Ctx, options: { id?: string } = {}): RaceBannerRun ``` Import: `import { banner } from "@argus/gameplay"` ### BEHAVIOR_ENTRIES *Since 0.6* Module name → source entry. #### Signature ```ts export const BEHAVIOR_ENTRIES: Readonly> = Object.freeze( Object.fromEntries(BEHAVIOR_CATALOGUE.map((e) => [e.module, e.entry])), ) ``` Import: `import { BEHAVIOR_ENTRIES } from "@argus/gameplay"` ### bendLookAhead *Since 0.7* The look-ahead, metres, kept short where the road ahead bends hard: `aheadM`, or less so that it times the tightest curvature over it stays under `maxBend` (about 0.35 rad: a chord that cuts the inside of the bend by under 4% of its radius), never under `minM`. A long look-ahead aims across the inside of an S-bend. #### Signature ```ts export function bendLookAhead(road: RoadLine, s: number, aheadM: number, way = 1, maxBend = 0.35, minM = 2): number ``` Import: `import { bendLookAhead } 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 = { 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): 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 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, 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 ``` 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): CameraDirector | null ``` Import: `import { cameraDirector } from "@argus/gameplay"` ### CameraKind *Since 0.6; changed in 0.7* The rigs {@link CameraHandle.set} takes. `"lock"` is a third-person boom that keeps the player and a second thing, `target`, in frame: see {@link CameraParams.target}. #### Signature ```ts export type CameraKind = "third-person" | "first-person" | "fixed" | "orbit" | "lock" ``` 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 | 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"` ### cornerSpeed *Since 0.7* The fastest a bend of `curvature` (1/m) can be taken, m/s: `sqrt(grip * g / |curvature|)`, so the sideways pull is `grip` g, capped at `maxSpeed`. `grip` is a share of the tyres' friction, about their `muLat` times the share of it a driver dares use; 0.8 suits the kart preset. #### Signature ```ts export function cornerSpeed(curvature: number, grip = 0.8, maxSpeed = Number.POSITIVE_INFINITY): number ``` Import: `import { cornerSpeed } from "@argus/gameplay"` ### CountdownPhase *Since 0.7* Where a start countdown is: a figure, `"go"`, `"done"`, or `"idle"` before `start()`. #### Signature ```ts export type CountdownPhase = number | "go" | "done" | "idle" ``` Import: `import type { CountdownPhase } 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 = {}): 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"` ### dirFromRoad *Since 0.7* A direction in the road's own frame, in the world. #### Signature ```ts export function dirFromRoad(d: Vec3, pose: RoadPose): Vec3 ``` Import: `import { dirFromRoad } 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 = Record, P extends Record = Record>(base: Behavior, overrides: Behavior): Behavior ``` 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"` ### freshWedge *Since 0.7* {@link wedgeState} with nothing remembered but the tries and whether it is stuck. #### Signature ```ts export function freshWedge(w: WedgeState): WedgeState ``` Import: `import { freshWedge } from "@argus/gameplay"` ### fromRoad *Since 0.7* A point in the road's own frame, in the world. #### Signature ```ts export function fromRoad(p: Vec3, pose: RoadPose): Vec3 ``` Import: `import { fromRoad } 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` 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, 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): 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, body: string | null, position: Vec3, prev: GroundFollow | null, dt: number, opts: FollowGroundOptions = {}): GroundFollow ``` Import: `import { groundStep } from "@argus/gameplay"` ### headingError *Since 0.7* The angle from the facing `forward` to `target` in the ground plane, radians, positive right (-π..π). #### Signature ```ts export function headingError(position: Vec3, forward: Vec3, target: Vec3): number ``` Import: `import { headingError } 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, 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): 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> = { 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(): InstanceStore ``` 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"` ### JOIN_CHOICE_EVENT *Since 0.7* Raised by a `join-slot` when its player pushes sideways (`{ player, step }`, step -1 or 1); the screen cycles their choice. #### Signature ```ts export const JOIN_CHOICE_EVENT = "join-choice" ``` Import: `import { JOIN_CHOICE_EVENT } from "@argus/gameplay"` ### JOIN_LEAVE_EVENT *Since 0.7* Raised by a `join-slot` when its player presses leave (`{ player }`); the screen unseats them. #### Signature ```ts export const JOIN_LEAVE_EVENT = "join-leave" ``` Import: `import { JOIN_LEAVE_EVENT } from "@argus/gameplay"` ### JOIN_READY_EVENT *Since 0.7* Raised by a `join-slot` when its player presses ready (`{ player }`); the screen toggles that player's ready. #### Signature ```ts export const JOIN_READY_EVENT = "join-ready" ``` Import: `import { JOIN_READY_EVENT } from "@argus/gameplay"` ### joinScreenBehavior *Since 0.7* The built-in behaviour packages/gameplay/src/behaviors/join-screen.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it. #### Signature ```ts const joinScreenBehavior: Behavior, JoinScreenProps> ``` Import: `import { joinScreenBehavior } from "@argus/gameplay"` ### joinScreenController *Since 0.7* The controller running on an entity, or null. #### Signature ```ts export function joinScreenController(ctx: { entity: { id: string } }): JoinScreen | null ``` Import: `import { joinScreenController } from "@argus/gameplay"` ### JoinScreenProps *Since 0.7* The `join-screen` behavior's props: {@link JoinScreenOptions}. #### Signature ```ts export type JoinScreenProps = JoinScreenOptions ``` Import: `import type { JoinScreenProps } from "@argus/gameplay"` ### joinSlotBehavior *Since 0.7* The built-in behaviour packages/gameplay/src/behaviors/join-slot.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it. #### Signature ```ts const joinSlotBehavior: Behavior, JoinSlotProps> ``` Import: `import { joinSlotBehavior } 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, 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): 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, 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): 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"` ### minimap *Since 0.7* A minimap controller for the `Minimap` with node id `options.id` showing `options.bounds`. #### Signature ```ts export function minimap(ctx: Ctx, options: MinimapOptions): MinimapRun ``` Import: `import { minimap } from "@argus/gameplay"` ### minimapPoint *Since 0.7* Where a world position sits on a minimap image, as the `left` and `top` percentages an absolutely placed marker takes (`ctx.ui.set(id, "style:left", p.left)`). The image is a top-down view with `minX` at its left edge and `minZ` at its top edge. A position outside the bounds is pinned to the edge, so a marker never leaves the map. Degenerate bounds (no width or depth) give the centre. #### Signature ```ts export function minimapPoint(position: readonly number[], bounds: MinimapBounds): { left: string; top: string } ``` Import: `import { minimapPoint } 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(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"` ### ordinal *Since 0.7* A place in a race for the HUD's locale: the English ordinal for an `en` locale (or none given), else `"{n}."`, which most languages read as an ordinal. The locale layer has no ordinal rules yet, so other languages get the neutral form rather than English endings. #### Signature ```ts export function ordinal(n: number, locale?: string): string ``` Import: `import { ordinal } from "@argus/gameplay"` ### ordinalEn *Since 0.7* An English ordinal: 1st, 2nd, 3rd, 4th, 11th, 12th, 13th, 21st, 102nd, 111th. Not a whole number, or below 1: the number as it is. #### Signature ```ts export function ordinalEn(n: number): string ``` Import: `import { ordinalEn } 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): 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 ``` Import: `import { particleParams } from "@argus/gameplay"` ### ParticleParamValue *Since 0.7* A value for an effect param: a number, `[x, y, z]`, `[r, g, b, a]` (linear), or a `"#rrggbb[aa]"` colour (sRGB). #### Signature ```ts export type ParticleParamValue = number | Vec3 | [number, number, number, number] | string ``` Import: `import type { ParticleParamValue } from "@argus/api"` ### 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, 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 ``` 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"` ### pedals *Since 0.7* The pedals toward `target` m/s at `speed` (forward, m/s) with `steer` held: full throttle under it, lifted to 40% at full lock as a driver lifts for a bend; the brake once more than `margin` over it, harder the further over; nothing in between. Never the brake below 2 m/s, where it is reverse. #### Signature ```ts export function pedals(speed: number, target: number, steer: number, margin = 1): Pedals ``` Import: `import { pedals } 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 ``` 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): 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"` ### pursuitSteer *Since 0.7* The `steer` (-1..1, +1 right, as `ctx.vehicle.drive` takes it) that turns a vehicle at `position` facing `forward` toward `target`: the heading error to it in the ground plane, radians, times `gain`. A target behind the vehicle asks for full lock toward its side. #### Signature ```ts export function pursuitSteer(position: Vec3, forward: Vec3, target: Vec3, gain = 2): number ``` Import: `import { pursuitSteer } 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"` ### RACE_BANNER_KEYS *Since 0.7* The race banners and their words, as `@argus/ui`'s `RaceBanner` has them. #### Signature ```ts export const RACE_BANNER_KEYS: Readonly> = Object.freeze({ "final-lap": "ui.race.finalLap", "wrong-way": "ui.race.wrongWay", "new-record": "ui.race.newRecord", }) ``` Import: `import { RACE_BANNER_KEYS } from "@argus/gameplay"` ### raceClock *Since 0.7* A race time, `m:ss.mmm` (`decimals` 0..3, default 3): `raceClock(83.4567)` is `"1:23.456"`. Never negative. Minutes are not capped (`61:05.000`). The fraction is cut, not rounded, so a clock never shows a time the race has not reached yet (59.9996 s reads `0:59.999`, not `1:00.000`). #### Signature ```ts export function raceClock(seconds: number, decimals?: number): string ``` Import: `import { raceClock } from "@argus/gameplay"` ### raceDelta *Since 0.7* A gap to another time, signed: `raceDelta(-0.4567)` is `"-0.456"`, `raceDelta(1.2)` is `"+1.200"`, and a gap of a minute or more reads as a clock (`"+1:02.500"`). Zero is `"+0.000"`. #### Signature ```ts export function raceDelta(seconds: number, decimals?: number): string ``` Import: `import { raceDelta } 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): 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"` ### RigidBodyView *Since 0.7* Another entity's body, as {@link EntityHandle.body} gives it: everything {@link RigidBody} does but `wheels` (a wheel write takes a script vehicle's wheel over, which is driving it). Called anyway it throws `body.not-own`. #### Signature ```ts export type RigidBodyView = Omit ``` Import: `import type { RigidBodyView } from "@argus/api"` ### roadCurvatureAhead *Since 0.7* The tightest bend (largest |curvature|, 1/m) on `road` from `s` over the next `aheadM` metres the way `way` (+1 along the road, -1 against), sampled every `stepM`. Open roads clamp at their ends. #### Signature ```ts export function roadCurvatureAhead(road: RoadLine, s: number, aheadM: number, way = 1, stepM = 2): number ``` Import: `import { roadCurvatureAhead } from "@argus/gameplay"` ### roadDriverBehavior *Since 0.7* The built-in behaviour packages/gameplay/src/behaviors/road-driver.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it. #### Signature ```ts const roadDriverBehavior: Behavior ``` Import: `import { roadDriverBehavior } from "@argus/gameplay"` ### roadPose *Since 0.7* The pose of the road entity `id` in the world, through its parents; null when there is no such entity. #### Signature ```ts export function roadPose(ctx: Ctx, id: string): RoadPose | null ``` Import: `import { roadPose } from "@argus/gameplay"` ### rouletteItem *Since 0.7* Which item an item roulette shows `elapsed` seconds into a spin that lands on `landOn`. The spin starts fast and slows to a stop on `landOn` (or on the first item, if `landOn` is not one of `names`). The same arguments always give the same frame, so a behaviour only keeps the spin's start time and asks every tick; it writes to the HUD only when `index` changes: `ts const f = rouletteItem(ctx.time.now - ctx.state.spinAt, ITEMS, ctx.state.won) if (f.index !== ctx.state.shown) { … ctx.state.shown = f.index } ``` #### Signature ```ts export function rouletteItem(elapsed: number, names: readonly string[], landOn: string, options: RouletteOptions = {}): RouletteFrame ``` Import: `import { rouletteItem } from "@argus/gameplay"` ### 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): 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): 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 ``` 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"` ### startCountdown *Since 0.7* Make a start countdown; call `start()` when the race should begin counting. #### Signature ```ts export function startCountdown(ctx: Ctx, options: StartCountdownOptions = {}): StartCountdownRun ``` Import: `import { startCountdown } from "@argus/gameplay"` ### 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"` ### SWAY_DEFAULTS *Since 0.7* The tuning the `sway` behavior uses for any prop it is not given: a light kart body. #### Signature ```ts export const SWAY_DEFAULTS: SwayTuning = { pitch: 0.012, roll: 0.015, bob: 0.004, maxPitch: 0.12, maxRoll: 0.15, maxBob: 0.08, frequency: 2.5, damping: 0.45, } ``` Import: `import { SWAY_DEFAULTS } from "@argus/gameplay"` ### swayBehavior *Since 0.7* The built-in behaviour packages/gameplay/src/behaviors/sway.ts exports: a scene names it by module, or a behaviour imports it from "@argus/gameplay" to delegate to it. #### Signature ```ts const swayBehavior: Behavior ``` Import: `import { swayBehavior } from "@argus/gameplay"` ### swayKick *Since 0.7* The pose with `kick` added to each channel's speed, times `scale`: a hit, a boost, a landing the carrier's own motion does not show. The springs then rock the body and settle it as they settle any other sway, so a kick needs no clip and no timing of its own. A missing or non-finite field kicks nothing. The tuning's limits clamp the springs' target, not a kick: kicks add up. #### Signature ```ts export function swayKick(pose: SwayPose, kick: SwayKick, scale = 1): SwayPose ``` Import: `import { swayKick } from "@argus/gameplay"` ### swayRest *Since 0.7* A pose at rest: every channel at zero and still. #### Signature ```ts export function swayRest(): SwayPose ``` Import: `import { swayRest } from "@argus/gameplay"` ### swayStep *Since 0.7* The pose `dt` seconds on: each channel springs toward its target, the acceleration times its gain, clamped to its limit. The clamp is on the target, so a hard hit still rocks the body past it a little and settles back, as a bump stop would let it. #### Signature ```ts export function swayStep(pose: SwayPose, accel: FrameAccel, tuning: SwayTuning, dt: number): SwayPose ``` Import: `import { swayStep } 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"` ### toRoad *Since 0.7* A world point in the road's own frame. #### Signature ```ts export function toRoad(p: Vec3, pose: RoadPose): Vec3 ``` Import: `import { toRoad } from "@argus/gameplay"` ### turnRadiusSpeed *Since 0.7* The speed to drive for so the vehicle can still make a bend of curvature `k` (1/m), given the tightest circle it turns at its speed now (`ctx.vehicle.minTurnRadius`, which grows with speed on a car whose lock shrinks at speed): `speed` scaled down by how far the circle is too wide, never under `floor`; `Infinity` when it fits. #### Signature ```ts export function turnRadiusSpeed(speed: number, minTurnRadius: number, k: number, floor = 3): number ``` Import: `import { turnRadiusSpeed } 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). To turn an entity to face a target at a steady rate: `entity.yaw = turnTowards(entity.yaw, yawTo(entity, target), rate * dt)`. #### Signature ```ts export function turnTowards(current: number, target: number, maxStep: number): number ``` Import: `import { turnTowards } from "@argus/gameplay"` ### UiPreset *Since 0.7* A motion preset name for {@link UiHandle.fx} (docs/UI.md "Motion presets"). #### Signature ```ts export type UiPreset = | "pop" | "slam-in" | "slide-in-up" | "slide-in-down" | "slide-in-left" | "slide-in-right" | "fade-in" | "pulse" | "bob" | "shake" | "stamp" ``` Import: `import type { UiPreset } from "@argus/api"` ### 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"` ### VehicleRecoveryWhy *Since 0.7* Why a `recovery` block put a vehicle back. `physics`: the body kept spinning or jumping impossibly, or read NaN. #### Signature ```ts export type VehicleRecoveryWhy = "flipped" | "stuck" | "fell" | "water" | "physics" ``` Import: `import type { VehicleRecoveryWhy } from "@argus/api"` ### VehicleView *Since 0.7* Another entity's vehicle, as {@link EntityHandle.vehicle} gives it (the kart that drove into a pickup): everything {@link Vehicle} reads, and {@link Vehicle.boost}. Driving it is its own behaviour's job: `drive`, `reset` and `wheels` are not here, and called anyway they throw `vehicle.not-own`. #### Signature ```ts export type VehicleView = Omit ``` Import: `import type { VehicleView } from "@argus/api"` ### ViewLayout *Since 0.7* How `ctx.views` splits the window. `"single"` is one view (the default). `"top-bottom"` puts view 1 above view 2, `"left-right"` view 1 left of view 2. `"three"` is a 2x2 grid with views 1, 2 on top, 3 bottom-left and the bottom-right cell black, so every view keeps one size. `"grid"` is 2x2: 1 and 2 on top, 3 and 4 below. #### Signature ```ts export type ViewLayout = "single" | "top-bottom" | "left-right" | "three" | "grid" ``` Import: `import type { ViewLayout } from "@argus/api"` ### WaterKind *Since 0.7* Which water holds a point: the scene's sea, a lake (a `water` component or a terrain lake), or a river. #### Signature ```ts export type WaterKind = "sea" | "lake" | "river" ``` Import: `import type { WaterKind } from "@argus/api"` ### wedgeState *Since 0.7* A fresh {@link stepWedge} memory: not pinned, not backing out, no tries, not stuck. #### Signature ```ts export function wedgeState(): WedgeState ``` Import: `import { wedgeState } from "@argus/gameplay"` ### 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"`