Skip to content

@aosengine/wasm-host

Interfaces

AdapterCall

One recorded EngineAdapter call.

Properties

args
ts
args: readonly unknown[];

Arguments, by reference — they may be pooled and reused by the guest.

method
ts
method: keyof EngineAdapter;

Method name.


DirectSandboxOptions

Run the game's TypeScript directly, in the host realm.

Properties

game
ts
game: GameDefinition;

The game's defineGame result.

host
ts
host: HostApi;

Host services the guest imports.

mode
ts
mode: "direct";

DomHudOptions

Options accepted by createDomHud.

Properties

className?
ts
optional className?: string;

Class name given to the root element. Defaults to aos-hud.

container?
ts
optional container?: HudElement;

Where the overlay is appended. Defaults to document.body.

document?
ts
optional document?: HudDocument;

Document used to create elements. Defaults to the global document.


EncodeArgs

Everything an encoder needs for one fixed step.

Properties

bodies
ts
bodies: Float32Array;

Packed body rows, stride 14, sorted ascending by body id.

bodyCount
ts
bodyCount: number;

Live body count; bodies may be longer.

contacts?
ts
optional contacts?: readonly Contact[];

Reported contacts.

dt
ts
dt: number;

Fixed timestep in seconds.

elapsed
ts
elapsed: number;

Simulated seconds since init.

events?
ts
optional events?: readonly GameEvent[];

Host-side events since the previous tick.

frame
ts
frame: number;

Fixed-step counter.

inputState
ts
inputState: InputSnapshot;

Host input state.


EngineAdapter

Everything the host can be asked to do, one method per command.

Extended by

Methods

addBody()
ts
addBody(args): void;

Create a rigid body or character controller.

Parameters
ParameterType
argsAddBodyCmd
Returns

void

applyImpulse()
ts
applyImpulse(
   body, 
   impulse, 
   atPoint
): void;

Apply a one-shot impulse.

Parameters
ParameterType
bodynumber
impulseVec3
atPointVec3 | undefined
Returns

void

applyTransforms()
ts
applyTransforms(transforms, count): void;

Apply packed entity transforms.

Parameters
ParameterTypeDescription
transformsFloat32ArrayStride 12: entity, flags, position, rotation, scale.
countnumberNumber of rows. The buffer may be longer.
Returns

void

despawn()
ts
despawn(entity): void;

Destroy an entity and everything attached to it.

Parameters
ParameterType
entitynumber
Returns

void

loadAsset()
ts
loadAsset(asset, priority): void;

Start loading an asset.

Parameters
ParameterType
assetnumber
prioritynumber
Returns

void

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

Aim a character's head and eyes.

Parameters
ParameterType
entitynumber
targetVec3 | undefined
weightnumber
Returns

void

moveCharacter()
ts
moveCharacter(
   body, 
   desiredVelocity, 
   jump, 
   crouch, 
   maxSlopeDeg
): void;

Drive a character body for one step.

Parameters
ParameterType
bodynumber
desiredVelocityVec3
jumpboolean
crouchboolean
maxSlopeDegnumber
Returns

void

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

Start a sound.

Parameters
ParameterType
soundnumber
assetnumber
entitynumber | undefined
positionVec3 | undefined
volumenumber
pitchnumber
loopingboolean
busAudioBus
Returns

void

removeBody()
ts
removeBody(body): void;

Destroy a body.

Parameters
ParameterType
bodynumber
Returns

void

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

Speak a line.

Parameters
ParameterType
entitynumber
textstring
audionumber | undefined
visemesstring | undefined
Returns

void

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

Play or cross-fade an animation clip.

Parameters
ParameterType
entitynumber
clipstring
loopingboolean
speednumber
fadeMsnumber
weightnumber
Returns

void

setAsset()
ts
setAsset(entity, asset): void;

Attach or detach a renderable.

Parameters
ParameterType
entitynumber
assetnumber | undefined
Returns

void

setBodyEnabled()
ts
setBodyEnabled(body, enabled): void;

Enable or disable a body in the broad phase.

Parameters
ParameterType
bodynumber
enabledboolean
Returns

void

setBodyTransform()
ts
setBodyTransform(
   body, 
   position, 
   rotation, 
   teleport
): void;

Move a body directly.

Parameters
ParameterType
bodynumber
positionVec3
rotationQuat
teleportboolean
Returns

void

setBodyVelocity()
ts
setBodyVelocity(
   body, 
   linear, 
   angular
): void;

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

Parameters
ParameterType
bodynumber
linearVec3 | undefined
angularVec3 | undefined
Returns

void

setCamera()
ts
setCamera(camera): void;

Apply the camera the guest asked for.

Parameters
ParameterType
cameraCameraState
Returns

void

setCharacterState()
ts
setCharacterState(
   entity, 
   state, 
   velocity, 
   grounded
): void;

Drive a character's locomotion state machine.

Parameters
ParameterType
entitynumber
statestring
velocityVec3
groundedboolean
Returns

void

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

Set explicit per-clip weights.

Parameters
ParameterType
entitynumber
clipsreadonly string[]
weightsArrayLike<number>
timeScalenumber
Returns

void

setExpression()
ts
setExpression(
   entity, 
   space, 
   weights
): void;

Set facial expression coefficients.

Parameters
ParameterType
entitynumber
spaceExpressionSpace
weightsArrayLike<number>
Returns

void

setHud()
ts
setHud(json): void;

Apply the HUD model, or leave the previous one when undefined.

Parameters
ParameterType
jsonstring | undefined
Returns

void

setListener()
ts
setListener(
   position, 
   rotation, 
   velocity
): void;

Place the audio listener.

Parameters
ParameterType
positionVec3
rotationQuat
velocityVec3
Returns

void

setMaterialParam()
ts
setMaterialParam(
   entity, 
   name, 
   value
): void;

Set one material uniform.

Parameters
ParameterType
entitynumber
namestring
valueMaterialValue
Returns

void

setParent()
ts
setParent(
   entity, 
   parent, 
   keepWorldTransform
): void;

Reparent an entity.

Parameters
ParameterType
entitynumber
parentnumber | undefined
keepWorldTransformboolean
Returns

void

setPointerLock()
ts
setPointerLock(locked): void;

Request or release pointer lock.

Parameters
ParameterType
lockedboolean
Returns

void

setTimeScale()
ts
setTimeScale(scale): void;

Scale simulated time.

Parameters
ParameterType
scalenumber
Returns

void

spawn()
ts
spawn(
   entity, 
   asset, 
   position, 
   rotation, 
   scale, 
   flags
): void;

Create an entity in the scene.

Parameters
ParameterType
entitynumber
assetnumber | undefined
positionVec3
rotationQuat
scaleVec3
flags{ name?: string; parent?: number; visible: boolean; }
flags.name?string
flags.parent?number
flags.visibleboolean
Returns

void

spawnCharacter()
ts
spawnCharacter(
   entity, 
   bundle, 
   position, 
   rotation
): void;

Instantiate a splat character bundle.

Parameters
ParameterType
entitynumber
bundlenumber
positionVec3
rotationQuat
Returns

void

stopSound()
ts
stopSound(sound, fadeMs): void;

Stop a playing sound.

Parameters
ParameterType
soundnumber
fadeMsnumber
Returns

void


EngineAdapterHandle

The engine-backed adapter, plus the hooks the host loop drives.

Extends

Properties

events
ts
readonly events: GameEvent[];

Host-side occurrences since the loop last drained them.

hud
ts
readonly hud: HudRenderer | null;

The HUD renderer, or null when hud: false.

hudModel
ts
readonly hudModel: unknown;

The HUD model currently on screen, whether or not a renderer is attached.

transforms
ts
readonly transforms: TransformStore;

Previous/current transforms, slot 0 being the camera.

Methods

addBody()
ts
addBody(args): void;

Create a rigid body or character controller.

Parameters
ParameterType
argsAddBodyCmd
Returns

void

Inherited from

EngineAdapter.addBody

animationOf()
ts
animationOf(entity): CharacterAnimationState | null;

What the guest last asked an entity's animation to do.

Parameters
ParameterTypeDescription
entitynumberThe entity.
Returns

CharacterAnimationState | null

The recorded intent, or null when the entity has never been the subject of a spawn-character, set-anim or set-character-state.

applyImpulse()
ts
applyImpulse(
   body, 
   impulse, 
   atPoint
): void;

Apply a one-shot impulse.

Parameters
ParameterType
bodynumber
impulseVec3
atPointVec3 | undefined
Returns

void

Inherited from

EngineAdapter.applyImpulse

applyTransforms()
ts
applyTransforms(transforms, count): void;

Apply packed entity transforms.

Parameters
ParameterTypeDescription
transformsFloat32ArrayStride 12: entity, flags, position, rotation, scale.
countnumberNumber of rows. The buffer may be longer.
Returns

void

Inherited from

EngineAdapter.applyTransforms

beginFixedStep()
ts
beginFixedStep(): void;

Roll current transforms into previous ones.

Call once per fixed step, before applying that step's output.

Returns

void

Nothing.

despawn()
ts
despawn(entity): void;

Destroy an entity and everything attached to it.

Parameters
ParameterType
entitynumber
Returns

void

Inherited from

EngineAdapter.despawn

dispose()
ts
dispose(): void;

Release the HUD and every object this adapter put in the scene.

Returns

void

entityOfBody()
ts
entityOfBody(body): number;

The entity a body id drives.

Parameters
ParameterTypeDescription
bodynumberBody id minted by the guest.
Returns

number

The entity, or 0 when the body is unknown.

interpolate()
ts
interpolate(alpha): void;

Write the blend of the previous and current transforms onto the scene.

Parameters
ParameterTypeDescription
alphanumberInterpolation factor in [0, 1), from the engine loop.
Returns

void

Nothing.

loadAsset()
ts
loadAsset(asset, priority): void;

Start loading an asset.

Parameters
ParameterType
assetnumber
prioritynumber
Returns

void

Inherited from

EngineAdapter.loadAsset

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

Aim a character's head and eyes.

Parameters
ParameterType
entitynumber
targetVec3 | undefined
weightnumber
Returns

void

Inherited from

EngineAdapter.lookAt

moveCharacter()
ts
moveCharacter(
   body, 
   desiredVelocity, 
   jump, 
   crouch, 
   maxSlopeDeg
): void;

Drive a character body for one step.

Parameters
ParameterType
bodynumber
desiredVelocityVec3
jumpboolean
crouchboolean
maxSlopeDegnumber
Returns

void

Inherited from

EngineAdapter.moveCharacter

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

Start a sound.

Parameters
ParameterType
soundnumber
assetnumber
entitynumber | undefined
positionVec3 | undefined
volumenumber
pitchnumber
loopingboolean
busAudioBus
Returns

void

Inherited from

EngineAdapter.playSound

removeBody()
ts
removeBody(body): void;

Destroy a body.

Parameters
ParameterType
bodynumber
Returns

void

Inherited from

EngineAdapter.removeBody

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

Speak a line.

Parameters
ParameterType
entitynumber
textstring
audionumber | undefined
visemesstring | undefined
Returns

void

Inherited from

EngineAdapter.say

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

Play or cross-fade an animation clip.

Parameters
ParameterType
entitynumber
clipstring
loopingboolean
speednumber
fadeMsnumber
weightnumber
Returns

void

Inherited from

EngineAdapter.setAnim

setAsset()
ts
setAsset(entity, asset): void;

Attach or detach a renderable.

Parameters
ParameterType
entitynumber
assetnumber | undefined
Returns

void

Inherited from

EngineAdapter.setAsset

setBodyEnabled()
ts
setBodyEnabled(body, enabled): void;

Enable or disable a body in the broad phase.

Parameters
ParameterType
bodynumber
enabledboolean
Returns

void

Inherited from

EngineAdapter.setBodyEnabled

setBodyTransform()
ts
setBodyTransform(
   body, 
   position, 
   rotation, 
   teleport
): void;

Move a body directly.

Parameters
ParameterType
bodynumber
positionVec3
rotationQuat
teleportboolean
Returns

void

Inherited from

EngineAdapter.setBodyTransform

setBodyVelocity()
ts
setBodyVelocity(
   body, 
   linear, 
   angular
): void;

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

Parameters
ParameterType
bodynumber
linearVec3 | undefined
angularVec3 | undefined
Returns

void

Inherited from

EngineAdapter.setBodyVelocity

setCamera()
ts
setCamera(camera): void;

Apply the camera the guest asked for.

Parameters
ParameterType
cameraCameraState
Returns

void

Inherited from

EngineAdapter.setCamera

setCharacterState()
ts
setCharacterState(
   entity, 
   state, 
   velocity, 
   grounded
): void;

Drive a character's locomotion state machine.

Parameters
ParameterType
entitynumber
statestring
velocityVec3
groundedboolean
Returns

void

Inherited from

EngineAdapter.setCharacterState

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

Set explicit per-clip weights.

Parameters
ParameterType
entitynumber
clipsreadonly string[]
weightsArrayLike<number>
timeScalenumber
Returns

void

Inherited from

EngineAdapter.setClipWeights

setExpression()
ts
setExpression(
   entity, 
   space, 
   weights
): void;

Set facial expression coefficients.

Parameters
ParameterType
entitynumber
spaceExpressionSpace
weightsArrayLike<number>
Returns

void

Inherited from

EngineAdapter.setExpression

setHud()
ts
setHud(json): void;

Apply the HUD model, or leave the previous one when undefined.

Parameters
ParameterType
jsonstring | undefined
Returns

void

Inherited from

EngineAdapter.setHud

setListener()
ts
setListener(
   position, 
   rotation, 
   velocity
): void;

Place the audio listener.

Parameters
ParameterType
positionVec3
rotationQuat
velocityVec3
Returns

void

Inherited from

EngineAdapter.setListener

setMaterialParam()
ts
setMaterialParam(
   entity, 
   name, 
   value
): void;

Set one material uniform.

Parameters
ParameterType
entitynumber
namestring
valueMaterialValue
Returns

void

Inherited from

EngineAdapter.setMaterialParam

setParent()
ts
setParent(
   entity, 
   parent, 
   keepWorldTransform
): void;

Reparent an entity.

Parameters
ParameterType
entitynumber
parentnumber | undefined
keepWorldTransformboolean
Returns

void

Inherited from

EngineAdapter.setParent

setPointerLock()
ts
setPointerLock(locked): void;

Request or release pointer lock.

Parameters
ParameterType
lockedboolean
Returns

void

Inherited from

EngineAdapter.setPointerLock

setTimeScale()
ts
setTimeScale(scale): void;

Scale simulated time.

Parameters
ParameterType
scalenumber
Returns

void

Inherited from

EngineAdapter.setTimeScale

spawn()
ts
spawn(
   entity, 
   asset, 
   position, 
   rotation, 
   scale, 
   flags
): void;

Create an entity in the scene.

Parameters
ParameterType
entitynumber
assetnumber | undefined
positionVec3
rotationQuat
scaleVec3
flags{ name?: string; parent?: number; visible: boolean; }
flags.name?string
flags.parent?number
flags.visibleboolean
Returns

void

Inherited from

EngineAdapter.spawn

spawnCharacter()
ts
spawnCharacter(
   entity, 
   bundle, 
   position, 
   rotation
): void;

Instantiate a splat character bundle.

Parameters
ParameterType
entitynumber
bundlenumber
positionVec3
rotationQuat
Returns

void

Inherited from

EngineAdapter.spawnCharacter

stopSound()
ts
stopSound(sound, fadeMs): void;

Stop a playing sound.

Parameters
ParameterType
soundnumber
fadeMsnumber
Returns

void

Inherited from

EngineAdapter.stopSound

update()
ts
update(dt, alpha): void;

One rendered frame's worth of adapter work: interpolate, then the character bridge's animators and rigs.

The two are separate because interpolation is pure transform maths and characters are not: a rig runs a compute pass and wants wall-clock seconds, not an interpolation factor.

Parameters
ParameterTypeDescription
dtnumberClamped wall-clock seconds since the previous frame.
alphanumberInterpolation factor in [0, 1), from the engine loop.
Returns

void

Nothing.


EngineAdapterOptions

Options accepted by createEngineAdapter.

Properties

capacity?
ts
optional capacity?: number;

Entity slots reserved up front. Defaults to 512.

characters?
ts
optional characters?: CharacterBridge;

Renders the spawn-character family for real.

Build one with createCharacterBridge from @aosengine/wasm-host/characters — the optional module, so a game with no characters never downloads the rig stack. Leave it out and the six character commands are recorded on EngineAdapterHandle.animationOf and warn once, which is what shipped before this existed.

hud?
ts
optional hud?: false | HudRenderer;

HUD renderer. Defaults to createDomHud over document.body; pass your own to restyle it, or false to render no HUD at all and read adapter.hudModel yourself.

hudContainer?
ts
optional hudContainer?: HudElement;

Container for the default HUD. Defaults to document.body.

modules?
ts
optional modules?: readonly EngineModule[];

The module instances handed to createEngine.

Services are normally reached through engine.get(id), but two things are only on the module object: the audio module's decodeAsset, which turns a play-sound asset handle into an AudioBuffer. Pass the same array you passed to createEngine and it is found automatically.

placeholders?
ts
optional placeholders?: "bodies" | "always" | "never";

When to draw a placeholder mesh in place of a real asset.

  • bodies (the default) — an entity with no renderable gets a mesh the shape and size of its physics body, and a spawn whose asset is unknown or not yet resident gets a unit box until the bytes arrive.
  • always — additionally, an entity with neither an asset nor a body gets a unit box. The right choice for a sketch, where nothing has an asset yet and an empty scene is indistinguishable from a broken one.
  • never — draw only what the manifest provides. The right choice once the game has real content, because then a missing mesh is a bug and should look like one.
warn?
ts
optional warn?: (message) => void;

Where warnings go. Defaults to console.warn, once per distinct message.

Parameters
ParameterTypeDescription
messagestringWhat went wrong.
Returns

void


EngineHostOptions

Options accepted by createEngineHost.

Properties

log?
ts
optional log?: (level, message) => void;

Where guest console.log goes. Defaults to the browser console.

Parameters
ParameterType
levelstring
messagestring
Returns

void

maxOverlaps?
ts
optional maxOverlaps?: number;

Most hits an overlap-sphere may return in one call. Defaults to 64.

seed?
ts
optional seed?: number;

Deterministic run seed. Defaults to 0x5eed1234.


GameSlot

A registered place in the module order, filled in once the engine exists.

Properties

module
ts
readonly module: EngineModule;

Register this with createEngine({ modules }).

Methods

attach()
ts
attach(loop, ctx): Promise<void>;

Bind the real loop and initialise it.

Parameters
ParameterTypeDescription
loopEngineModuleThe module from createHostLoop.
ctxEngineContextThe engine context, normally engine.ctx.
Returns

Promise<void>

Resolves once the loop's own init has run.


GuestNamespace

The game namespace the component exports.

Methods

init()
ts
init(config): void;
Parameters
ParameterType
configHostGameConfig
Returns

void

restore()
ts
restore(state): void;
Parameters
ParameterType
stateUint8Array
Returns

void

shutdown()
ts
shutdown(): void;
Returns

void

snapshot()
ts
snapshot(): Uint8Array;
Returns

Uint8Array

tick()
ts
tick(input): FrameOutput;
Parameters
ParameterType
inputHostFrameInput
Returns

FrameOutput


HostBindings

The aos:engine half of a jco import object.

Properties

aos:engine/assets
ts
aos:engine/assets: object;
describe
ts
describe: (id) => AssetDesc | undefined;
Parameters
ParameterType
idnumber
Returns

AssetDesc | undefined

resolveId
ts
resolveId: (name) => number | undefined;
Parameters
ParameterType
namestring
Returns

number | undefined

aos:engine/env
ts
aos:engine/env: object;
log
ts
log: (level, msg) => void;
Parameters
ParameterType
levelstring
msgstring
Returns

void

nowMs
ts
nowMs: () => number;
Returns

number

seed
ts
seed: () => bigint;
Returns

bigint

aos:engine/physics-query
ts
aos:engine/physics-query: object;
overlapSphere
ts
overlapSphere: (center, radius, filter, maxResults) => OverlapHit[];
Parameters
ParameterType
centerVec3
radiusnumber
filterQueryFilter
maxResultsnumber
Returns

OverlapHit[]

raycast
ts
raycast: (origin, direction, maxDistance, filter) => RayHit | undefined;
Parameters
ParameterType
originVec3
directionVec3
maxDistancenumber
filterQueryFilter
Returns

RayHit | undefined

raycastBatch
ts
raycastBatch: (rays) => (RayHit | undefined)[];
Parameters
ParameterType
raysRayQuery[]
Returns

(RayHit | undefined)[]


HostLoopOptions

Options accepted by createHostLoop.

Properties

devMode?
ts
optional devMode?: boolean;

Value of game-config.dev-mode. Defaults to true.

init?
ts
optional init?: boolean;

Call sandbox.init during module init. Defaults to true.

maxBodies?
ts
optional maxBodies?: number;

Body rows the input encoder reserves. Defaults to 1024.

onDead?
ts
optional onDead?: (error) => void;

Shown when the guest dies. Defaults to a red overlay on document.body.

Parameters
ParameterTypeDescription
errorError | nullWhy the sandbox died.
Returns

void

options?
ts
optional options?: string;

Extra options string handed to game.init.

order?
ts
optional order?: number;

Module order. Defaults to 100: after physics, before the render helpers.

seed?
ts
optional seed?: number | bigint;

Deterministic run seed handed to game.init. Defaults to 0x5eed1234.

Fix it and a run replays; vary it and each run differs.


HudDocument

The slice of Document the renderer uses.

Methods

createElement()
ts
createElement(tag): HudElement;

Create an element.

Parameters
ParameterTypeDescription
tagstringTag name, always 'div' here.
Returns

HudElement

The new element.


HudElement

The slice of HTMLElement the renderer uses.

Properties

className
ts
className: string;

Class name, set once per element at creation.

style
ts
readonly style: object;

Inline style, written through setProperty so a fake needs one method.

setProperty()
ts
setProperty(name, value): void;
Parameters
ParameterType
namestring
valuestring
Returns

void

textContent
ts
textContent: string | null;

Text content; the renderer only ever writes it.

Methods

append()
ts
append(...nodes): void;

Append children.

The parameter is unknown rather than HudElement on purpose: the real HTMLElement.append takes (string | Node)[], and only a parameter type that a Node is assignable to makes a real element satisfy this interface under method bivariance.

Parameters
ParameterTypeDescription
...nodesunknown[]Children to append; always HudElements here.
Returns

void

remove()
ts
remove(): void;

Detach from the parent, if any.

Returns

void


HudModel

The HUD model the default renderer understands.

Properties

bars?
ts
optional bars?: Record<string, {
  max: number;
  value: number;
}>;

Label to { value, max } meters, drawn bottom-left in declaration order.

crosshair?
ts
optional crosshair?: boolean;

Draw the centre crosshair.

message?
ts
optional message?: string;

A single centred line, for "You win" and friends. Empty or absent hides it.

text?
ts
optional text?: Record<string, string | number>;

Label to value rows, drawn top-left in declaration order.


HudRenderer

What createDomHud returns, and what the adapter drives.

Properties

element
ts
readonly element: HudElement;

The overlay root, for tests and for callers that want to restyle it.

model
ts
readonly model: HudModel | null;

The model currently on screen, or null before the first payload.

Methods

clear()
ts
clear(): void;

Hide everything and forget the model.

Returns

void

dispose()
ts
dispose(): void;

Detach the overlay from its container.

Returns

void

set()
ts
set(json): boolean;

Apply one frame-output.hud value.

Parameters
ParameterTypeDescription
jsonstring | undefinedThe JSON the guest sent, or undefined when nothing changed.
Returns

boolean

True when the DOM was touched.


InputEncoder

A reusable frame-input builder.

Methods

encode()
ts
encode(args): HostFrameInput;

Build the next frame input. The returned object is reused.

Parameters
ParameterType
argsEncodeArgs
Returns

HostFrameInput


InputSnapshot

The shape the engine's input module hands over each frame.

Properties

down
ts
down: ArrayLike<number>;

Key bitsets, KEY_WORDS words each.

focused
ts
focused: boolean;
gamepads?
ts
optional gamepads?: readonly GamepadState[];
mods
ts
mods: InputMods;
mouse
ts
mouse: MouseState;
pressed
ts
pressed: ArrayLike<number>;
released
ts
released: ArrayLike<number>;

MinimalWasiOptions

Options for minimalWasi.

Properties

monotonicNs?
ts
optional monotonicNs?: () => bigint;

Monotonic nanoseconds. Default: performance.now().

Returns

bigint

stderr?
ts
optional stderr?: StderrSink;

Where the guest's stderr goes. Default: console.error.


NullAdapter

An adapter that records instead of rendering.

Extends

Properties

calls
ts
readonly calls: AdapterCall[];

Every call, in order.

lastTransformCount
ts
readonly lastTransformCount: number;

Rows handed to the most recent applyTransforms.

Methods

addBody()
ts
addBody(args): void;

Create a rigid body or character controller.

Parameters
ParameterType
argsAddBodyCmd
Returns

void

Inherited from

EngineAdapter.addBody

applyImpulse()
ts
applyImpulse(
   body, 
   impulse, 
   atPoint
): void;

Apply a one-shot impulse.

Parameters
ParameterType
bodynumber
impulseVec3
atPointVec3 | undefined
Returns

void

Inherited from

EngineAdapter.applyImpulse

applyTransforms()
ts
applyTransforms(transforms, count): void;

Apply packed entity transforms.

Parameters
ParameterTypeDescription
transformsFloat32ArrayStride 12: entity, flags, position, rotation, scale.
countnumberNumber of rows. The buffer may be longer.
Returns

void

Inherited from

EngineAdapter.applyTransforms

by()
ts
by(method): AdapterCall[];

Calls with a given method name.

Parameters
ParameterType
methodkeyof EngineAdapter
Returns

AdapterCall[]

despawn()
ts
despawn(entity): void;

Destroy an entity and everything attached to it.

Parameters
ParameterType
entitynumber
Returns

void

Inherited from

EngineAdapter.despawn

loadAsset()
ts
loadAsset(asset, priority): void;

Start loading an asset.

Parameters
ParameterType
assetnumber
prioritynumber
Returns

void

Inherited from

EngineAdapter.loadAsset

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

Aim a character's head and eyes.

Parameters
ParameterType
entitynumber
targetVec3 | undefined
weightnumber
Returns

void

Inherited from

EngineAdapter.lookAt

moveCharacter()
ts
moveCharacter(
   body, 
   desiredVelocity, 
   jump, 
   crouch, 
   maxSlopeDeg
): void;

Drive a character body for one step.

Parameters
ParameterType
bodynumber
desiredVelocityVec3
jumpboolean
crouchboolean
maxSlopeDegnumber
Returns

void

Inherited from

EngineAdapter.moveCharacter

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

Start a sound.

Parameters
ParameterType
soundnumber
assetnumber
entitynumber | undefined
positionVec3 | undefined
volumenumber
pitchnumber
loopingboolean
busAudioBus
Returns

void

Inherited from

EngineAdapter.playSound

removeBody()
ts
removeBody(body): void;

Destroy a body.

Parameters
ParameterType
bodynumber
Returns

void

Inherited from

EngineAdapter.removeBody

reset()
ts
reset(): void;

Forget every recorded call.

Returns

void

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

Speak a line.

Parameters
ParameterType
entitynumber
textstring
audionumber | undefined
visemesstring | undefined
Returns

void

Inherited from

EngineAdapter.say

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

Play or cross-fade an animation clip.

Parameters
ParameterType
entitynumber
clipstring
loopingboolean
speednumber
fadeMsnumber
weightnumber
Returns

void

Inherited from

EngineAdapter.setAnim

setAsset()
ts
setAsset(entity, asset): void;

Attach or detach a renderable.

Parameters
ParameterType
entitynumber
assetnumber | undefined
Returns

void

Inherited from

EngineAdapter.setAsset

setBodyEnabled()
ts
setBodyEnabled(body, enabled): void;

Enable or disable a body in the broad phase.

Parameters
ParameterType
bodynumber
enabledboolean
Returns

void

Inherited from

EngineAdapter.setBodyEnabled

setBodyTransform()
ts
setBodyTransform(
   body, 
   position, 
   rotation, 
   teleport
): void;

Move a body directly.

Parameters
ParameterType
bodynumber
positionVec3
rotationQuat
teleportboolean
Returns

void

Inherited from

EngineAdapter.setBodyTransform

setBodyVelocity()
ts
setBodyVelocity(
   body, 
   linear, 
   angular
): void;

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

Parameters
ParameterType
bodynumber
linearVec3 | undefined
angularVec3 | undefined
Returns

void

Inherited from

EngineAdapter.setBodyVelocity

setCamera()
ts
setCamera(camera): void;

Apply the camera the guest asked for.

Parameters
ParameterType
cameraCameraState
Returns

void

Inherited from

EngineAdapter.setCamera

setCharacterState()
ts
setCharacterState(
   entity, 
   state, 
   velocity, 
   grounded
): void;

Drive a character's locomotion state machine.

Parameters
ParameterType
entitynumber
statestring
velocityVec3
groundedboolean
Returns

void

Inherited from

EngineAdapter.setCharacterState

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

Set explicit per-clip weights.

Parameters
ParameterType
entitynumber
clipsreadonly string[]
weightsArrayLike<number>
timeScalenumber
Returns

void

Inherited from

EngineAdapter.setClipWeights

setExpression()
ts
setExpression(
   entity, 
   space, 
   weights
): void;

Set facial expression coefficients.

Parameters
ParameterType
entitynumber
spaceExpressionSpace
weightsArrayLike<number>
Returns

void

Inherited from

EngineAdapter.setExpression

setHud()
ts
setHud(json): void;

Apply the HUD model, or leave the previous one when undefined.

Parameters
ParameterType
jsonstring | undefined
Returns

void

Inherited from

EngineAdapter.setHud

setListener()
ts
setListener(
   position, 
   rotation, 
   velocity
): void;

Place the audio listener.

Parameters
ParameterType
positionVec3
rotationQuat
velocityVec3
Returns

void

Inherited from

EngineAdapter.setListener

setMaterialParam()
ts
setMaterialParam(
   entity, 
   name, 
   value
): void;

Set one material uniform.

Parameters
ParameterType
entitynumber
namestring
valueMaterialValue
Returns

void

Inherited from

EngineAdapter.setMaterialParam

setParent()
ts
setParent(
   entity, 
   parent, 
   keepWorldTransform
): void;

Reparent an entity.

Parameters
ParameterType
entitynumber
parentnumber | undefined
keepWorldTransformboolean
Returns

void

Inherited from

EngineAdapter.setParent

setPointerLock()
ts
setPointerLock(locked): void;

Request or release pointer lock.

Parameters
ParameterType
lockedboolean
Returns

void

Inherited from

EngineAdapter.setPointerLock

setTimeScale()
ts
setTimeScale(scale): void;

Scale simulated time.

Parameters
ParameterType
scalenumber
Returns

void

Inherited from

EngineAdapter.setTimeScale

spawn()
ts
spawn(
   entity, 
   asset, 
   position, 
   rotation, 
   scale, 
   flags
): void;

Create an entity in the scene.

Parameters
ParameterType
entitynumber
assetnumber | undefined
positionVec3
rotationQuat
scaleVec3
flags{ name?: string; parent?: number; visible: boolean; }
flags.name?string
flags.parent?number
flags.visibleboolean
Returns

void

Inherited from

EngineAdapter.spawn

spawnCharacter()
ts
spawnCharacter(
   entity, 
   bundle, 
   position, 
   rotation
): void;

Instantiate a splat character bundle.

Parameters
ParameterType
entitynumber
bundlenumber
positionVec3
rotationQuat
Returns

void

Inherited from

EngineAdapter.spawnCharacter

stopSound()
ts
stopSound(sound, fadeMs): void;

Stop a playing sound.

Parameters
ParameterType
soundnumber
fadeMsnumber
Returns

void

Inherited from

EngineAdapter.stopSound


Sandbox

One loaded game module.

Properties

dead
ts
readonly dead: boolean;

True once the guest has trapped or failed. A dead sandbox returns a safe empty frame forever; rebuild it.

error
ts
readonly error: Error | null;

Why the sandbox died, when it did.

mode
ts
readonly mode: "wasm" | "direct";

How this sandbox runs its guest.

Methods

init()
ts
init(config): void;

Call once, before the first tick.

Parameters
ParameterType
configHostGameConfig
Returns

void

restore()
ts
restore(state): void;

Restore a state produced by snapshot from the same build.

Parameters
ParameterType
stateUint8Array
Returns

void

shutdown()
ts
shutdown(): void;

Release guest-side resources. No further calls follow.

Returns

void

snapshot()
ts
snapshot(): Uint8Array;

Serialise the whole guest state.

Returns

Uint8Array

tick()
ts
tick(input): FrameOutput;

One fixed simulation step.

Parameters
ParameterType
inputHostFrameInput
Returns

FrameOutput


WasmSandboxOptions

Load a jco transpiled component.

Properties

getCoreModule
ts
getCoreModule: (path) => Promise<Module>;

Compile one of the nine core wasm files by its relative path.

Parameters
ParameterType
pathstring
Returns

Promise<Module>

guestModuleUrl?
ts
optional guestModuleUrl?: string | URL;

URL of the transpiled game.js. Ignored when instantiate is given. Dynamically imported, so bundlers see a runtime specifier.

host
ts
host: HostApi;

Host services the guest imports.

instantiate?
ts
optional instantiate?: Instantiate;

The transpiled module's instantiate, when it is already imported.

mode
ts
mode: "wasm";
wasi?
ts
optional wasi?: MinimalWasiOptions;

WASI stub overrides.

Type Aliases

Instantiate

ts
type Instantiate = (getCoreModule, imports, instantiateCore) => Promise<{
  game: GuestNamespace;
}>;

The instantiate a jco transpile --instantiation async module exports.

Parameters

ParameterType
getCoreModule(path) => Promise<WebAssembly.Module>
importsRecord<string, unknown>
instantiateCoretypeof WebAssembly.instantiate

Returns

Promise<{ game: GuestNamespace; }>


SandboxOptions

ts
type SandboxOptions = 
  | DirectSandboxOptions
  | WasmSandboxOptions;

Either kind of sandbox.


StderrSink

ts
type StderrSink = (bytes) => void;

Where stub stderr goes. Replaced by minimalWasi({ stderr }).

Parameters

ParameterType
bytesUint8Array

Returns

void

Variables

PACKAGE

ts
const PACKAGE: "@aosengine/wasm-host";

Package identity marker.

Example

ts
import { PACKAGE } from '@aosengine/wasm-host';

console.log(PACKAGE); // '@aosengine/wasm-host'

Functions

applyCommand()

ts
function applyCommand(adapter, command): void;

Dispatch one command to the adapter.

The switch is exhaustive over Command['tag']; adding a case to the WIT variant without adding one here is a compile error, which is exactly what should happen.

Parameters

ParameterTypeDescription
adapterEngineAdapterThe engine.
commandCommandThe command.

Returns

void

Nothing.

Example

ts
import { applyCommand } from '@aosengine/wasm-host';

for (const command of out.commands) applyCommand(adapter, command);

applyOutput()

ts
function applyOutput(adapter, out): void;

Apply a whole frame-output.

Parameters

ParameterTypeDescription
adapterEngineAdapterThe engine.
outFrameOutputThe guest's output for this frame.

Returns

void

Nothing.

Example

ts
import { applyOutput } from '@aosengine/wasm-host';

applyOutput(adapter, sandbox.tick(input));

createDirectSandbox()

ts
function createDirectSandbox(options): Sandbox;

Build a direct-mode sandbox, synchronously.

Parameters

ParameterTypeDescription
optionsDirectSandboxOptionsThe game definition and host services.

Returns

Sandbox

A sandbox running the SDK runtime in this realm.

Example

ts
import { createDirectSandbox } from '@aosengine/wasm-host';

const sandbox = createDirectSandbox({ mode: 'direct', game, host });

createDomHud()

ts
function createDomHud(options?): HudRenderer;

Create the default DOM HUD.

The renderer is deliberately dumb: it knows four keys and draws them the same way for every game. A game that wants its own look passes its own renderer to createEngineAdapter({ hud }), or turns this one off with { hud: false } and reads adapter.hudModel itself.

Parameters

ParameterTypeDescription
optionsDomHudOptionsContainer, document and root class name.

Returns

HudRenderer

A renderer, already attached to its container.

Example

ts
import { createDomHud } from '@aosengine/wasm-host';

const hud = createDomHud();
hud.set(JSON.stringify({ text: { ammo: 12 }, crosshair: true }));

createEngineAdapter()

ts
function createEngineAdapter(engine, options?): EngineAdapterHandle;

Build the adapter that applies frame-output to a booted engine.

Parameters

ParameterTypeDescription
engineEngineThe engine from createEngine.
optionsEngineAdapterOptionsModules, HUD and capacity.

Returns

EngineAdapterHandle

An adapter, plus the per-frame hooks createHostLoop drives.

Example

ts
import { createEngine } from '@aosengine/core';
import { createEngineAdapter } from '@aosengine/wasm-host';

const modules = [physics(), input(), audio(), splat()];
const engine = await createEngine({ canvas, manifest, modules });
const adapter = createEngineAdapter(engine, { modules });

createEngineHost()

ts
function createEngineHost(
   engine, 
   adapter, 
   options?
): HostApi;

Build the HostApi a browser sandbox imports.

These are the only synchronous calls the guest may make during tick: three physics queries and two init-time manifest lookups. Everything else the guest wants is a command, applied after it returns.

Parameters

ParameterTypeDescription
engineEngineThe booted engine.
adapterEngineAdapterHandleThe adapter, for the body-to-entity mapping queries report.
optionsEngineHostOptionsSeed, log sink and query capacity.

Returns

HostApi

A HostApi to hand to createSandbox.

Example

ts
import { createEngineAdapter, createEngineHost, createSandbox } from '@aosengine/wasm-host';

const adapter = createEngineAdapter(engine, { modules });
const host = createEngineHost(engine, adapter, { seed: 1 });
const sandbox = await createSandbox({ mode: 'direct', game, host });

createGameSlot()

ts
function createGameSlot(order?): GameSlot;

Reserve the game module's place in the module order.

createEngine wants its module list up front, and the game module wants the booted engine — the adapter needs engine.graph, the host bindings need engine.assets. Rather than make every application shell invent a way round that, the slot registers a module that does nothing until GameSlot.attach hands it the real one.

Parameters

ParameterTypeDefault valueDescription
ordernumber100Module order. Defaults to 100: after physics, before rendering helpers.

Returns

GameSlot

The slot.

Example

ts
import { createGameSlot, createHostLoop } from '@aosengine/wasm-host';

const slot = createGameSlot();
const engine = await createEngine({ canvas, manifest, modules: [...modules, slot.module] });
await slot.attach(createHostLoop(engine, sandbox, adapter), engine.ctx);

createHostLoop()

ts
function createHostLoop(
   engine, 
   sandbox, 
   adapter, 
   options?
): EngineModule;

The game module: one fixed step is one guest tick.

Registered at order 100, it runs after physics has stepped — so the bodies it reads are post-step — and before the rendering helpers. Its update hands the interpolation factor to the adapter, which is what makes a 60 Hz simulation look smooth on a 144 Hz display.

The first failure latches: a dead sandbox is not retried, because a trapped component instance stays poisoned. The overlay says so.

Parameters

ParameterTypeDescription
engineEngineThe booted engine.
sandboxSandboxThe guest, from createSandbox.
adapterEngineAdapterHandleThe adapter from createEngineAdapter.
optionsHostLoopOptionsSeed, capacity and the death handler.

Returns

EngineModule

A module to register with createEngine.

Example

ts
import { createHostLoop } from '@aosengine/wasm-host';

const game = createHostLoop(engine, sandbox, adapter, { seed: 1n });
engine.modules.register(game); // or pass it in createEngine({ modules })

createInputEncoder()

ts
function createInputEncoder(maxBodies?): InputEncoder;

Create a reusable frame-input builder.

Parameters

ParameterTypeDefault valueDescription
maxBodiesnumber4096Row capacity for the packed bodies list.

Returns

InputEncoder

An encoder that reuses one frame-input record.

Example

ts
import { createInputEncoder } from '@aosengine/wasm-host';

const encoder = createInputEncoder(2048);
const input = encoder.encode({ frame, dt, elapsed, inputState, bodies, bodyCount });

createSandbox()

ts
function createSandbox(options): Promise<Sandbox>;

Build a sandbox in either mode.

Parameters

ParameterTypeDescription
optionsSandboxOptionsDirect or wasm configuration.

Returns

Promise<Sandbox>

The sandbox, once the component (if any) is instantiated.

Example

ts
import { createSandbox } from '@aosengine/wasm-host';

const sandbox = await createSandbox({
  mode: 'wasm',
  guestModuleUrl: new URL('./guest/game.js', import.meta.url),
  getCoreModule: (p) => fetch(new URL(p, base)).then((r) => WebAssembly.compileStreaming(r)),
  host,
});

hostBindings()

ts
function hostBindings(host): HostBindings;

Adapt a HostApi to the import object instantiate expects.

Parameters

ParameterTypeDescription
hostHostApiThe host services.

Returns

HostBindings

The aos:engine/* import object, with unversioned keys.

Example

ts
import { hostBindings, minimalWasi } from '@aosengine/wasm-host';

const root = await instantiate(getCoreModule, {
  ...minimalWasi(),
  ...hostBindings(host),
});

minimalWasi()

ts
function minimalWasi(options?): Record<string, unknown>;

Build the wasi:* half of the import object.

Parameters

ParameterTypeDescription
optionsMinimalWasiOptionsStderr sink and clock overrides.

Returns

Record<string, unknown>

An object keyed by unversioned WASI interface name.

Example

ts
import { minimalWasi } from '@aosengine/wasm-host';

const imports = { ...minimalWasi(), ...hostBindings(host) };

NullEngineAdapter()

ts
function NullEngineAdapter(): NullAdapter;

An adapter that records every call and does nothing else.

The node-side stand-in for the real engine: boundary tests assert on calls, and deepCopy is deliberately absent, because the whole point is that the guest reuses its command objects.

Returns

NullAdapter

A recording adapter.

Example

ts
import { NullEngineAdapter } from '@aosengine/wasm-host';

const adapter = NullEngineAdapter();
applyOutput(adapter, out);
console.log(adapter.by('spawn').length);

quantizeInput()

ts
function quantizeInput(input): HostFrameInput;

Round every f32 field of a frame-input in place.

bodies is already a Float32Array, so it needs nothing. frame is a u64 and focused a bool; only the timing, mouse, gamepad and contact floats can differ.

Parameters

ParameterTypeDescription
inputHostFrameInputThe frame input to normalise. Mutated in place where it can be, which is every field the host encoder owns.

Returns

HostFrameInput

The same object.

Example

ts
import { quantizeInput } from '@aosengine/wasm-host';

sandbox.tick(quantizeInput(encoder.encode(args)));

quantizeSeed()

ts
function quantizeSeed(seed): bigint;

Round a game-config's floats. There are none today, but the seed must be a bigint and the counts integers; this is the hook if the record grows.

Parameters

ParameterTypeDescription
seednumber | bigintThe seed as the host holds it.

Returns

bigint

The same value, as a bigint.

Example

ts
import { quantizeSeed } from '@aosengine/wasm-host';

const seed = quantizeSeed(0x5eed1234n);

queueResizeEvent()

ts
function queueResizeEvent(
   adapter, 
   width, 
   height, 
   devicePixelRatio
): void;

A sound-ended and resized aware event queue is not needed by every host, so the resize event is published here rather than inside the loop.

Parameters

ParameterTypeDescription
adapterEngineAdapterHandleThe adapter whose queue to push onto.
widthnumberViewport width in device pixels.
heightnumberViewport height in device pixels.
devicePixelRationumberThe ratio the renderer is using.

Returns

void

Nothing.

Example

ts
import { queueResizeEvent } from '@aosengine/wasm-host';

engine.events.on('engine:resize', ({ width, height }) => {
  queueResizeEvent(adapter, width, height, devicePixelRatio);
});