Ctx

One Ctx per behavior instance; state and props are per instance, nav/input/controller/animator are null when the entity lacks that component. @typeParam S shape of state (persisted across hot reloads) @typeParam P shape of props (the script component's props in the scene)

Reached in a behaviour as ctx.

Signature

export interface Ctx<S = Record<string, any>, P = Record<string, any>> {
  entity: EntityHandle
  world: WorldQuery
  nav: NavAgent | null
  input: InputState | null
  controller: Controller | null
  animator: Animator | null
  /** The entity's physics body; null while it has none. Read live, like `controller`. */
  body: RigidBody | null
  /** The entity's joint while it is in force; null otherwise. Read live, like `body`. */
  joint: Joint | null
  /** The entity's vehicle while it is running; null otherwise. Read live, like `body`. */
  vehicle: Vehicle | null
  /** The entity's wheel while it is running; null otherwise. Read live, like `body`. */
  wheel: Wheel | null
  /** The entity's sprite; null when it has no `sprite` component. Read live, like `body`. */
  sprite: Sprite | null
  /** The entity's tilemap; null when it has no `tilemap` component. Read live, like `body`. */
  tilemap: Tilemap | null
  /** Values this behaviour publishes for a data recording. Always present. */
  data: DataHandle
  events: EventBus
  hud: HudHandle
  ui: UiHandle
  time: TimeInfo
  /** The sky, read-only. */
  environment: EnvironmentInfo
  camera: CameraHandle
  audio: AudioHandle
  particles: ParticlesHandle
  labels: LabelsHandle
  /** Shader parameters. */
  render: RenderHandle
  strings: StringsHandle
  save: SaveHandle
  /** The project's `data/**` files, read-only. */
  files: FilesHandle
  session: SessionHandle
  /** Plain object owned by this instance; survives `reload`. Must stay JSON-serialisable. */
  state: S
  /** Read-only copy of the script component's props. */
  props: P
  /** Structured log line for the observability layer; `data` is JSON round-tripped. */
  log(msg: string, data?: unknown): void
}

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

Members

Example

The tested fixture fixtures/app/agent.ts.

import type { Behavior } from "@argus/api"

// Sends a nav agent to `props.target` once, then reports arrival through ctx.state so the
// test can read it without polling the crowd directly.
export default {
  init(ctx) {
    ctx.state.arrived = false
    ctx.nav?.goTo(ctx.props.target as [number, number, number])
  },
  update(ctx) {
    if (ctx.nav?.arrived) ctx.state.arrived = true
  },
} satisfies Behavior