@aosengine/sdk

Classes

BodyIndex

Maps host body ids back onto entities and ingests frame-input.bodies.

The incoming list is a Float32Array in both modes — jco lifts WIT list<f32> into one, and direct mode hands the guest the host's own buffer (see packages/sdk/src/wit/generated/interfaces/aos-engine-game.d.ts). It is read purely by index and never copied.

Constructors

Constructor

new BodyIndex(maxBodies): BodyIndex;

Parameters

Parameter	Type	Description
maxBodies	number	Body-id ceiling.

Returns

BodyIndex

Properties

bodyToEntity

readonly bodyToEntity: Uint32Array;

Body id to entity id. Index 0 is unused: body 0 means "no body".

lastRowCount

lastRowCount: number = 0;

Number of rows seen in the most recent ingest.

Methods

bind()

bind(body, entity): void;

Associate a body with the entity it drives.

Parameters

Parameter	Type	Description
body	number	Body id.
entity	number	Entity id.

Returns

void

Nothing.

bodyOf()

bodyOf(entity): number;

The body id driving an entity, or 0.

Parameters

Parameter	Type	Description
entity	number	Entity id.

Returns

number

The body id, or 0 when the entity has none.

clear()

clear(): void;

Forget every body.

Returns

void

Nothing.

ingest()

ingest(bodies): void;

Copy post-step body transforms into Transform and Velocity.

This does not mark the entity moved, and that is the point. The host owns a body-driven entity's transform: the physics module hands the same rows straight to the adapter after it steps, so the object in the scene is already where the body is. Marking here would send all twelve floats back across the boundary in frame-output.transforms for the host to write a second time — the same numbers, one step later.

What the guest gets is still the truth for gameplay: read Transform.x[e] to aim at something, Velocity to decide whether it is running. A system that overwrites those lanes is authoring a move rather than observing one, and has to say so with markMoved — see markMoved.

Parameters

Parameter	Type	Description
bodies	ArrayLike<number>	The packed rows, stride 15.

Returns

void

Nothing.

unbind()

unbind(body): void;

Forget a body.

Parameters

Parameter	Type	Description
body	number	Body id.

Returns

void

Nothing.

---

CommandBuffer

Builds and owns one frame's commands list.

Constructors

Constructor

new CommandBuffer(): CommandBuffer;

Returns

CommandBuffer

Properties

list

readonly list: Command[] = [];

The list handed to the host. Reused every frame; never retain it.

Methods

addBody()

addBody(
   body, 
   entity, 
   kind, 
   shape, 
   hx, 
   hy, 
   hz, 
   px, 
   py, 
   pz, 
   mass, 
   layer, 
   mask, 
   flags
): AddBodyCmd;

Create a rigid body or character controller.

Parameters

Parameter	Type	Description
body	number	Guest-minted body id.
entity	number	Entity the body drives.
kind	BodyKind	Body class.
shape	ShapeKind	Collision shape family.
hx	number	Half-extent / radius lane 0.
hy	number	Half-extent / half-height lane 1.
hz	number	Half-extent lane 2.
px	number	Position x.
py	number	Position y.
pz	number	Position z.
mass	number	Kilograms; ignored for fixed and kinematic bodies.
layer	CollisionLayers	What this body is.
mask	CollisionLayers	What this body collides with.
flags	BodyFlags	Per-body switches.

Returns

AddBodyCmd

The payload, so the caller can tune friction and damping. Round anything written onto it with Math.fround.

applyImpulse()

applyImpulse(
   body, 
   x, 
   y, 
   z, 
   atX?, 
   atY?, 
   atZ?
): void;

Apply a one-shot impulse.

Parameters

Parameter	Type	Description
body	number	Body id.
x	number	Impulse x.
y	number	Impulse y.
z	number	Impulse z.
atX?	number	World-space application point x. Omit for the centre of mass.
atY?	number	Application point y.
atZ?	number	Application point z.

Returns

void

Nothing.

conversation()

conversation(
   entity, 
   action, 
   character?, 
   text?
): void;

Control an optional host conversation module using pooled commands.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Interviewed entity.
action	| "end" | "start" | "ask" | "interrupt" | "microphone-on" | "microphone-off"	undefined	Lifecycle or text command.
character	string	''	Configured character id, never a URL.
text	string	''	Typed/transcribed question; empty for lifecycle commands.

Returns

void

despawn()

despawn(entity): void;

Destroy an entity in the host scene.

Parameters

Parameter	Type	Description
entity	number	Entity id.

Returns

void

Nothing.

loadAsset()

loadAsset(asset, priority): void;

Ask the host to start loading an asset.

Parameters

Parameter	Type	Description
asset	number	Asset handle.
priority	number	Higher runs first.

Returns

void

Nothing.

lookAt()

lookAt(
   entity, 
   target, 
   weight
): void;

Aim a character's head and eyes.

Parameters

Parameter	Type	Description
entity	number	Entity id.
target	Vec3 | null	World-space point, or null to release the look-at.
weight	number	Blend weight in 0..1.

Returns

void

Nothing.

moveCharacter()

moveCharacter(
   body, 
   vx, 
   vy, 
   vz, 
   jump, 
   crouch, 
   maxSlopeDeg
): void;

Drive a character body for one step.

Parameters

Parameter	Type	Description
body	number	Body id of a character body.
vx	number	Desired velocity x.
vy	number	Desired velocity y.
vz	number	Desired velocity z.
jump	boolean	Request a jump this step.
crouch	boolean	Request a crouch this step.
maxSlopeDeg	number	Maximum walkable slope in degrees.

Returns

void

Nothing.

playSound()

playSound(
   sound, 
   asset, 
   entity, 
   volume, 
   pitch, 
   looping, 
   bus
): void;

Start a sound.

Parameters

Parameter	Type	Description
sound	number	Guest-minted sound handle.
asset	number	Audio asset handle.
entity	number | undefined	Entity to follow, or undefined for a non-positional sound.
volume	number	Linear gain in 0..1.
pitch	number	Playback-rate multiplier.
looping	boolean	Loop the sound.
bus	AudioBus	Mixer bus.

Returns

void

Nothing.

removeBody()

removeBody(body): void;

Destroy a body.

Parameters

Parameter	Type	Description
body	number	Body id.

Returns

void

Nothing.

reset()

reset(): void;

Rewind for a new frame. Keeps every pooled object alive.

Returns

void

Nothing.

say()

say(
   entity, 
   text, 
   audio?, 
   visemes?
): void;

Speak a line.

Parameters

Parameter	Type	Description
entity	number	Entity id.
text	string	Subtitle text.
audio?	number	Voice line asset handle.
visemes?	string	Viseme track as JSON.

Returns

void

Nothing.

setAnim()

setAnim(
   entity, 
   clip, 
   looping, 
   speed, 
   fadeMs, 
   weight
): void;

Play or cross-fade a clip.

Parameters

Parameter	Type	Description
entity	number	Entity id.
clip	string	Clip name inside the entity's asset.
looping	boolean	Loop the clip.
speed	number	Playback rate multiplier.
fadeMs	number	Cross-fade duration in milliseconds.
weight	number	Target layer weight in 0..1.

Returns

void

Nothing.

setAsset()

setAsset(entity, asset): void;

Attach or detach a renderable.

Parameters

Parameter	Type	Description
entity	number	Entity id.
asset	number | undefined	Asset handle, or undefined to detach.

Returns

void

Nothing.

setBodyEnabled()

setBodyEnabled(body, enabled): void;

Enable or disable a body in the broad phase.

Parameters

Parameter	Type	Description
body	number	Body id.
enabled	boolean	Whether the body participates.

Returns

void

Nothing.

setBodyTransform()

setBodyTransform(
   body, 
   px, 
   py, 
   pz, 
   qx, 
   qy, 
   qz, 
   qw, 
   teleport
): void;

Move a body directly.

Parameters

Parameter	Type	Description
body	number	Body id.
px	number	Position x.
py	number	Position y.
pz	number	Position z.
qx	number	Rotation x.
qy	number	Rotation y.
qz	number	Rotation z.
qw	number	Rotation w.
teleport	boolean	Clear velocities and skip interpolation.

Returns

void

Nothing.

setBodyVelocity()

setBodyVelocity(
   body, 
   x, 
   y, 
   z, 
   ax?, 
   ay?, 
   az?
): void;

Overwrite a body's velocity.

Parameters

Parameter	Type	Description
body	number	Body id.
x	number	Linear x.
y	number	Linear y.
z	number	Linear z.
ax?	number	Angular x, radians per second. Omit to leave spin alone.
ay?	number	Angular y.
az?	number	Angular z.

Returns

void

Nothing.

setCharacterState()

setCharacterState(
   entity, 
   state, 
   vx, 
   vy, 
   vz, 
   grounded
): void;

Drive a character's locomotion state machine.

Parameters

Parameter	Type	Description
entity	number	Entity id.
state	string	State name, for example `'idle'
vx	number	Velocity x.
vy	number	Velocity y.
vz	number	Velocity z.
grounded	boolean	Whether the character is on the ground.

Returns

void

Nothing.

setClipWeights()

setClipWeights(
   entity, 
   clips, 
   weights, 
   timeScale
): void;

Set explicit per-clip weights.

Parameters

Parameter	Type	Description
entity	number	Entity id.
clips	readonly string[]	Clip names.
weights	Float32Array<ArrayBufferLike> | readonly number[]	Positional weights; must match clips in length. Copied into pooled storage, so the caller may reuse its own array freely.
timeScale	number	Playback rate for the whole layer.

Returns

void

Nothing.

setExpression()

setExpression(
   entity, 
   space, 
   weights
): void;

Set facial expression coefficients.

Parameters

Parameter	Type	Description
entity	number	Entity id.
space	ExpressionSpace	Coordinate space the weights are in.
weights	Float32Array<ArrayBufferLike> | readonly number[]	Coefficients; length must match the space. Copied into pooled storage, so the caller may reuse its own array freely.

Returns

void

Nothing.

setListener()

setListener(
   px, 
   py, 
   pz, 
   qx, 
   qy, 
   qz, 
   qw
): void;

Place the audio listener.

Parameters

Parameter	Type	Description
px	number	Position x.
py	number	Position y.
pz	number	Position z.
qx	number	Rotation x.
qy	number	Rotation y.
qz	number	Rotation z.
qw	number	Rotation w.

Returns

void

Nothing.

setMaterialParam()

setMaterialParam(
   entity, 
   name, 
   value
): void;

Set one material uniform.

The value is copied into a pooled holder, rounded to f32: the host never sees the guest's own object, and a colour built inline costs nothing after the first frame. Only a slot that changes variant allocates.

Parameters

Parameter	Type	Description
entity	number	Entity id.
name	string	Uniform name.
value	MaterialValue	The value variant.

Returns

void

Nothing.

setParent()

setParent(
   entity, 
   parent, 
   keepWorldTransform
): void;

Reparent an entity.

Parameters

Parameter	Type	Description
entity	number	Entity id.
parent	number | undefined	New parent, or undefined for the scene root.
keepWorldTransform	boolean	Preserve the world transform across the move.

Returns

void

Nothing.

setPointerLock()

setPointerLock(locked): void;

Request or release pointer lock.

Parameters

Parameter	Type	Description
locked	boolean	Whether the canvas should hold pointer lock.

Returns

void

Nothing.

setTimeScale()

setTimeScale(scale): void;

Scale simulated time.

Parameters

Parameter	Type	Description
scale	number	Multiplier; 1 is real time.

Returns

void

Nothing.

spawn()

spawn(
   entity, 
   asset, 
   px, 
   py, 
   pz, 
   qx, 
   qy, 
   qz, 
   qw, 
   sx, 
   sy, 
   sz, 
   name?
): void;

Create an entity in the host scene.

Parameters

Parameter	Type	Description
entity	number	Guest-minted entity id.
asset	number | undefined	Renderable asset handle, or undefined for a bare node.
px	number	Position x.
py	number	Position y.
pz	number	Position z.
qx	number	Rotation x.
qy	number	Rotation y.
qz	number	Rotation z.
qw	number	Rotation w.
sx	number	Scale x.
sy	number	Scale y.
sz	number	Scale z.
name?	string	Debug label.

Returns

void

Nothing.

spawnCharacter()

spawnCharacter(
   entity, 
   bundle, 
   px, 
   py, 
   pz, 
   qx, 
   qy, 
   qz, 
   qw
): void;

Instantiate a splat character bundle.

Parameters

Parameter	Type	Description
entity	number	Guest-minted entity id.
bundle	number	Character bundle asset handle.
px	number	Position x.
py	number	Position y.
pz	number	Position z.
qx	number	Rotation x.
qy	number	Rotation y.
qz	number	Rotation z.
qw	number	Rotation w.

Returns

void

Nothing.

stopSound()

stopSound(sound, fadeMs): void;

Stop a playing sound.

Parameters

Parameter	Type	Description
sound	number	Sound handle.
fadeMs	number	Fade-out in milliseconds.

Returns

void

Nothing.

---

TransformPacker

Packs entity transforms into frame-output.transforms.

One row is written per entity whose dirty flags are non-zero, in ascending entity order — deterministic, and cheaper than a bitecs query for the densely packed id space the SDK mints.

Constructors

Constructor

new TransformPacker(maxEntities): TransformPacker;

Parameters

Parameter	Type	Description
maxEntities	number	Entity ceiling; the buffer holds this many rows.

Returns

TransformPacker

Properties

dirty

readonly dirty: Uint8Array;

Per-entity transform-flags accumulated since the last pack.

highWater

highWater: number = 0;

Highest entity id pack scans to.

It rises when a higher id is marked and falls back to the last dirty id every pack, so a level that spawned 4,000 entities and despawned all but ten does not keep scanning 4,000 slots a frame.

Methods

clear()

clear(): void;

Forget every pending flag, for example after restore.

Returns

void

Nothing.

mark()

mark(entity, flags): void;

Accumulate dirty flags for one entity.

Parameters

Parameter	Type	Description
entity	number	Entity id.
flags	number	Any combination of TRANSFORM_FLAGS.

Returns

void

Nothing.

pack()

pack(): Float32Array;

Write every dirty entity into the packed buffer and clear the flags.

Returns

Float32Array

A memoised subarray of the internal buffer. The same row count always returns the same object, which is what makes a steady-state tick allocation-free; never retain it across frames.

Interfaces

AddBodyCmd

Create a rigid body or character controller.

Properties

angularDamping

angularDamping: number;

body

body: number;

entity

entity: number;

flags

flags: BodyFlags;

friction

friction: number;

kind

kind: BodyKind;

layer

layer: CollisionLayers;

linearDamping

linearDamping: number;

mask

mask: CollisionLayers;

mass

mass: number;

position

position: Vec3;

restitution

restitution: number;

rotation

rotation: Quat;

shape

shape: Shape;

---

AnimEventData

An animation clip passed a named marker.

Properties

clip

clip: string;

entity

entity: number;

name

name: string;

time

time: number;

---

ApplyImpulseCmd

Apply a one-shot impulse.

Properties

atPoint?

optional atPoint?: Vec3;

body

body: number;

impulse

impulse: Vec3;

---

AssetDesc

Manifest metadata for one asset handle.

Properties

hasCollider

hasCollider: boolean;

id

id: number;

kind

kind: AssetKind;

name

name: string;

ready

ready: boolean;

rig?

optional rig?: string;

tags

tags: readonly string[];

---

AssetLoadedEvent

An asset finished loading.

Properties

asset

asset: number;

name

name: string;

---

Axis2

A two-axis reading. The same object is returned every call.

Properties

x

x: number;

y

y: number;

---

BodyFlags

Per-body behaviour switches. Omitted keys lower as false.

Properties

ccd?

optional ccd?: boolean;

debugDraw?

optional debugDraw?: boolean;

lockRotation?

optional lockRotation?: boolean;

noSleep?

optional noSleep?: boolean;

reportContacts?

optional reportContacts?: boolean;

sensor?

optional sensor?: boolean;

---

BodySpec

The physics body a prefab carries.

Properties

dims?

optional dims?: readonly number[];

Shape dimensions. box: half extents. sphere: [radius]. capsule / cylinder: [radius, halfHeight]. plane: the normal.

flags?

optional flags?: BodyFlags;

Per-body switches.

friction?

optional friction?: number;

Coulomb friction. Default 0.5.

kind

kind: BodyKind;

Body class. 'character' makes a CharacterVirtual controller.

layer?

optional layer?: CollisionLayers;

What this body is. Default { defaultLayer: true }.

mask?

optional mask?: CollisionLayers;

What this body collides with. Default every layer.

mass?

optional mass?: number;

Kilograms; ignored for fixed and kinematic bodies. Default 1.

restitution?

optional restitution?: number;

Bounciness in 0..1. Default 0.

shape

shape: ShapeKind;

Collision shape family.

---

CameraState

The camera the host should render from this frame.

Properties

armLength

armLength: number;

far

far: number;

follow?

optional follow?: number;

fovYDeg

fovYDeg: number;

mode

mode: CameraMode;

near

near: number;

offset

offset: Vec3;

position

position: Vec3;

projection

projection: ProjectionKind;

rotation

rotation: Quat;

target?

optional target?: Vec3;

---

CharacterReadyEvent

A character bundle finished loading and reported its expression space.

Properties

bundle

bundle: number;

entity

entity: number;

expressionDim

expressionDim: number;

space

space: ExpressionSpace;

---

CharacterStore

Splat character bundle handle.

Properties

bundle

bundle: Uint32Array;

Character bundle asset handle.

dirty

dirty: Uint8Array;

Non-zero when the host has not yet seen the current value.

---

CollisionLayers

Broad-phase layer set. Omitted keys lower as false.

Properties

character?

optional character?: boolean;

debris?

optional debris?: boolean;

defaultLayer?

optional defaultLayer?: boolean;

enemy?

optional enemy?: boolean;

pickup?

optional pickup?: boolean;

player?

optional player?: boolean;

projectile?

optional projectile?: boolean;

staticGeometry?

optional staticGeometry?: boolean;

trigger?

optional trigger?: boolean;

user0?

optional user0?: boolean;

user1?

optional user1?: boolean;

user2?

optional user2?: boolean;

user3?

optional user3?: boolean;

user4?

optional user4?: boolean;

user5?

optional user5?: boolean;

water?

optional water?: boolean;

---

Contact

One reported contact between two bodies.

Properties

a

a: number;

b

b: number;

entityA

entityA: number;

entityB

entityB: number;

impulse

impulse: number;

normal

normal: Vec3;

phase

phase: ContactPhase;

point

point: Vec3;

---

ConversationCmd

Structural interview controls; service addresses stay in host configuration.

Properties

action

action: 
  | "end"
  | "start"
  | "ask"
  | "interrupt"
  | "microphone-on"
  | "microphone-off";

character

character: string;

entity

entity: number;

text

text: string;

---

ConversationEvent

Low-frequency conversation UI/input event. No audio or facial frames cross WIT.

Properties

entity

entity: number;

kind

kind: "error" | "input" | "status" | "subtitle" | "story";

text

text: string;

Story events carry the versioned full snapshot as JSON.

---

FirstPersonOptions

Options for camera.firstPerson.

Properties

eyeHeight?

optional eyeHeight?: number;

Eye height above the entity origin, metres. Default 1.7.

fovYDeg?

optional fovYDeg?: number;

Vertical field of view in degrees. Default 75.

---

FollowOptions

Options for camera.follow.

Properties

distance?

optional distance?: number;

Boom length behind the target, metres. Default 4.

fovYDeg?

optional fovYDeg?: number;

Vertical field of view in degrees. Default 60.

height?

optional height?: number;

Rig-local height offset, metres. Default 1.6.

pitch?

optional pitch?: number;

Orbit pitch in radians; positive looks up. Defaults to the accumulator.

yaw?

optional yaw?: number;

Orbit yaw in radians about +Y; 0 puts the camera behind the target.

Defaults to the built-in look accumulator. Pass it when the game keeps its own orbit — a third-person camera usually wants a tighter pitch range and its own sensitivity than the first-person one the accumulator is tuned for.

---

FrameInput

One fixed simulation step of host state handed to the guest.

Properties

bodies

bodies: ArrayLike<number>;

Post-step body transforms, stride 15, sorted ascending by body id.

contacts

contacts: readonly Contact[];

dt

dt: number;

elapsed

elapsed: number;

events

events: readonly GameEvent[];

frame

frame: number | bigint;

Monotonic fixed-step counter. jco lifts u64 as a bigint on the host and a number in the guest, so both are legal here; the runtime Number()s it once, on the way in.

input

input: InputState;

---

FrameOutput

Everything the guest hands back for one fixed step.

Properties

camera

camera: CameraState;

commands

commands: readonly Command[];

hud?

optional hud?: string;

HUD JSON, present only on the frames it changed.

transforms

transforms: Float32Array;

Entity transforms, stride 12. Never empty: see the zero-row rule.

---

GameConfig

The init payload.

Properties

devMode

devMode: boolean;

fixedHz

fixedHz: number;

options?

optional options?: string;

seed

seed: number | bigint;

Deterministic run seed. A bigint on the host, a number in the guest; the runtime Number()s it once, on the way in.

viewportHeight

viewportHeight: number;

viewportWidth

viewportWidth: number;

---

GameContext

Everything a system can reach.

The same object is handed to every system on every frame — it is mutated in place, never rebuilt, so never retain it or destructure frame outside the call.

Properties

audio

readonly audio: object;

Sound playback.

listener()

listener(position, rotation): void;

Place the audio listener.

Parameters

Parameter	Type	Description
position	Vec3	Listener position.
rotation	Quat	Listener rotation, xyzw.

Returns

void

Nothing.

play()

play(asset, options?): number;

Start a sound.

Parameters

Parameter	Type	Description
asset	string | number	Manifest string id or asset handle.
options?	PlayOptions	Attachment, gain, pitch, looping and bus.

Returns

number

The guest-minted sound handle, or 0 when the asset is unknown.

stop()

stop(sound, fadeMs?): void;

Stop a playing sound.

Parameters

Parameter	Type	Default value	Description
sound	number	undefined	A handle from play.
fadeMs	number	0	Fade-out in milliseconds; 0 stops immediately.

Returns

void

Nothing.

camera

readonly camera: object;

The camera record for this frame.

look

Get Signature

get look(): object;

Accumulated look angles, in radians. Mutate to snap the view.

Returns

object

The live look state.

pitch

pitch: number;

sensitivity

sensitivity: number;

yaw

yaw: number;

state

Get Signature

get state(): CameraState;

The whole camera record, for games that want every knob.

Returns

CameraState

The live record. Mutate it; do not replace it.

firstPerson()

firstPerson(entity, options?): void;

Mount the camera at an entity's eyes.

Yaw and pitch come from the built-in look accumulator, which integrates input.mouse.dx/dy once per tick.

Parameters

Parameter	Type	Description
entity	number	Entity to mount on.
options?	FirstPersonOptions	Eye height and field of view.

Returns

void

Nothing.

follow()

follow(entity, options?): void;

Put the camera on a spring arm behind an entity.

The host owns the arm and its collision; the guest only states the intent. position is the orbit pivot and rotation the direction the player is looking, so a host with no rig still ends up somewhere sensible.

Parameters

Parameter	Type	Description
entity	number	Entity to follow.
options?	FollowOptions	Boom length, height offset, field of view and orbit angles.

Returns

void

Nothing.

lookAt()

lookAt(target): void;

Aim the camera at a world point, overriding its rotation.

Parameters

Parameter	Type	Description
target	Vec3 | null	The point to look at, or null to use the rotation again.

Returns

void

Nothing.

set()

set(
   position, 
   rotation, 
   fovYDeg?
): void;

Place the camera explicitly, detaching it from any entity.

Parameters

Parameter	Type	Default value	Description
position	Vec3	undefined	Eye position.
rotation	Quat	undefined	Eye rotation, xyzw.
fovYDeg	number	60	Vertical field of view in degrees. Default 60.

Returns

void

Nothing.

character

readonly character: object;

Splat characters.

bundleOf()

bundleOf(entity): number;

The character bundle handle attached to an entity, or 0.

Parameters

Parameter	Type	Description
entity	number	Entity id.

Returns

number

The bundle asset handle.

lookAt()

lookAt(
   entity, 
   target, 
   weight?
): void;

Aim the head and eyes at a world point.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity with a Character component.
target	Vec3 | null	undefined	The point, or null to release and return to the idle.
weight	number	1	Blend weight in 0..1. Default 1.

Returns

void

Nothing.

say()

say(
   entity, 
   text, 
   voice?, 
   visemes?
): void;

Speak a line.

Parameters

Parameter	Type	Description
entity	number	Entity with a Character component.
text	string	Subtitle text; the host decides whether to show it.
voice?	string | number	Manifest string id or handle of a voice line.
visemes?	string	Viseme track as JSON, matching the bundle's space.

Returns

void

Nothing.

setClipWeights()

setClipWeights(
   entity, 
   clips, 
   weights, 
   timeScale?
): void;

Set explicit per-clip weights on the body layer.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity with a Character component.
clips	readonly string[]	undefined	Clip names.
weights	Float32Array<ArrayBufferLike> | readonly number[]	undefined	Positional weights; must be the same length as clips.
timeScale	number	1	Playback rate for the whole layer. Default 1.

Returns

void

Nothing.

setExpression()

setExpression(
   entity, 
   space, 
   weights
): void;

Set facial expression coefficients.

Parameters

Parameter	Type	Description
entity	number	Entity with a Character component.
space	ExpressionSpace	Coordinate space: 52 ARKit, 387 GNM, or the 68-float view.
weights	Float32Array<ArrayBufferLike> | readonly number[]	Coefficients; length must match the space.

Returns

void

Nothing.

setState()

setState(
   entity, 
   state, 
   vx, 
   vy, 
   vz, 
   grounded?
): void;

Drive the locomotion state machine.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity with a Character component.
state	string	undefined	State name, for example `'idle'
vx	number	undefined	World-space velocity x, drives the locomotion blend.
vy	number	undefined	World-space velocity y.
vz	number	undefined	World-space velocity z.
grounded	boolean	true	Whether the character is on the ground.

Returns

void

Nothing.

config

readonly config: GameConfig;

The init config.

contacts

readonly contacts: readonly Contact[];

Contacts reported since the previous tick.

dt

readonly dt: number;

Fixed timestep in seconds.

elapsed

readonly elapsed: number;

Simulated seconds since init.

events

readonly events: readonly GameEvent[];

Host-side occurrences since the previous tick, in order.

frame

readonly frame: number;

Monotonic fixed-step counter, starting at 0.

hud

readonly hud: object;

The HUD model.

clear()

clear(): void;

Drop the HUD: emit an empty model this frame.

Idempotent — calling it every frame emits {} once, exactly like set.

Returns

void

Nothing.

invalidate()

invalidate(): void;

Forget what the host has seen, so the next set emits even if the model did not change. Use it after the host reloaded its overlay.

On its own it sends nothing: the next set does. To send an empty model now, call clear().

Returns

void

Nothing.

set()

set(model): boolean;

Set the HUD model for this frame.

Nested plain objects are compared by value four levels down, so a model rebuilt inline every frame is recognised as unchanged. Arrays and class instances are compared by identity: keep those out of the model, or build them once and mutate nothing.

Parameters

Parameter	Type	Description
model	Record<string, unknown>	A JSON-serialisable object.

Returns

boolean

True when the model changed and JSON will cross this frame.

input

readonly input: object;

Keyboard, mouse and gamepad.

focused

Get Signature

get focused(): boolean;

Does the canvas have focus? Treat input as neutral when it does not.

Returns

boolean

True while the canvas is focused.

mods

Get Signature

get mods(): InputMods;

Keyboard modifier state.

Returns

InputMods

The modifiers for this frame.

mouse

Get Signature

get mouse(): MouseState;

Pointer position, per-frame delta, wheel and button bitsets.

Returns

MouseState

The mouse state for this frame. Owned by the SDK; never retain it.

axis2()

axis2(
   negX, 
   posX, 
   negY, 
   posY
): Axis2;

A two-axis reading built from four keys.

Parameters

Parameter	Type	Description
negX	string	Key that drives x negative, for example 'A'.
posX	string	Key that drives x positive, for example 'D'.
negY	string	Key that drives y negative, for example 'S'.
posY	string	Key that drives y positive, for example 'W'.

Returns

Axis2

A pooled { x, y } with components in -1..1. Never retain it.

gamepad()

gamepad(index): 
  | {
  axes: ArrayLike<number>;
  buttons: number;
  connected: boolean;
  index: number;
  pressed: number;
  released: number;
}
  | null;

One connected gamepad.

Parameters

Parameter	Type	Description
index	number	Navigator gamepad index.

Returns

| { axes: ArrayLike<number>; buttons: number; connected: boolean; index: number; pressed: number; released: number; } | null

The gamepad, or null when nothing is connected at that index. Owned by the SDK; never retain it.

isDown()

isDown(key): boolean;

Is the key held this frame?

Parameters

Parameter	Type	Description
key	string	A DOM code ('KeyW'), a bare letter/digit ('W', '1') or an alias ('Shift', 'Esc').

Returns

boolean

True while the key is down.

mouseDown()

mouseDown(button): boolean;

Is a mouse button held?

Parameters

Parameter	Type	Description
button	number	A MOUSE_BUTTONS value, or a raw bit mask.

Returns

boolean

True while the button is down.

mousePressed()

mousePressed(button): boolean;

Did a mouse button go down this frame?

Parameters

Parameter	Type	Description
button	number	A MOUSE_BUTTONS value, or a raw bit mask.

Returns

boolean

True on the frame the button went down.

mouseReleased()

mouseReleased(button): boolean;

Did a mouse button come up this frame?

Parameters

Parameter	Type	Description
button	number	A MOUSE_BUTTONS value, or a raw bit mask.

Returns

boolean

True on the frame the button came up.

pressed()

pressed(key): boolean;

Did the key go down this frame?

Parameters

Parameter	Type	Description
key	string	A key name.

Returns

boolean

True on the frame the key went down.

released()

released(key): boolean;

Did the key come up this frame?

Parameters

Parameter	Type	Description
key	string	A key name.

Returns

boolean

True on the frame the key came up.

physics

readonly physics: object;

Physics queries and body commands.

ALL_LAYERS

ALL_LAYERS: CollisionLayers;

Every collision layer, for queries that should hit anything.

applyImpulse()

applyImpulse(
   entity, 
   x, 
   y, 
   z, 
   atX?, 
   atY?, 
   atZ?
): void;

Apply a one-shot impulse.

With no application point the impulse acts at the centre of mass. Give one — all three coordinates — to apply it off-centre and impart spin.

Parameters

Parameter	Type	Description
entity	number	Entity with a body.
x	number	Impulse x, newton-seconds.
y	number	Impulse y.
z	number	Impulse z.
atX?	number	World-space application point x, or omit for the centre of mass.
atY?	number	Application point y.
atZ?	number	Application point z.

Returns

void

Nothing.

isGrounded()

isGrounded(entity): boolean;

Actual walkable ground contact from the last host physics step. No host call. Unknown, steep and unsupported contacts return false, even at a jump apex.

Parameters

Parameter	Type	Description
entity	number	Character entity.

Returns

boolean

Whether the character is supported by walkable ground.

moveCharacter()

moveCharacter(
   entity, 
   vx, 
   vy, 
   vz, 
   jump?, 
   crouch?, 
   maxSlopeDeg?
): void;

Drive a character body for this step.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity whose body was created with kind: 'character'.
vx	number	undefined	Desired world-space velocity x, metres per second.
vy	number	undefined	Desired world-space velocity y.
vz	number	undefined	Desired world-space velocity z.
jump	boolean	false	Request a jump this step.
crouch	boolean	false	Request a crouch this step.
maxSlopeDeg	number	45	Maximum walkable slope.

Returns

void

Nothing.

overlapSphere()

overlapSphere(
   center, 
   radius, 
   maxResults?, 
   mask?, 
   ignoreEntity?
): readonly OverlapHit[];

Bodies overlapping a sphere, nearest first.

Parameters

Parameter	Type	Default value	Description
center	Vec3	undefined	Sphere centre.
radius	number	undefined	Sphere radius in metres.
maxResults	number	16	Cap on returned hits.
mask?	CollisionLayers	undefined	Layers to consider; defaults to every layer.
ignoreEntity?	number	undefined	Entity to skip.

Returns

readonly OverlapHit[]

The overlapping bodies.

raycast()

raycast(
   origin, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Closest hit along a ray.

Parameters

Parameter	Type	Description
origin	Vec3	World-space ray origin.
direction	Vec3	Ray direction; need not be normalised.
maxDistance	number	Maximum distance in metres.
mask?	CollisionLayers	Layers to consider; defaults to every layer.
ignoreEntity?	number	Entity to skip, usually the caster.

Returns

RayHit | null

The hit, or null on a miss. The hit object comes from the host and is freshly allocated: this call is not allocation-free.

raycastBatch()

raycastBatch(rays): readonly (RayHit | null | undefined)[];

Many rays in one round trip. Result index i matches rays[i].

Parameters

Parameter	Type	Description
rays	readonly object[]	The rays. Build them once and mutate them in place.

Returns

readonly (RayHit | null | undefined)[]

One result per ray; undefined or null entries are misses.

setEnabled()

setEnabled(entity, enabled): void;

Enable or disable a body in the broad phase.

Parameters

Parameter	Type	Description
entity	number	Entity with a body.
enabled	boolean	Whether the body participates.

Returns

void

Nothing.

setVelocity()

setVelocity(
   entity, 
   x, 
   y, 
   z, 
   ax?, 
   ay?, 
   az?
): void;

Overwrite a body's velocity.

Angular velocity is left alone unless all three angular components are given.

Parameters

Parameter	Type	Description
entity	number	Entity with a body.
x	number	Linear velocity x.
y	number	Linear velocity y.
z	number	Linear velocity z.
ax?	number	Angular velocity x, radians per second.
ay?	number	Angular velocity y.
az?	number	Angular velocity z.

Returns

void

Nothing.

teleport()

teleport(
   entity, 
   x, 
   y, 
   z
): void;

Teleport a body, clearing its velocities.

Parameters

Parameter	Type	Description
entity	number	Entity with a body.
x	number	Position x.
y	number	Position y.
z	number	Position z.

Returns

void

Nothing.

player

readonly player: number;

The entity the declarative player block spawned, or 0.

rng

readonly rng: Rng;

The seeded generator. Never Math.random.

rules

readonly rules: Readonly<Record<string, unknown>>;

The rules object from defineGame, verbatim.

world

readonly world: object;

The bitecs world, for query, addComponent and friends.

Methods

assetId()

assetId(name): number;

Resolve a manifest string id to a handle, cached.

Parameters

Parameter	Type
name	string

Returns

number

despawn()

despawn(entity): void;

Destroy an entity and its body.

Parameters

Parameter	Type
entity	number

Returns

void

spawn()

spawn(
   def, 
   position, 
   rotation?
): number;

Instantiate a prefab.

Parameters

Parameter	Type
def	PrefabDef
position	Vec3
rotation?	Quat

Returns

number

---

GameError

The error payload of init and restore.

Properties

code

code: ErrorCode;

message

message: string;

---

GamepadState

One gamepad in the standard mapping.

Properties

axes

axes: ArrayLike<number>;

buttons

buttons: number;

connected

connected: boolean;

index

index: number;

pressed

pressed: number;

released

released: number;

---

GameSpec

Everything a game declares.

Properties

assets?

optional assets?: readonly string[];

Manifest string ids to resolve during init and cache.

init?

optional init?: (ctx) => void;

Extra setup, run after the declarative spawns.

Parameters

Parameter	Type
ctx	GameContext

Returns

void

player?

optional player?: PlayerSpec;

The player and its camera.

restore?

optional restore?: (state) => void;

Read back what snapshot returned.

Parameters

Parameter	Type
state	unknown

Returns

void

rules?

optional rules?: Record<string, unknown>;

Arbitrary tuning values, handed back as ctx.rules.

shutdown?

optional shutdown?: (ctx) => void;

Called once before the guest is torn down.

Parameters

Parameter	Type
ctx	GameContext

Returns

void

snapshot?

optional snapshot?: () => unknown;

Extra state to fold into snapshot(). Must be JSON-serialisable.

Returns

unknown

spawns?

optional spawns?: readonly SpawnSpec[];

Entities to create during init.

systems?

optional systems?: readonly System[];

User systems, run in order after the built-ins.

update?

optional update?: (ctx) => void;

Convenience: one more system, run after systems.

Parameters

Parameter	Type
ctx	GameContext

Returns

void

world?

optional world?: WorldSpec;

World settings.

---

Guest

A guest instance: the five WIT exports plus a liveness flag.

Extends

• GuestExports

Properties

dead

readonly dead: boolean;

True once the runtime has given up on user code.

state

readonly state: RuntimeState;

The runtime, for tests and tooling.

Methods

init()

init(config): void;

Parameters

Parameter	Type
config	GameConfig

Returns

void

Inherited from

GuestExports.init

restore()

restore(state): void;

Parameters

Parameter	Type
state	ArrayLike<number>

Returns

void

Inherited from

GuestExports.restore

shutdown()

shutdown(): void;

Returns

void

Inherited from

GuestExports.shutdown

snapshot()

snapshot(): Uint8Array;

Returns

Uint8Array

Inherited from

GuestExports.snapshot

tick()

tick(input): FrameOutput;

Parameters

Parameter	Type
input	FrameInput

Returns

FrameOutput

Inherited from

GuestExports.tick

---

GuestExports

The five functions the WIT game interface exports.

Extended by

• Guest

Methods

init()

init(config): void;

Parameters

Parameter	Type
config	GameConfig

Returns

void

restore()

restore(state): void;

Parameters

Parameter	Type
state	ArrayLike<number>

Returns

void

shutdown()

shutdown(): void;

Returns

void

snapshot()

snapshot(): Uint8Array;

Returns

Uint8Array

tick()

tick(input): FrameOutput;

Parameters

Parameter	Type
input	FrameInput

Returns

FrameOutput

---

HealthStore

Current and maximum hit points.

Properties

current

current: Float32Array;

max

max: Float32Array;

---

HostApi

The host services a guest may call, in guest-side JS shapes.

This is the SDK's own narrow view of the three aos:engine import interfaces. packages/sdk/src/wit/entry.ts adapts the real WIT imports to it; @aosengine/test-harness implements it directly for node tests.

Extended by

• MockHost

Methods

describe()

describe(id): AssetDesc | null | undefined;

Metadata for a handle, or nullish when the handle is unknown.

Parameters

Parameter	Type
id	number

Returns

AssetDesc | null | undefined

log()

log(level, msg): void;

Route a message to the host logger.

Parameters

Parameter	Type
level	LogLevel
msg	string

Returns

void

nowMs()

nowMs(): number;

Monotonic milliseconds since engine start. Never feed this to simulation.

Returns

number

overlapSphere()

overlapSphere(
   center, 
   radius, 
   filter, 
   maxResults
): readonly OverlapHit[];

Bodies overlapping a sphere, nearest first.

Parameters

Parameter	Type
center	Vec3
radius	number
filter	QueryFilter
maxResults	number

Returns

readonly OverlapHit[]

raycast()

raycast(
   origin, 
   direction, 
   maxDistance, 
   filter
): RayHit | null | undefined;

Closest hit along a ray, or nullish on a miss.

Parameters

Parameter	Type
origin	Vec3
direction	Vec3
maxDistance	number
filter	QueryFilter

Returns

RayHit | null | undefined

raycastBatch()

raycastBatch(rays): readonly (RayHit | null | undefined)[];

One round trip for many rays; result index i matches rays[i].

Parameters

Parameter	Type
rays	readonly RayQuery[]

Returns

readonly (RayHit | null | undefined)[]

resolveId()

resolveId(name): number | null | undefined;

Manifest string id to handle, or nullish when the manifest has no entry.

Parameters

Parameter	Type
name	string

Returns

number | null | undefined

seed()

seed(): number;

The deterministic run seed, as a number (already Number()-coerced).

Returns

number

---

HostFrameInput

frame-input in host-side shapes.

jco lifts u64 to bigint on the host and to number in the guest, and the host is free to hand over real typed arrays. Everything else is identical, which is why the guest types accept ArrayLike<number>.

Properties

bodies

bodies: Float32Array;

contacts

contacts: readonly Contact[];

dt

dt: number;

elapsed

elapsed: number;

events

events: readonly GameEvent[];

frame

frame: bigint;

input

input: InputState;

---

HostGameConfig

game-config in host-side shapes: seed is a bigint.

Properties

devMode

devMode: boolean;

fixedHz

fixedHz: number;

options?

optional options?: string;

seed

seed: bigint;

viewportHeight

viewportHeight: number;

viewportWidth

viewportWidth: number;

---

HudState

HUD change detection state.

Properties

last

last: Record<string, unknown> | null;

Shallow copy of the last model the game set, or null before the first.

pending

pending: string | undefined;

JSON to emit this frame, or undefined when the model did not change.

---

InputMods

Keyboard modifier state. Every key is present on input.

Properties

alt

alt: boolean;

capsLock

capsLock: boolean;

ctrl

ctrl: boolean;

meta

meta: boolean;

numLock

numLock: boolean;

shift

shift: boolean;

---

InputState

Everything the host knows about input for one fixed step.

Extended by

• MutableInputState

Properties

focused

focused: boolean;

gamepads

gamepads: readonly GamepadState[];

keys

keys: KeyState;

mods

mods: InputMods;

mouse

mouse: MouseState;

---

KeyState

256 key codes packed into 8 u32 words, one list per edge.

Properties

down

down: ArrayLike<number>;

pressed

pressed: ArrayLike<number>;

released

released: ArrayLike<number>;

---

LoadAssetCmd

Ask the host to start loading an asset.

Properties

asset

asset: number;

priority

priority: number;

---

LookAtCmd

Aim a character's head and eyes at a world point.

Properties

entity

entity: number;

target?

optional target?: Vec3;

weight

weight: number;

---

LookState

First-person / third-person look accumulator owned by the built-in camera.

Properties

pitch

pitch: number;

sensitivity

sensitivity: number;

yaw

yaw: number;

---

MouseState

Pointer position, deltas, wheel and button edges for one frame.

Properties

buttons

buttons: number;

dx

dx: number;

dy

dy: number;

locked

locked: boolean;

pressed

pressed: number;

released

released: number;

wheel

wheel: number;

x

x: number;

y

y: number;

---

MoveCharacterCmd

Drive a character body for one step.

Properties

body

body: number;

crouch

crouch: boolean;

desiredVelocity

desiredVelocity: Vec3;

jump

jump: boolean;

maxSlopeDeg

maxSlopeDeg: number;

---

MutableGamepad

A gamepad snapshot the SDK owns and reuses every frame.

Properties

axes

axes: Float32Array;

Standard mapping: lx, ly, rx, ry, left trigger, right trigger.

buttons

buttons: number;

connected

connected: boolean;

index

index: number;

pressed

pressed: number;

released

released: number;

---

OverlapHit

One body overlapping a query volume.

Properties

body

body: number;

depth

depth: number;

entity

entity: number;

point

point: Vec3;

---

PlayerSpec

The declarative player block.

Properties

camera?

optional camera?: "firstPerson" | "thirdPerson";

Which built-in camera rig to drive.

distance?

optional distance?: number;

Third-person boom length, metres. Default 4.

eyeHeight?

optional eyeHeight?: number;

First-person eye height, metres. Default 1.7.

height?

optional height?: number;

Third-person height offset, metres. Default 1.6.

prefab?

optional prefab?: PrefabDef;

Prefab to spawn for the player.

sensitivity?

optional sensitivity?: number;

Radians of look per pixel of mouse movement. Default 0.0025.

spawn?

optional spawn?: readonly number[];

Spawn position, [x, y, z]. Default [0, 0, 0].

---

PlayOptions

Options for audio.play.

Properties

bus?

optional bus?: AudioBus;

Mixer bus. Default 'sfx'.

entity?

optional entity?: number;

Attach to an entity for positional audio that follows it.

looping?

optional looping?: boolean;

Loop until stopped. Default false.

pitch?

optional pitch?: number;

Playback-rate multiplier. Default 1.

volume?

optional volume?: number;

Linear gain in 0..1. Default 1.

---

PlaySoundCmd

Start a sound.

Properties

asset

asset: number;

bus

bus: AudioBus;

entity?

optional entity?: number;

looping

looping: boolean;

pitch

pitch: number;

position?

optional position?: Vec3;

sound

sound: number;

volume

volume: number;

---

PrefabDef

A prefab, ready to spawn.

Extends

• PrefabSpec

Properties

asset?

optional asset?: string | number;

Renderable asset: a manifest string id, or a handle.

Inherited from

PrefabSpec.asset

body?

optional body?: BodySpec;

Physics body, if any.

Inherited from

PrefabSpec.body

character?

optional character?: string | number;

Splat character bundle: a manifest string id, or a handle.

Inherited from

PrefabSpec.character

components?

optional components?: readonly object[];

Extra bitecs components and tags to add on spawn.

Inherited from

PrefabSpec.components

health?

optional health?: number;

Starting hit points; adds the Health component when present.

Inherited from

PrefabSpec.health

name?

optional name?: string;

Debug label shown in the engine overlay.

Inherited from

PrefabSpec.name

prefabId

readonly prefabId: number;

Stable index, assigned in declaration order.

scale?

optional scale?: readonly number[];

Uniform or per-axis scale. Default [1, 1, 1].

Inherited from

PrefabSpec.scale

---

PrefabSpec

Everything a prefab can declare.

Extended by

• PrefabDef

Properties

asset?

optional asset?: string | number;

Renderable asset: a manifest string id, or a handle.

body?

optional body?: BodySpec;

Physics body, if any.

character?

optional character?: string | number;

Splat character bundle: a manifest string id, or a handle.

components?

optional components?: readonly object[];

Extra bitecs components and tags to add on spawn.

health?

optional health?: number;

Starting hit points; adds the Health component when present.

name?

optional name?: string;

Debug label shown in the engine overlay.

scale?

optional scale?: readonly number[];

Uniform or per-axis scale. Default [1, 1, 1].

---

Quat

A unit quaternion in xyzw order (three.js / Jolt order).

Properties

w

w: number;

x

x: number;

y

y: number;

z

z: number;

---

QueryFilter

Which bodies a physics query considers.

Properties

excludeBody?

optional excludeBody?: number;

excludeEntity?

optional excludeEntity?: number;

layers

layers: CollisionLayers;

solidOnly

solidOnly: boolean;

---

RayHit

Closest hit along a ray.

Properties

body

body: number;

distance

distance: number;

entity

entity: number;

normal

normal: Vec3;

point

point: Vec3;

---

RayQuery

One ray in a raycastBatch call.

Properties

direction

direction: Vec3;

filter

filter: QueryFilter;

maxDistance

maxDistance: number;

origin

origin: Vec3;

---

RenderableStore

Renderable asset handle plus host-side flags.

Properties

asset

asset: Uint32Array;

Manifest asset handle; 0 means "no renderable".

dirty

dirty: Uint8Array;

Non-zero when the host has not yet seen the current value.

flags

flags: Uint32Array;

Reserved host flags bitset.

---

Rgba

Linear RGBA, components in 0..1.

Properties

a

a: number;

b

b: number;

g

g: number;

r

r: number;

---

RigidBodyStore

Rigid body handle and classification.

Properties

dirty

dirty: Uint8Array;

Non-zero when the host has not yet seen the current value.

groundState

groundState: Uint8Array;

Post-step contact: 0 unknown, 1 ground, 2 steep, 3 unsupported, 4 air.

handle

handle: Uint32Array;

Guest-minted body id; 0 means "no body".

kind

kind: Uint8Array;

BODY_KIND index.

shape

shape: Uint8Array;

SHAPE_KIND index.

---

Rng

A seeded, serialisable random source.

Methods

float()

float(): number;

Next float in [0, 1).

Returns

number

int()

int(n): number;

Next integer in [0, n). Returns 0 when n <= 0.

Parameters

Parameter	Type
n	number

Returns

number

load()

load(state): void;

Overwrite the state.

Parameters

Parameter	Type
state	RngState

Returns

void

pick()

pick<T>(items): T | undefined;

A uniformly chosen element, or undefined when the array is empty.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
items	ArrayLike<T>

Returns

T | undefined

range()

range(min, max): number;

Next float in [min, max).

Parameters

Parameter	Type
min	number
max	number

Returns

number

save()

save(out?): RngState;

Copy the state out, into out when given.

Parameters

Parameter	Type
out?	RngState

Returns

RngState

seed()

seed(value): void;

Re-seed from a 32-bit integer.

Parameters

Parameter	Type
value	number

Returns

void

uint32()

uint32(): number;

Next u32.

Returns

number

---

RngState

Four-word xoshiro128** state, as it appears in a snapshot.

Properties

s0

s0: number;

s1

s1: number;

s2

s2: number;

s3

s3: number;

---

RuntimeState

Everything one guest instance owns.

Properties

assetDescs

assetDescs: Map<number, AssetDesc | null>;

Asset handle to its description, cached because the manifest is immutable for the life of a run. Per runtime, never module scope: a parity run has a direct guest and a wasm guest, with different hosts, in one realm.

assetIds

assetIds: Map<string, number>;

Manifest string id to asset handle, resolved once and cached.

bodyIndex

bodyIndex: BodyIndex;

camera

camera: CameraState;

carryCommands

carryCommands: boolean;

True when the command buffer holds commands built outside tick — the spawns init queued. The next tick keeps them instead of resetting.

commands

commands: CommandBuffer;

config

config: GameConfig;

contacts

contacts: readonly Contact[];

dead

dead: boolean;

Set after repeated user-code failures; the host must rebuild the sandbox.

dt

dt: number;

elapsed

elapsed: number;

events

events: readonly GameEvent[];

failures

failures: number;

Consecutive failed ticks.

focused

focused: boolean;

frame

frame: number;

gamepadCount

gamepadCount: number;

gamepads

gamepads: MutableGamepad[];

host

host: HostApi;

hud

hud: HudState;

initialised

initialised: boolean;

True once init has completed. Asset resolution warns after this.

keysDown

keysDown: Uint32Array;

keysPressed

keysPressed: Uint32Array;

keysReleased

keysReleased: Uint32Array;

look

look: LookState;

mods

mods: InputMods;

mouse

mouse: MouseState;

nextBody

nextBody: number;

Next guest-minted body id. Counters start at 1; 0 means "none".

nextSound

nextSound: number;

Next guest-minted sound handle.

packer

packer: TransformPacker;

player

player: number;

The player entity, when the declarative player block created one.

rng

rng: Rng;

world

world: object;

The bitecs world. Typed loosely so the SDK does not leak bitecs generics.

---

SayCmd

Speak a line, optionally with audio and a viseme track.

Properties

audio?

optional audio?: number;

entity

entity: number;

text

text: string;

visemes?

optional visemes?: string;

---

SetAnimCmd

Play or cross-fade an animation clip on one layer.

Properties

clip

clip: string;

entity

entity: number;

fadeMs

fadeMs: number;

looping

looping: boolean;

speed

speed: number;

weight

weight: number;

---

SetAssetCmd

Attach or detach an entity's renderable.

Properties

asset?

optional asset?: number;

entity

entity: number;

---

SetBodyEnabledCmd

Enable or disable a body in the broad phase.

Properties

body

body: number;

enabled

enabled: boolean;

---

SetBodyTransformCmd

Move a body directly.

Properties

body

body: number;

position

position: Vec3;

rotation

rotation: Quat;

teleport

teleport: boolean;

---

SetBodyVelocityCmd

Overwrite a body's velocities. undefined leaves one untouched.

Properties

angular?

optional angular?: Vec3;

body

body: number;

linear?

optional linear?: Vec3;

---

SetCharacterStateCmd

Drive a character's locomotion state machine.

Properties

entity

entity: number;

grounded

grounded: boolean;

state

state: string;

velocity

velocity: Vec3;

---

SetClipWeightsCmd

Set explicit per-clip weights on a character's body layer.

Properties

clips

clips: readonly string[];

entity

entity: number;

timeScale

timeScale: number;

weights

weights: Float32Array<ArrayBufferLike> | readonly number[];

---

SetExpressionCmd

Set a character's facial expression coefficients.

Properties

entity

entity: number;

space

space: ExpressionSpace;

weights

weights: Float32Array<ArrayBufferLike> | readonly number[];

---

SetListenerCmd

Place the audio listener.

Properties

position

position: Vec3;

rotation

rotation: Quat;

velocity

velocity: Vec3;

---

SetMaterialParamCmd

Set one material uniform.

Properties

entity

entity: number;

name

name: string;

value

value: MaterialValue;

---

SetParentCmd

Reparent an entity in the scene graph.

Properties

entity

entity: number;

keepWorldTransform

keepWorldTransform: boolean;

parent?

optional parent?: number;

---

Shape

Collision shape description carried by add-body.

Properties

asset?

optional asset?: number;

halfExtents

halfExtents: Vec3;

kind

kind: ShapeKind;

---

SoundEndedEvent

A playing sound stopped.

Properties

completed

completed: boolean;

sound

sound: number;

---

SpawnCharacterCmd

Instantiate a splat character bundle.

Properties

bundle

bundle: number;

entity

entity: number;

position

position: Vec3;

rotation

rotation: Quat;

---

SpawnCmd

Create an entity, optionally with a renderable asset.

Properties

asset?

optional asset?: number;

entity

entity: number;

name?

optional name?: string;

parent?

optional parent?: number;

position

position: Vec3;

rotation

rotation: Quat;

scale

scale: Vec3;

visible

visible: boolean;

---

SpawnSpec

One entry of the declarative spawns list.

Properties

position

position: readonly number[];

Where, [x, y, z].

prefab

prefab: PrefabDef;

What to spawn.

rotation?

optional rotation?: readonly number[];

Rotation, [x, y, z, w]. Defaults to identity.

---

StopSoundCmd

Stop a playing sound.

Properties

fadeMs

fadeMs: number;

sound

sound: number;

---

ThirdPersonClips

Optional authored clips; omit to use the animator's standard locomotion blend.

Properties

fall

fall: string;

idle

idle: string;

land

land: string;

rise

rise: string;

run

run: string;

walk

walk: string;

---

TransformStore

Position, rotation (xyzw) and scale, one lane per component.

Properties

qw

qw: Float32Array;

qx

qx: Float32Array;

qy

qy: Float32Array;

qz

qz: Float32Array;

sx

sx: Float32Array;

sy

sy: Float32Array;

sz

sz: Float32Array;

x

x: Float32Array;

y

y: Float32Array;

z

z: Float32Array;

---

Vec3

A 3-component vector.

Properties

x

x: number;

y

y: number;

z

z: number;

---

VelocityStore

Linear and angular velocity in metres and radians per second.

Properties

ax

ax: Float32Array;

ay

ay: Float32Array;

az

az: Float32Array;

x

x: Float32Array;

y

y: Float32Array;

z

z: Float32Array;

---

WorldSpec

World-level settings.

Properties

gravity?

optional gravity?: number | readonly number[];

Gravity in metres per second squared, applied by the built-in velocity system to entities that have Velocity but no RigidBody. Bodies get their gravity from the host physics world instead.

maxEntities?

optional maxEntities?: number;

Entity ceiling. Sizes every built-in component array. Default 4096.

Type Aliases

AssetId

type AssetId = number;

Manifest asset handle, resolved from a string id.

---

AssetKind

type AssetKind = "splat" | "gltf" | "character" | "audio" | "collider" | "data";

Manifest asset family.

---

AudioBus

type AudioBus = "master" | "music" | "sfx" | "voice" | "ui";

Audio mixer bus.

---

BodyId

type BodyId = number;

Rigid body / character controller handle.

---

BodyKind

type BodyKind = "fixed" | "kinematic" | "dynamic" | "character";

Physics body class. fixed is what other engines call static.

---

CameraMode

type CameraMode = "first-person" | "third-person" | "free" | "fixed";

Camera rig family.

---

Command

type Command = 
  | {
  tag: "conversation";
  val: ConversationCmd;
}
  | {
  tag: "spawn";
  val: SpawnCmd;
}
  | {
  tag: "despawn";
  val: Entity;
}
  | {
  tag: "set-asset";
  val: SetAssetCmd;
}
  | {
  tag: "set-parent";
  val: SetParentCmd;
}
  | {
  tag: "set-anim";
  val: SetAnimCmd;
}
  | {
  tag: "set-material-param";
  val: SetMaterialParamCmd;
}
  | {
  tag: "add-body";
  val: AddBodyCmd;
}
  | {
  tag: "remove-body";
  val: BodyId;
}
  | {
  tag: "set-body-transform";
  val: SetBodyTransformCmd;
}
  | {
  tag: "set-body-velocity";
  val: SetBodyVelocityCmd;
}
  | {
  tag: "apply-impulse";
  val: ApplyImpulseCmd;
}
  | {
  tag: "set-body-enabled";
  val: SetBodyEnabledCmd;
}
  | {
  tag: "move-character";
  val: MoveCharacterCmd;
}
  | {
  tag: "spawn-character";
  val: SpawnCharacterCmd;
}
  | {
  tag: "set-character-state";
  val: SetCharacterStateCmd;
}
  | {
  tag: "set-clip-weights";
  val: SetClipWeightsCmd;
}
  | {
  tag: "set-expression";
  val: SetExpressionCmd;
}
  | {
  tag: "look-at";
  val: LookAtCmd;
}
  | {
  tag: "say";
  val: SayCmd;
}
  | {
  tag: "play-sound";
  val: PlaySoundCmd;
}
  | {
  tag: "stop-sound";
  val: StopSoundCmd;
}
  | {
  tag: "set-listener";
  val: SetListenerCmd;
}
  | {
  tag: "load-asset";
  val: LoadAssetCmd;
}
  | {
  tag: "set-pointer-lock";
  val: boolean;
}
  | {
  tag: "set-time-scale";
  val: number;
};

Everything the guest can ask the host to do, applied front to back.

---

CommandTag

type CommandTag = Command["tag"];

Every Command['tag'], useful for exhaustive host-side switches.

---

ContactPhase

type ContactPhase = "begin" | "stay" | "end";

Lifecycle phase of a contact.

---

Entity

type Entity = number;

ECS entity handle. 0 is reserved and means "none".

---

ErrorCode

type ErrorCode = 
  | "init-failed"
  | "tick-failed"
  | "invalid-state"
  | "unsupported"
  | "asset-missing"
  | "snapshot-version-mismatch"
  | "internal";

Machine-readable half of a GameError.

---

ExpressionSpace

type ExpressionSpace = "arkit52" | "gnm" | "gnm68";

Coordinate space for setExpression weights.

---

GameDefinition

type GameDefinition = Readonly<GameSpec>;

A validated game declaration.

---

GameEvent

type GameEvent = 
  | {
  tag: "conversation-event";
  val: ConversationEvent;
}
  | {
  tag: "asset-loaded";
  val: AssetLoadedEvent;
}
  | {
  tag: "character-ready";
  val: CharacterReadyEvent;
}
  | {
  tag: "sound-ended";
  val: SoundEndedEvent;
}
  | {
  tag: "anim-event";
  val: AnimEventData;
}
  | {
  tag: "resized";
  val: ResizedEvent;
};

A host-side occurrence since the previous tick.

---

KeyName

type KeyName = string;

Any string this table accepts: a DOM code, a bare letter or digit, or one of the friendly aliases.

---

LogLevel

type LogLevel = "trace" | "debug" | "info" | "warn" | "error";

Log severity accepted by env.log.

---

LogSink

type LogSink = (level, msg) => void;

Where prelude console output goes.

Parameters

Parameter	Type
level	LogLevel
msg	string

Returns

void

---

MaterialValue

type MaterialValue = 
  | {
  tag: "scalar";
  val: number;
}
  | {
  tag: "boolean";
  val: boolean;
}
  | {
  tag: "color";
  val: Rgba;
}
  | {
  tag: "vector";
  val: Vec3;
}
  | {
  tag: "texture";
  val: AssetId;
};

A material parameter value.

---

ProjectionKind

type ProjectionKind = "perspective" | "orthographic";

Camera projection family.

---

ShapeKind

type ShapeKind = 
  | "box"
  | "sphere"
  | "capsule"
  | "cylinder"
  | "plane"
  | "convex-hull"
  | "mesh"
  | "height-field";

Collision shape family.

---

SoundId

type SoundId = number;

Playing-sound handle.

---

System

type System = (ctx) => void;

A system: one plain function, run once per fixed step.

Parameters

Parameter	Type
ctx	GameContext

Returns

void

Variables

audio

const audio: object;

The audio facade.

Type Declaration

listener()

listener(position, rotation): void;

Place the audio listener.

Parameters

Parameter	Type	Description
position	Vec3	Listener position.
rotation	Quat	Listener rotation, xyzw.

Returns

void

Nothing.

play()

play(asset, options?): number;

Start a sound.

Parameters

Parameter	Type	Description
asset	string | number	Manifest string id or asset handle.
options?	PlayOptions	Attachment, gain, pitch, looping and bus.

Returns

number

The guest-minted sound handle, or 0 when the asset is unknown.

stop()

stop(sound, fadeMs?): void;

Stop a playing sound.

Parameters

Parameter	Type	Default value	Description
sound	number	undefined	A handle from play.
fadeMs	number	0	Fade-out in milliseconds; 0 stops immediately.

Returns

void

Nothing.

Example

import { audio } from '@aosengine/sdk';

const id = audio.play('shot', { entity: player, volume: 0.8 });
audio.stop(id, 50);

---

BODY_KINDS

const BODY_KINDS: readonly ["fixed", "kinematic", "dynamic", "character"];

Physics body classes, in the index order RigidBody.kind stores.

---

BODY_STRIDE

const BODY_STRIDE: 15 = 15;

Floats per row of frame-input.bodies.

---

BUILTIN_COMPONENT_NAMES

const BUILTIN_COMPONENT_NAMES: readonly ["Transform", "Renderable", "RigidBody", "Character", "Velocity", "Health", "Player", "Enemy", "Pickup"];

Names matching BUILTIN_COMPONENTS, used in snapshot headers.

---

BUILTIN_COMPONENTS

const BUILTIN_COMPONENTS: readonly [TransformStore, RenderableStore, RigidBodyStore, CharacterStore, VelocityStore, HealthStore, Record<string, never>, Record<string, never>, Record<string, never>];

Every built-in component, in the fixed order snapshot serialises them.

---

camera

const camera: object;

The camera facade.

Type Declaration

look

Get Signature

get look(): object;

Accumulated look angles, in radians. Mutate to snap the view.

Returns

object

The live look state.

pitch

pitch: number;

sensitivity

sensitivity: number;

yaw

yaw: number;

state

Get Signature

get state(): CameraState;

The whole camera record, for games that want every knob.

Returns

CameraState

The live record. Mutate it; do not replace it.

firstPerson()

firstPerson(entity, options?): void;

Mount the camera at an entity's eyes.

Yaw and pitch come from the built-in look accumulator, which integrates input.mouse.dx/dy once per tick.

Parameters

Parameter	Type	Description
entity	number	Entity to mount on.
options?	FirstPersonOptions	Eye height and field of view.

Returns

void

Nothing.

follow()

follow(entity, options?): void;

Put the camera on a spring arm behind an entity.

The host owns the arm and its collision; the guest only states the intent. position is the orbit pivot and rotation the direction the player is looking, so a host with no rig still ends up somewhere sensible.

Parameters

Parameter	Type	Description
entity	number	Entity to follow.
options?	FollowOptions	Boom length, height offset, field of view and orbit angles.

Returns

void

Nothing.

lookAt()

lookAt(target): void;

Aim the camera at a world point, overriding its rotation.

Parameters

Parameter	Type	Description
target	Vec3 | null	The point to look at, or null to use the rotation again.

Returns

void

Nothing.

set()

set(
   position, 
   rotation, 
   fovYDeg?
): void;

Place the camera explicitly, detaching it from any entity.

Parameters

Parameter	Type	Default value	Description
position	Vec3	undefined	Eye position.
rotation	Quat	undefined	Eye rotation, xyzw.
fovYDeg	number	60	Vertical field of view in degrees. Default 60.

Returns

void

Nothing.

Example

import { camera } from '@aosengine/sdk';

camera.firstPerson(player, { eyeHeight: 1.7 });

---

character

const character: object;

The character facade.

Type Declaration

bundleOf()

bundleOf(entity): number;

The character bundle handle attached to an entity, or 0.

Parameters

Parameter	Type	Description
entity	number	Entity id.

Returns

number

The bundle asset handle.

lookAt()

lookAt(
   entity, 
   target, 
   weight?
): void;

Aim the head and eyes at a world point.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity with a Character component.
target	Vec3 | null	undefined	The point, or null to release and return to the idle.
weight	number	1	Blend weight in 0..1. Default 1.

Returns

void

Nothing.

say()

say(
   entity, 
   text, 
   voice?, 
   visemes?
): void;

Speak a line.

Parameters

Parameter	Type	Description
entity	number	Entity with a Character component.
text	string	Subtitle text; the host decides whether to show it.
voice?	string | number	Manifest string id or handle of a voice line.
visemes?	string	Viseme track as JSON, matching the bundle's space.

Returns

void

Nothing.

setClipWeights()

setClipWeights(
   entity, 
   clips, 
   weights, 
   timeScale?
): void;

Set explicit per-clip weights on the body layer.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity with a Character component.
clips	readonly string[]	undefined	Clip names.
weights	Float32Array<ArrayBufferLike> | readonly number[]	undefined	Positional weights; must be the same length as clips.
timeScale	number	1	Playback rate for the whole layer. Default 1.

Returns

void

Nothing.

setExpression()

setExpression(
   entity, 
   space, 
   weights
): void;

Set facial expression coefficients.

Parameters

Parameter	Type	Description
entity	number	Entity with a Character component.
space	ExpressionSpace	Coordinate space: 52 ARKit, 387 GNM, or the 68-float view.
weights	Float32Array<ArrayBufferLike> | readonly number[]	Coefficients; length must match the space.

Returns

void

Nothing.

setState()

setState(
   entity, 
   state, 
   vx, 
   vy, 
   vz, 
   grounded?
): void;

Drive the locomotion state machine.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity with a Character component.
state	string	undefined	State name, for example `'idle'
vx	number	undefined	World-space velocity x, drives the locomotion blend.
vy	number	undefined	World-space velocity y.
vz	number	undefined	World-space velocity z.
grounded	boolean	true	Whether the character is on the ground.

Returns

void

Nothing.

Example

import { character } from '@aosengine/sdk';

character.setState(npc, 'walk', 0, 0, 1.4, true);
character.lookAt(npc, { x: 0, y: 1.6, z: 0 });

---

Character

const Character: CharacterStore;

Splat character bundle attached to an entity.

---

conversation

const conversation: object;

Structural interview controls; all streams remain in optional host modules.

Type Declaration

command()

command(
   entity, 
   action, 
   character?, 
   text?
): void;

Queue one control using the reusable command pool.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Interview entity.
action	| "end" | "start" | "ask" | "interrupt" | "microphone-on" | "microphone-off"	undefined	Lifecycle or question action.
character	string	''	Host-configured id.
text	string	''	Question, if any.

Returns

void

Example

import { conversation } from '@aosengine/sdk';
conversation.command(npc, 'start', 'steward');
conversation.command(npc, 'ask', 'steward', 'Who had the study key?');

---

DEFAULT_MAX_ENTITIES

const DEFAULT_MAX_ENTITIES: 4096 = 4096;

Default entity ceiling. Every built-in component array is this long.

---

Enemy

const Enemy: Record<string, never> = {};

Tag: a hostile entity.

---

EXPRESSION_DIMS

const EXPRESSION_DIMS: Readonly<Record<ExpressionSpace, number>>;

Coefficient counts each expression space expects.

---

Health

const Health: HealthStore;

Hit points.

---

hud

const hud: object;

The HUD facade.

Type Declaration

clear()

clear(): void;

Drop the HUD: emit an empty model this frame.

Idempotent — calling it every frame emits {} once, exactly like set.

Returns

void

Nothing.

invalidate()

invalidate(): void;

Forget what the host has seen, so the next set emits even if the model did not change. Use it after the host reloaded its overlay.

On its own it sends nothing: the next set does. To send an empty model now, call clear().

Returns

void

Nothing.

set()

set(model): boolean;

Set the HUD model for this frame.

Nested plain objects are compared by value four levels down, so a model rebuilt inline every frame is recognised as unchanged. Arrays and class instances are compared by identity: keep those out of the model, or build them once and mutate nothing.

Parameters

Parameter	Type	Description
model	Record<string, unknown>	A JSON-serialisable object.

Returns

boolean

True when the model changed and JSON will cross this frame.

Example

import { hud } from '@aosengine/sdk';

hud.set({ health: 100, ammo: 30 }); // emitted once
hud.set({ health: 100, ammo: 30 }); // unchanged, nothing crosses

---

input

const input: object;

The keyboard, mouse and gamepad facade.

Type Declaration

focused

Get Signature

get focused(): boolean;

Does the canvas have focus? Treat input as neutral when it does not.

Returns

boolean

True while the canvas is focused.

mods

Get Signature

get mods(): InputMods;

Keyboard modifier state.

Returns

InputMods

The modifiers for this frame.

mouse

Get Signature

get mouse(): MouseState;

Pointer position, per-frame delta, wheel and button bitsets.

Returns

MouseState

The mouse state for this frame. Owned by the SDK; never retain it.

axis2()

axis2(
   negX, 
   posX, 
   negY, 
   posY
): Axis2;

A two-axis reading built from four keys.

Parameters

Parameter	Type	Description
negX	string	Key that drives x negative, for example 'A'.
posX	string	Key that drives x positive, for example 'D'.
negY	string	Key that drives y negative, for example 'S'.
posY	string	Key that drives y positive, for example 'W'.

Returns

Axis2

A pooled { x, y } with components in -1..1. Never retain it.

gamepad()

gamepad(index): 
  | {
  axes: ArrayLike<number>;
  buttons: number;
  connected: boolean;
  index: number;
  pressed: number;
  released: number;
}
  | null;

One connected gamepad.

Parameters

Parameter	Type	Description
index	number	Navigator gamepad index.

Returns

| { axes: ArrayLike<number>; buttons: number; connected: boolean; index: number; pressed: number; released: number; } | null

The gamepad, or null when nothing is connected at that index. Owned by the SDK; never retain it.

isDown()

isDown(key): boolean;

Is the key held this frame?

Parameters

Parameter	Type	Description
key	string	A DOM code ('KeyW'), a bare letter/digit ('W', '1') or an alias ('Shift', 'Esc').

Returns

boolean

True while the key is down.

mouseDown()

mouseDown(button): boolean;

Is a mouse button held?

Parameters

Parameter	Type	Description
button	number	A MOUSE_BUTTONS value, or a raw bit mask.

Returns

boolean

True while the button is down.

mousePressed()

mousePressed(button): boolean;

Did a mouse button go down this frame?

Parameters

Parameter	Type	Description
button	number	A MOUSE_BUTTONS value, or a raw bit mask.

Returns

boolean

True on the frame the button went down.

mouseReleased()

mouseReleased(button): boolean;

Did a mouse button come up this frame?

Parameters

Parameter	Type	Description
button	number	A MOUSE_BUTTONS value, or a raw bit mask.

Returns

boolean

True on the frame the button came up.

pressed()

pressed(key): boolean;

Did the key go down this frame?

Parameters

Parameter	Type	Description
key	string	A key name.

Returns

boolean

True on the frame the key went down.

released()

released(key): boolean;

Did the key come up this frame?

Parameters

Parameter	Type	Description
key	string	A key name.

Returns

boolean

True on the frame the key came up.

Example

import { input } from '@aosengine/sdk';

const move = input.axis2('A', 'D', 'S', 'W'); // x = strafe, y = forward
if (input.pressed('Space')) jump();
if (input.mouseDown(1)) fire();

---

IS_COMPONENT_GUEST

const IS_COMPONENT_GUEST: boolean;

True when this realm looks like the QuickJS component guest rather than V8.

Decided once, before anything is polyfilled: a realm with neither console nor TextEncoder is componentize-qjs. It is the only realm whose Math.random the prelude is allowed to replace — patching the global in V8 would reach vitest, Vite and the host application too.

---

KEY_BITS

const KEY_BITS: 256 = 256;

Number of key bits the WIT key-state bitsets can carry.

---

KEY_COUNT

const KEY_COUNT: number = KEY_NAMES.length;

Number of key names currently assigned.

---

KEY_NAMES

const KEY_NAMES: readonly string[];

Every key name in index order. The array index is the bit index.

Do not reorder; append only.

---

KEY_WORDS

const KEY_WORDS: number;

Number of u32 words in one key-state bitset.

---

LAYER_KEYS

const LAYER_KEYS: readonly ["defaultLayer", "staticGeometry", "player", "enemy", "projectile", "pickup", "trigger", "character", "debris", "water", "user0", "user1", "user2", "user3", "user4", "user5"];

Every WIT collision-layers member, in declaration order.

Bit i of the physics module's numeric layer/mask is member i of this list. It is a contract between the guest, which writes the flags record, and the host, which folds it into a bitmask — so both sides import this one list rather than keeping a copy each.

Example

import { LAYER_KEYS } from '@aosengine/sdk';

const bit = LAYER_KEYS.indexOf('enemy'); // 3

---

MOUSE_BUTTONS

const MOUSE_BUTTONS: Readonly<{
  BACK: 8;
  FORWARD: 16;
  LEFT: 1;
  MIDDLE: 4;
  RIGHT: 2;
}>;

Mouse button bit positions, matching mouse-state.buttons.

---

PACKAGE

const PACKAGE: "@aosengine/sdk";

Package identity marker.

Example

import { PACKAGE } from '@aosengine/sdk';

console.log(PACKAGE); // '@aosengine/sdk'

---

physics

const physics: object;

Physics queries and body commands.

Type Declaration

ALL_LAYERS

ALL_LAYERS: CollisionLayers;

Every collision layer, for queries that should hit anything.

applyImpulse()

applyImpulse(
   entity, 
   x, 
   y, 
   z, 
   atX?, 
   atY?, 
   atZ?
): void;

Apply a one-shot impulse.

With no application point the impulse acts at the centre of mass. Give one — all three coordinates — to apply it off-centre and impart spin.

Parameters

Parameter	Type	Description
entity	number	Entity with a body.
x	number	Impulse x, newton-seconds.
y	number	Impulse y.
z	number	Impulse z.
atX?	number	World-space application point x, or omit for the centre of mass.
atY?	number	Application point y.
atZ?	number	Application point z.

Returns

void

Nothing.

isGrounded()

isGrounded(entity): boolean;

Actual walkable ground contact from the last host physics step. No host call. Unknown, steep and unsupported contacts return false, even at a jump apex.

Parameters

Parameter	Type	Description
entity	number	Character entity.

Returns

boolean

Whether the character is supported by walkable ground.

moveCharacter()

moveCharacter(
   entity, 
   vx, 
   vy, 
   vz, 
   jump?, 
   crouch?, 
   maxSlopeDeg?
): void;

Drive a character body for this step.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity whose body was created with kind: 'character'.
vx	number	undefined	Desired world-space velocity x, metres per second.
vy	number	undefined	Desired world-space velocity y.
vz	number	undefined	Desired world-space velocity z.
jump	boolean	false	Request a jump this step.
crouch	boolean	false	Request a crouch this step.
maxSlopeDeg	number	45	Maximum walkable slope.

Returns

void

Nothing.

overlapSphere()

overlapSphere(
   center, 
   radius, 
   maxResults?, 
   mask?, 
   ignoreEntity?
): readonly OverlapHit[];

Bodies overlapping a sphere, nearest first.

Parameters

Parameter	Type	Default value	Description
center	Vec3	undefined	Sphere centre.
radius	number	undefined	Sphere radius in metres.
maxResults	number	16	Cap on returned hits.
mask?	CollisionLayers	undefined	Layers to consider; defaults to every layer.
ignoreEntity?	number	undefined	Entity to skip.

Returns

readonly OverlapHit[]

The overlapping bodies.

raycast()

raycast(
   origin, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Closest hit along a ray.

Parameters

Parameter	Type	Description
origin	Vec3	World-space ray origin.
direction	Vec3	Ray direction; need not be normalised.
maxDistance	number	Maximum distance in metres.
mask?	CollisionLayers	Layers to consider; defaults to every layer.
ignoreEntity?	number	Entity to skip, usually the caster.

Returns

RayHit | null

The hit, or null on a miss. The hit object comes from the host and is freshly allocated: this call is not allocation-free.

raycastBatch()

raycastBatch(rays): readonly (RayHit | null | undefined)[];

Many rays in one round trip. Result index i matches rays[i].

Parameters

Parameter	Type	Description
rays	readonly object[]	The rays. Build them once and mutate them in place.

Returns

readonly (RayHit | null | undefined)[]

One result per ray; undefined or null entries are misses.

setEnabled()

setEnabled(entity, enabled): void;

Enable or disable a body in the broad phase.

Parameters

Parameter	Type	Description
entity	number	Entity with a body.
enabled	boolean	Whether the body participates.

Returns

void

Nothing.

setVelocity()

setVelocity(
   entity, 
   x, 
   y, 
   z, 
   ax?, 
   ay?, 
   az?
): void;

Overwrite a body's velocity.

Angular velocity is left alone unless all three angular components are given.

Parameters

Parameter	Type	Description
entity	number	Entity with a body.
x	number	Linear velocity x.
y	number	Linear velocity y.
z	number	Linear velocity z.
ax?	number	Angular velocity x, radians per second.
ay?	number	Angular velocity y.
az?	number	Angular velocity z.

Returns

void

Nothing.

teleport()

teleport(
   entity, 
   x, 
   y, 
   z
): void;

Teleport a body, clearing its velocities.

Parameters

Parameter	Type	Description
entity	number	Entity with a body.
x	number	Position x.
y	number	Position y.
z	number	Position z.

Returns

void

Nothing.

Example

import { physics, Transform } from '@aosengine/sdk';

const hit = physics.raycast(eye, forward, 100);
if (hit) console.log('hit entity', hit.entity, 'at', hit.distance);

---

Pickup

const Pickup: Record<string, never> = {};

Tag: something the player can pick up.

---

Player

const Player: Record<string, never> = {};

Tag: the entity the player controls.

---

Renderable

const Renderable: RenderableStore;

Renderable asset attached to an entity.

---

RigidBody

const RigidBody: RigidBodyStore;

Physics body attached to an entity.

---

SHAPE_KINDS

const SHAPE_KINDS: readonly ["box", "sphere", "capsule", "cylinder", "plane", "convex-hull", "mesh", "height-field"];

Collision shapes, in the index order RigidBody.shape stores.

---

SNAPSHOT_VERSION

const SNAPSHOT_VERSION: 2 = 2;

Bumped whenever the byte layout changes. Mismatches refuse to restore.

---

TAG_ORDINAL

const TAG_ORDINAL: Record<CommandTag, number>;

Every command tag mapped to its pool index.

Written out rather than derived so the compiler checks it: Record over the CommandTag union rejects both a missing tag and one that is not in the WIT variant. packages/wasm-host/src/apply.test.ts pins the same list from the host side.

Example

import { TAG_ORDINAL } from '@aosengine/sdk';

console.log(TAG_ORDINAL['set-time-scale']); // 24

---

Transform

const Transform: TransformStore;

World transform of an entity. Position, rotation (xyzw), scale.

---

TRANSFORM_ALL

const TRANSFORM_ALL: number;

POSITION | ROTATION | SCALE, what a freshly spawned entity needs.

---

TRANSFORM_FLAGS

const TRANSFORM_FLAGS: Readonly<{
  DESTROYED: 32;
  POSITION: 1;
  ROTATION: 2;
  SCALE: 4;
  TELEPORT: 16;
  VISIBLE: 8;
}>;

Meaning of lane 1 of a transform row, matching WIT transform-flags.

---

TRANSFORM_STRIDE

const TRANSFORM_STRIDE: 12 = 12;

Floats per row of frame-output.transforms.

---

Velocity

const Velocity: VelocityStore;

Guest-integrated velocity, for entities the host physics does not own.

Functions

activeRuntime()

function activeRuntime(): RuntimeState;

The runtime the SDK facades are currently bound to.

Returns

RuntimeState

The active runtime.

Throws

When called outside init, a system, update or shutdown.

---

assetId()

function assetId(name): number;

Resolve a manifest string id to an asset handle, caching the result.

Parameters

Parameter	Type	Description
name	string	The manifest string id, for example 'arena'.

Returns

number

The handle, or 0 when the manifest has no such entry.

Example

import { assetId } from '@aosengine/sdk';

const arena = assetId('arena');

---

commandPoolSize()

function commandPoolSize(): number;

Total pooled command slots created since the module loaded.

Tests assert this stops growing once a game reaches its steady state.

Returns

number

The number of slots ever allocated.

Example

const before = commandPoolSize();
for (let i = 0; i < 100; i += 1) guest.tick(input);
console.log(commandPoolSize() === before); // true, in a steady state

---

configureEcs()

function configureEcs(n): void;

Resize every built-in component array.

Call this before defineGame runs any system — the runtime calls it from init out of world.maxEntities. The component objects keep their identity, so bitecs registrations survive; only the arrays inside are replaced, so never cache Transform.x across a call.

Parameters

Parameter	Type	Description
n	number	The new entity ceiling. Values below 2 are clamped to 2.

Returns

void

Nothing.

---

createGuest()

function createGuest(host, definition): Guest;

Create a guest from a host and a game definition.

Parameters

Parameter	Type	Description
host	HostApi	The host services, in guest-side JS shapes.
definition	GameDefinition	The result of defineGame.

Returns

Guest

The five WIT exports, plus dead and state.

Example

import { createGuest } from '@aosengine/sdk';
import { createMockHost, createFrameInput } from '@aosengine/test-harness';

const guest = createGuest(createMockHost(), game);
guest.init({ seed: 1, fixedHz: 60, viewportWidth: 1, viewportHeight: 1, devMode: true });
const out = guest.tick(createFrameInput({ frame: 0 }));

---

createRng()

function createRng(initialSeed?): Rng;

Create a seeded xoshiro128** generator.

Parameters

Parameter	Type	Default value	Description
initialSeed	number	1	A 32-bit seed. 0 is remapped so the state is never all zero.

Returns

Rng

A generator whose whole state is four integers.

---

createThirdPersonController()

function createThirdPersonController(clips?): object;

Create one allocation-free camera-relative controller per player. Call reset in game init; update from a guest system. Tuning comes from ctx.rules: walkSpeed, runSpeed, acceleration, deceleration, jumpSpeed, landingSeconds, moveTurnRate, idleTurnRate, idleTurnThreshold and camera pitch/distance/height.

Parameters

Parameter	Type	Description
clips?	ThirdPersonClips	Optional complete base-layer clip mapping, configured once.

Returns

object

Persistent state, reset and update functions.

reset

reset: (ctx) => void = resetLocomotion;

Parameters

Parameter	Type
ctx	GameContext

Returns

void

state

state: object = locomotionState;

state.airborne

airborne: number = 0;

state.descending

descending: boolean = false;

state.facing

facing: number = Math.PI;

state.grounded

grounded: boolean = false;

state.landing

landing: number = 0;

state.pitch

pitch: number = 0;

state.speed

speed: number = 0;

state.state

state: string = IDLE;

state.turning

turning: boolean = false;

state.vx

vx: number = 0;

state.vz

vz: number = 0;

state.yaw

yaw: number = 0;

update

update: (ctx, freeze) => void = locomotionSystem;

Parameters

Parameter	Type	Default value
ctx	GameContext	undefined
freeze	boolean	false

Returns

void

Example

const controller = createThirdPersonController();
// In init: controller.reset(ctx); in a system: controller.update(ctx);

---

defineGame()

function defineGame(spec): GameDefinition;

Declare a game.

Parameters

Parameter	Type	Description
spec	GameSpec	The declaration.

Returns

GameDefinition

The frozen definition, ready for createGuest or a build.

Example

import { defineGame, prefab } from '@aosengine/sdk';

const Player = prefab({
  body: { shape: 'capsule', dims: [0.3, 0.9], kind: 'character' },
});

export default defineGame({
  assets: ['arena'],
  world: { gravity: -9.81 },
  player: { prefab: Player, spawn: [0, 1, 0], camera: 'firstPerson' },
  systems: [(ctx) => { ctx.hud.set({ frame: ctx.frame }); }],
});

---

describeAsset()

function describeAsset(idOrName): AssetDesc | null;

Metadata for an asset handle or manifest name.

Parameters

Parameter	Type	Description
idOrName	string | number	A handle from assetId, or a manifest string id.

Returns

AssetDesc | null

The description, or null when the asset is unknown.

Example

import { describeAsset } from '@aosengine/sdk';

const desc = describeAsset('myra');
if (desc?.kind === 'character') console.log('rig backend', desc.rig);

---

despawn()

function despawn(entity): void;

Destroy an entity, its body and its host-side representation.

Parameters

Parameter	Type	Description
entity	number	The entity id.

Returns

void

Nothing.

Example

import { despawn } from '@aosengine/sdk';

despawn(enemy);

---

getActiveRuntime()

function getActiveRuntime(): RuntimeState | null;

The runtime currently executing, or null outside a guest call.

Returns

RuntimeState | null

The active runtime.

---

getMaxEntities()

function getMaxEntities(): number;

How many entities the built-in component arrays currently hold.

Returns

number

The configured entity ceiling.

---

keyIndex()

function keyIndex(name): number;

Bit index for a key name, or -1 when the name is unknown.

Parameters

Parameter	Type	Description
name	string	A DOM KeyboardEvent.code, a bare letter/digit, or an alias.

Returns

number

The bit index in 0..255, or -1.

---

keyIndex2()

function keyIndex2(name): number;

Second bit index for names that cover a left/right pair ('Shift'), or -1.

Parameters

Parameter	Type	Description
name	string	A key name or alias.

Returns

number

The second bit index, or -1 when the name maps to one key.

---

loadAsset()

function loadAsset(idOrName, priority?): void;

Ask the host to start loading an asset.

Parameters

Parameter	Type	Default value	Description
idOrName	string | number	undefined	A handle or manifest string id.
priority	number	0	Higher runs first. Default 0.

Returns

void

Nothing.

Example

import { loadAsset } from '@aosengine/sdk';

loadAsset('boss-arena', 10);

---

markMoved()

function markMoved(entity, flags?): void;

Tell the packer an entity's Transform changed.

spawn and the built-in velocity integration mark for you. Two cases they do not cover: a system that writes Transform.x[e] (or any other lane) by hand, and a body-driven entity, whose transform the host now owns outright — BodyIndex.ingest copies the physics rows in for the guest to read and deliberately does not mark them. Either way, nothing notices the write, the row is never packed and the host never moves the object. Call this after such a write. To move a physics body, send a command (setBodyTransform) rather than writing the lane.

Parameters

Parameter	Type	Default value	Description
entity	number	undefined	Entity id. Out-of-range ids are ignored.
flags	number	TRANSFORM_ALL	Which lanes changed; defaults to position, rotation and scale.

Returns

void

Nothing.

Example

import { Transform, TRANSFORM_FLAGS, markMoved } from '@aosengine/sdk';

Transform.y[e] = Transform.y[e] + 0.1;
markMoved(e, TRANSFORM_FLAGS.POSITION);

---

maxEntities()

function maxEntities(): number;

The entity ceiling the built-in components are currently sized for.

Returns

number

The configured maximum.

Example

import { maxEntities } from '@aosengine/sdk';

console.log(maxEntities()); // 4096

---

prefab()

function prefab(spec): PrefabDef;

Declare a prefab.

Safe at module scope: nothing is resolved until the first spawn.

Parameters

Parameter	Type	Description
spec	PrefabSpec	What the entity is made of.

Returns

PrefabDef

The prefab, ready to spawn.

Example

import { prefab } from '@aosengine/sdk';

export const Crate = prefab({
  asset: 'crate',
  body: { shape: 'box', dims: [0.5, 0.5, 0.5], kind: 'dynamic', mass: 20 },
});

---

prefabRegistry()

function prefabRegistry(): readonly PrefabDef[];

Every prefab declared so far, in declaration order.

Returns

readonly PrefabDef[]

The registry, for tooling and tests.

---

quatFromYawPitch()

function quatFromYawPitch(
   out, 
   yaw, 
   pitch
): void;

Write a yaw/pitch pair into a quaternion, in the engine's Y-up convention.

Parameters

Parameter	Type	Description
out	Quat	Quaternion to overwrite.
yaw	number	Yaw in radians, around +Y.
pitch	number	Pitch in radians, around the camera's local +X.

Returns

void

Nothing; out is mutated.

---

readKeyBit()

function readKeyBit(words, index): boolean;

Read one bit out of an 8-word key bitset.

Parameters

Parameter	Type	Description
words	ArrayLike<number>	The bitset, exactly KEY_WORDS long.
index	number	A bit index from keyIndex.

Returns

boolean

True when the bit is set.

---

readSnapshot()

function readSnapshot(rt, state): unknown;

Restore a state previously produced by writeSnapshot from the same build.

Parameters

Parameter	Type	Description
rt	RuntimeState	The runtime to overwrite.
state	ArrayLike<number>	The bytes.

Returns

unknown

The user state from defineGame({ snapshot }), if any.

Throws

A GameError-shaped object when the magic or version does not match.

---

requireRuntime()

function requireRuntime(): RuntimeState;

The runtime currently executing.

Returns

RuntimeState

The active runtime.

Throws

When called outside init, tick or shutdown.

---

resetBuiltinStores()

function resetBuiltinStores(): void;

Zero every built-in component array without changing its length.

Returns

void

Nothing.

---

resetPrefabRegistry()

function resetPrefabRegistry(): void;

Reset prefab numbering. Tests only — a game never calls this.

Returns

void

Nothing.

---

setActiveRuntime()

function setActiveRuntime(next): RuntimeState | null;

Install the runtime the facades resolve against.

Parameters

Parameter	Type	Description
next	RuntimeState | null	The runtime, or null when leaving a guest call.

Returns

RuntimeState | null

The previously active runtime, so calls can nest.

---

setLogSink()

function setLogSink(next): void;

Point prelude console at the host logger.

The runtime calls this at the top of init. Any lines buffered before then are flushed in order, so module-scope logging is not silently lost.

Parameters

Parameter	Type	Description
next	LogSink | null	The sink, or null to go back to buffering.

Returns

void

Nothing.

---

setRandomSource()

function setRandomSource(next): void;

Route Math.random at the seeded SDK generator.

The runtime calls this from init. Until then Math.random() throws with RANDOM_MESSAGE, which is far kinder than a game that silently replays the same "random" sequence on every instantiation.

Only effective in the component guest; see IS_COMPONENT_GUEST.

Parameters

Parameter	Type	Description
next	(() => number) | null	The seeded generator, or null to re-arm the guard.

Returns

void

Nothing.

---

spawn()

function spawn(
   def, 
   position, 
   rotation?
): number;

Instantiate a prefab.

Mints the entity id, writes the built-in components and queues the spawn / add-body / spawn-character commands the host needs.

Parameters

Parameter	Type	Default value	Description
def	PrefabDef	undefined	A prefab from prefab().
position	Vec3	undefined	World position.
rotation	Quat	IDENTITY	World rotation, xyzw. Defaults to identity.

Returns

number

The new entity id.

Example

import { spawn } from '@aosengine/sdk';

const crate = spawn(Crate, { x: 0, y: 2, z: -5 });

---

utf8Decode()

function utf8Decode(
   b, 
   start?, 
   end?
): string;

Decode UTF-8 bytes without TextDecoder.

Parameters

Parameter	Type	Default value	Description
b	ArrayLike<number>	undefined	The bytes. Any ArrayLike<number> works, including the plain Array jco hands the guest.
start	number	0	First byte to read.
end?	number	undefined	One past the last byte to read; defaults to b.length.

Returns

string

The decoded string.

---

utf8Encode()

function utf8Encode(s): Uint8Array;

Encode a JavaScript string as UTF-8 without TextEncoder.

Parameters

Parameter	Type	Description
s	string	The string to encode.

Returns

Uint8Array

A freshly allocated UTF-8 byte array.

---

writeKeyBit()

function writeKeyBit(
   words, 
   index, 
   value
): void;

Set or clear one bit in an 8-word key bitset, in place.

Parameters

Parameter	Type	Description
words	Uint32Array	The bitset, exactly KEY_WORDS long.
index	number	A bit index from keyIndex.
value	boolean	True to set the bit, false to clear it.

Returns

void

Nothing; words is mutated.

---

writeSnapshot()

function writeSnapshot(rt, userState?): Uint8Array;

Serialise the whole guest state.

Parameters

Parameter	Type	Description
rt	RuntimeState	The runtime to serialise.
userState?	unknown	Extra state from defineGame({ snapshot }).

Returns

Uint8Array

A freshly allocated byte string. Opaque to the host.