Script API

ActionName

Since 0.6

Signature

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

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

add

Since 0.6

a + b, a new tuple.

Signature

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

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

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

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

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

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

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

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

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

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

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

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

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

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

export function axisMagnitude(axis: Vec2): number

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

BEHAVIOR_ENTRIES

Since 0.6

Module name → source entry.

Signature

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

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

export type BlendKind = "linear" | "cartesian"

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

BOB_DEFAULTS

Since 0.6

Signature

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

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

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

export const BUILT_IN_CONTEXTS = [GAMEPLAY_CONTEXT, MENU_CONTEXT] as const

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

BuiltInAction

Since 0.6

Signature

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

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

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

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

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

Camera2DProps

Since 0.6

Signature

export type Camera2DProps = Partial<Follow2DConfig>

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

CAMERA_KINDS

Since 0.6

Signature

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

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

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

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

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

CameraKind

Since 0.6

Signature

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

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

export type CameraTarget = Vec3 | EntityHandle | string | null

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

CastShape

Since 0.6

Shape for {@link WorldQuery.shapeCast}.

Signature

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

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

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

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

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

CONTROLLER_EVENTS

Since 0.6

Signature

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

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

ControllerEvent

Since 0.6

Signature

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

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

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

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

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

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

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

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

export const DEG = Math.PI / 180

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

deg

Since 0.6

Radians to degrees.

Signature

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

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

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

dot

Since 0.6

Dot product.

Signature

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

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

Ease

Since 0.6

Signature

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

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

ease

Since 0.6

Signature

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

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

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

export const FALLBACK_BLEND = 0.15

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

FIRST_PERSON_DEFAULTS

Since 0.6

Signature

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

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

export function flatForwardFromYaw(yaw: number): Vec3

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

FOLLOW_2D_DEFAULTS

Since 0.6

Signature

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

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

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

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

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

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

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

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

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

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

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

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

export type HostEvent = EmitEvent | ScriptErrorEvent

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

HUD_ELEMENTS

Since 0.6

Signature

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

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

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

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

HudElement

Since 0.6

Signature

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

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

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

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

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

InputKind

Since 0.6

What an action produces.

Signature

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

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

instanceStore

Since 0.6

Signature

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

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

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

isCameraKind

Since 0.6

Signature

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

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

isParticlePreset

Since 0.6

Signature

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

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

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

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

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

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

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

length

Since 0.6

Length of a vector.

Signature

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

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

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

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

lerpVec3

Since 0.6

Signature

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

export function normalize(a: Vec3): Vec3

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

ORBIT_DEFAULTS

Since 0.6

Signature

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

export function quatNormalize(q: Quat): Quat

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

rad

Since 0.6

Degrees to radians.

Signature

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const shotsBehavior: Behavior<ShotsState, ShotsProps>

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

SkyKind

Since 0.6

Signature

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

export type SpawnOptions = SpawnLikeOptions | SpawnPrefabOptions

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

sub

Since 0.6

a - b, a new tuple.

Signature

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

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

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

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

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

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

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

THIRD_PERSON_DEFAULTS

Since 0.6

Signature

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

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

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

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

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

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

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

export function worldPoint(target: Target): Vec3

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

wrapAngle

Since 0.6

Wrap an angle to (-pi, pi].

Signature

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

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

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

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

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