@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
| Parameter | Type |
|---|---|
args | AddBodyCmd |
Returns
void
applyImpulse()
ts
applyImpulse(
body,
impulse,
atPoint
): void;Apply a one-shot impulse.
Parameters
| Parameter | Type |
|---|---|
body | number |
impulse | Vec3 |
atPoint | Vec3 | undefined |
Returns
void
applyTransforms()
ts
applyTransforms(transforms, count): void;Apply packed entity transforms.
Parameters
| Parameter | Type | Description |
|---|---|---|
transforms | Float32Array | Stride 12: entity, flags, position, rotation, scale. |
count | number | Number of rows. The buffer may be longer. |
Returns
void
despawn()
ts
despawn(entity): void;Destroy an entity and everything attached to it.
Parameters
| Parameter | Type |
|---|---|
entity | number |
Returns
void
loadAsset()
ts
loadAsset(asset, priority): void;Start loading an asset.
Parameters
| Parameter | Type |
|---|---|
asset | number |
priority | number |
Returns
void
lookAt()
ts
lookAt(
entity,
target,
weight
): void;Aim a character's head and eyes.
Parameters
| Parameter | Type |
|---|---|
entity | number |
target | Vec3 | undefined |
weight | number |
Returns
void
moveCharacter()
ts
moveCharacter(
body,
desiredVelocity,
jump,
crouch,
maxSlopeDeg
): void;Drive a character body for one step.
Parameters
| Parameter | Type |
|---|---|
body | number |
desiredVelocity | Vec3 |
jump | boolean |
crouch | boolean |
maxSlopeDeg | number |
Returns
void
playSound()
ts
playSound(
sound,
asset,
entity,
position,
volume,
pitch,
looping,
bus
): void;Start a sound.
Parameters
| Parameter | Type |
|---|---|
sound | number |
asset | number |
entity | number | undefined |
position | Vec3 | undefined |
volume | number |
pitch | number |
looping | boolean |
bus | AudioBus |
Returns
void
removeBody()
ts
removeBody(body): void;Destroy a body.
Parameters
| Parameter | Type |
|---|---|
body | number |
Returns
void
say()
ts
say(
entity,
text,
audio,
visemes
): void;Speak a line.
Parameters
| Parameter | Type |
|---|---|
entity | number |
text | string |
audio | number | undefined |
visemes | string | undefined |
Returns
void
setAnim()
ts
setAnim(
entity,
clip,
looping,
speed,
fadeMs,
weight
): void;Play or cross-fade an animation clip.
Parameters
| Parameter | Type |
|---|---|
entity | number |
clip | string |
looping | boolean |
speed | number |
fadeMs | number |
weight | number |
Returns
void
setAsset()
ts
setAsset(entity, asset): void;Attach or detach a renderable.
Parameters
| Parameter | Type |
|---|---|
entity | number |
asset | number | undefined |
Returns
void
setBodyEnabled()
ts
setBodyEnabled(body, enabled): void;Enable or disable a body in the broad phase.
Parameters
| Parameter | Type |
|---|---|
body | number |
enabled | boolean |
Returns
void
setBodyTransform()
ts
setBodyTransform(
body,
position,
rotation,
teleport
): void;Move a body directly.
Parameters
| Parameter | Type |
|---|---|
body | number |
position | Vec3 |
rotation | Quat |
teleport | boolean |
Returns
void
setBodyVelocity()
ts
setBodyVelocity(
body,
linear,
angular
): void;Overwrite a body's velocities; undefined leaves one untouched.
Parameters
| Parameter | Type |
|---|---|
body | number |
linear | Vec3 | undefined |
angular | Vec3 | undefined |
Returns
void
setCamera()
ts
setCamera(camera): void;Apply the camera the guest asked for.
Parameters
| Parameter | Type |
|---|---|
camera | CameraState |
Returns
void
setCharacterState()
ts
setCharacterState(
entity,
state,
velocity,
grounded
): void;Drive a character's locomotion state machine.
Parameters
| Parameter | Type |
|---|---|
entity | number |
state | string |
velocity | Vec3 |
grounded | boolean |
Returns
void
setClipWeights()
ts
setClipWeights(
entity,
clips,
weights,
timeScale
): void;Set explicit per-clip weights.
Parameters
| Parameter | Type |
|---|---|
entity | number |
clips | readonly string[] |
weights | ArrayLike<number> |
timeScale | number |
Returns
void
setExpression()
ts
setExpression(
entity,
space,
weights
): void;Set facial expression coefficients.
Parameters
| Parameter | Type |
|---|---|
entity | number |
space | ExpressionSpace |
weights | ArrayLike<number> |
Returns
void
setHud()
ts
setHud(json): void;Apply the HUD model, or leave the previous one when undefined.
Parameters
| Parameter | Type |
|---|---|
json | string | undefined |
Returns
void
setListener()
ts
setListener(
position,
rotation,
velocity
): void;Place the audio listener.
Parameters
| Parameter | Type |
|---|---|
position | Vec3 |
rotation | Quat |
velocity | Vec3 |
Returns
void
setMaterialParam()
ts
setMaterialParam(
entity,
name,
value
): void;Set one material uniform.
Parameters
| Parameter | Type |
|---|---|
entity | number |
name | string |
value | MaterialValue |
Returns
void
setParent()
ts
setParent(
entity,
parent,
keepWorldTransform
): void;Reparent an entity.
Parameters
| Parameter | Type |
|---|---|
entity | number |
parent | number | undefined |
keepWorldTransform | boolean |
Returns
void
setPointerLock()
ts
setPointerLock(locked): void;Request or release pointer lock.
Parameters
| Parameter | Type |
|---|---|
locked | boolean |
Returns
void
setTimeScale()
ts
setTimeScale(scale): void;Scale simulated time.
Parameters
| Parameter | Type |
|---|---|
scale | number |
Returns
void
spawn()
ts
spawn(
entity,
asset,
position,
rotation,
scale,
flags
): void;Create an entity in the scene.
Parameters
| Parameter | Type |
|---|---|
entity | number |
asset | number | undefined |
position | Vec3 |
rotation | Quat |
scale | Vec3 |
flags | { name?: string; parent?: number; visible: boolean; } |
flags.name? | string |
flags.parent? | number |
flags.visible | boolean |
Returns
void
spawnCharacter()
ts
spawnCharacter(
entity,
bundle,
position,
rotation
): void;Instantiate a splat character bundle.
Parameters
| Parameter | Type |
|---|---|
entity | number |
bundle | number |
position | Vec3 |
rotation | Quat |
Returns
void
stopSound()
ts
stopSound(sound, fadeMs): void;Stop a playing sound.
Parameters
| Parameter | Type |
|---|---|
sound | number |
fadeMs | number |
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
| Parameter | Type |
|---|---|
args | AddBodyCmd |
Returns
void
Inherited from
animationOf()
ts
animationOf(entity): CharacterAnimationState | null;What the guest last asked an entity's animation to do.
Parameters
| Parameter | Type | Description |
|---|---|---|
entity | number | The 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
| Parameter | Type |
|---|---|
body | number |
impulse | Vec3 |
atPoint | Vec3 | undefined |
Returns
void
Inherited from
applyTransforms()
ts
applyTransforms(transforms, count): void;Apply packed entity transforms.
Parameters
| Parameter | Type | Description |
|---|---|---|
transforms | Float32Array | Stride 12: entity, flags, position, rotation, scale. |
count | number | Number of rows. The buffer may be longer. |
Returns
void
Inherited from
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
| Parameter | Type |
|---|---|
entity | number |
Returns
void
Inherited from
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
| Parameter | Type | Description |
|---|---|---|
body | number | Body 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
| Parameter | Type | Description |
|---|---|---|
alpha | number | Interpolation factor in [0, 1), from the engine loop. |
Returns
void
Nothing.
loadAsset()
ts
loadAsset(asset, priority): void;Start loading an asset.
Parameters
| Parameter | Type |
|---|---|
asset | number |
priority | number |
Returns
void
Inherited from
lookAt()
ts
lookAt(
entity,
target,
weight
): void;Aim a character's head and eyes.
Parameters
| Parameter | Type |
|---|---|
entity | number |
target | Vec3 | undefined |
weight | number |
Returns
void
Inherited from
moveCharacter()
ts
moveCharacter(
body,
desiredVelocity,
jump,
crouch,
maxSlopeDeg
): void;Drive a character body for one step.
Parameters
| Parameter | Type |
|---|---|
body | number |
desiredVelocity | Vec3 |
jump | boolean |
crouch | boolean |
maxSlopeDeg | number |
Returns
void
Inherited from
playSound()
ts
playSound(
sound,
asset,
entity,
position,
volume,
pitch,
looping,
bus
): void;Start a sound.
Parameters
| Parameter | Type |
|---|---|
sound | number |
asset | number |
entity | number | undefined |
position | Vec3 | undefined |
volume | number |
pitch | number |
looping | boolean |
bus | AudioBus |
Returns
void
Inherited from
removeBody()
ts
removeBody(body): void;Destroy a body.
Parameters
| Parameter | Type |
|---|---|
body | number |
Returns
void
Inherited from
say()
ts
say(
entity,
text,
audio,
visemes
): void;Speak a line.
Parameters
| Parameter | Type |
|---|---|
entity | number |
text | string |
audio | number | undefined |
visemes | string | undefined |
Returns
void
Inherited from
setAnim()
ts
setAnim(
entity,
clip,
looping,
speed,
fadeMs,
weight
): void;Play or cross-fade an animation clip.
Parameters
| Parameter | Type |
|---|---|
entity | number |
clip | string |
looping | boolean |
speed | number |
fadeMs | number |
weight | number |
Returns
void
Inherited from
setAsset()
ts
setAsset(entity, asset): void;Attach or detach a renderable.
Parameters
| Parameter | Type |
|---|---|
entity | number |
asset | number | undefined |
Returns
void
Inherited from
setBodyEnabled()
ts
setBodyEnabled(body, enabled): void;Enable or disable a body in the broad phase.
Parameters
| Parameter | Type |
|---|---|
body | number |
enabled | boolean |
Returns
void
Inherited from
setBodyTransform()
ts
setBodyTransform(
body,
position,
rotation,
teleport
): void;Move a body directly.
Parameters
| Parameter | Type |
|---|---|
body | number |
position | Vec3 |
rotation | Quat |
teleport | boolean |
Returns
void
Inherited from
EngineAdapter.setBodyTransform
setBodyVelocity()
ts
setBodyVelocity(
body,
linear,
angular
): void;Overwrite a body's velocities; undefined leaves one untouched.
Parameters
| Parameter | Type |
|---|---|
body | number |
linear | Vec3 | undefined |
angular | Vec3 | undefined |
Returns
void
Inherited from
setCamera()
ts
setCamera(camera): void;Apply the camera the guest asked for.
Parameters
| Parameter | Type |
|---|---|
camera | CameraState |
Returns
void
Inherited from
setCharacterState()
ts
setCharacterState(
entity,
state,
velocity,
grounded
): void;Drive a character's locomotion state machine.
Parameters
| Parameter | Type |
|---|---|
entity | number |
state | string |
velocity | Vec3 |
grounded | boolean |
Returns
void
Inherited from
EngineAdapter.setCharacterState
setClipWeights()
ts
setClipWeights(
entity,
clips,
weights,
timeScale
): void;Set explicit per-clip weights.
Parameters
| Parameter | Type |
|---|---|
entity | number |
clips | readonly string[] |
weights | ArrayLike<number> |
timeScale | number |
Returns
void
Inherited from
setExpression()
ts
setExpression(
entity,
space,
weights
): void;Set facial expression coefficients.
Parameters
| Parameter | Type |
|---|---|
entity | number |
space | ExpressionSpace |
weights | ArrayLike<number> |
Returns
void
Inherited from
setHud()
ts
setHud(json): void;Apply the HUD model, or leave the previous one when undefined.
Parameters
| Parameter | Type |
|---|---|
json | string | undefined |
Returns
void
Inherited from
setListener()
ts
setListener(
position,
rotation,
velocity
): void;Place the audio listener.
Parameters
| Parameter | Type |
|---|---|
position | Vec3 |
rotation | Quat |
velocity | Vec3 |
Returns
void
Inherited from
setMaterialParam()
ts
setMaterialParam(
entity,
name,
value
): void;Set one material uniform.
Parameters
| Parameter | Type |
|---|---|
entity | number |
name | string |
value | MaterialValue |
Returns
void
Inherited from
EngineAdapter.setMaterialParam
setParent()
ts
setParent(
entity,
parent,
keepWorldTransform
): void;Reparent an entity.
Parameters
| Parameter | Type |
|---|---|
entity | number |
parent | number | undefined |
keepWorldTransform | boolean |
Returns
void
Inherited from
setPointerLock()
ts
setPointerLock(locked): void;Request or release pointer lock.
Parameters
| Parameter | Type |
|---|---|
locked | boolean |
Returns
void
Inherited from
setTimeScale()
ts
setTimeScale(scale): void;Scale simulated time.
Parameters
| Parameter | Type |
|---|---|
scale | number |
Returns
void
Inherited from
spawn()
ts
spawn(
entity,
asset,
position,
rotation,
scale,
flags
): void;Create an entity in the scene.
Parameters
| Parameter | Type |
|---|---|
entity | number |
asset | number | undefined |
position | Vec3 |
rotation | Quat |
scale | Vec3 |
flags | { name?: string; parent?: number; visible: boolean; } |
flags.name? | string |
flags.parent? | number |
flags.visible | boolean |
Returns
void
Inherited from
spawnCharacter()
ts
spawnCharacter(
entity,
bundle,
position,
rotation
): void;Instantiate a splat character bundle.
Parameters
| Parameter | Type |
|---|---|
entity | number |
bundle | number |
position | Vec3 |
rotation | Quat |
Returns
void
Inherited from
stopSound()
ts
stopSound(sound, fadeMs): void;Stop a playing sound.
Parameters
| Parameter | Type |
|---|---|
sound | number |
fadeMs | number |
Returns
void
Inherited from
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
| Parameter | Type | Description |
|---|---|---|
dt | number | Clamped wall-clock seconds since the previous frame. |
alpha | number | Interpolation 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
| Parameter | Type | Description |
|---|---|---|
message | string | What 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
| Parameter | Type |
|---|---|
level | string |
message | string |
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
| Parameter | Type | Description |
|---|---|---|
loop | EngineModule | The module from createHostLoop. |
ctx | EngineContext | The 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
| Parameter | Type |
|---|---|
config | HostGameConfig |
Returns
void
restore()
ts
restore(state): void;Parameters
| Parameter | Type |
|---|---|
state | Uint8Array |
Returns
void
shutdown()
ts
shutdown(): void;Returns
void
snapshot()
ts
snapshot(): Uint8Array;Returns
Uint8Array
tick()
ts
tick(input): FrameOutput;Parameters
| Parameter | Type |
|---|---|
input | HostFrameInput |
Returns
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
| Parameter | Type |
|---|---|
id | number |
Returns
AssetDesc | undefined
resolveId
ts
resolveId: (name) => number | undefined;Parameters
| Parameter | Type |
|---|---|
name | string |
Returns
number | undefined
aos:engine/env
ts
aos:engine/env: object;log
ts
log: (level, msg) => void;Parameters
| Parameter | Type |
|---|---|
level | string |
msg | string |
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
| Parameter | Type |
|---|---|
center | Vec3 |
radius | number |
filter | QueryFilter |
maxResults | number |
Returns
raycast
ts
raycast: (origin, direction, maxDistance, filter) => RayHit | undefined;Parameters
| Parameter | Type |
|---|---|
origin | Vec3 |
direction | Vec3 |
maxDistance | number |
filter | QueryFilter |
Returns
RayHit | undefined
raycastBatch
ts
raycastBatch: (rays) => (RayHit | undefined)[];Parameters
| Parameter | Type |
|---|---|
rays | RayQuery[] |
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
| Parameter | Type | Description |
|---|---|---|
error | Error | null | Why 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
| Parameter | Type | Description |
|---|---|---|
tag | string | Tag name, always 'div' here. |
Returns
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
| Parameter | Type |
|---|---|
name | string |
value | string |
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
| Parameter | Type | Description |
|---|---|---|
...nodes | unknown[] | 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
| Parameter | Type | Description |
|---|---|---|
json | string | undefined | The 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
| Parameter | Type |
|---|---|
args | EncodeArgs |
Returns
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
| Parameter | Type |
|---|---|
args | AddBodyCmd |
Returns
void
Inherited from
applyImpulse()
ts
applyImpulse(
body,
impulse,
atPoint
): void;Apply a one-shot impulse.
Parameters
| Parameter | Type |
|---|---|
body | number |
impulse | Vec3 |
atPoint | Vec3 | undefined |
Returns
void
Inherited from
applyTransforms()
ts
applyTransforms(transforms, count): void;Apply packed entity transforms.
Parameters
| Parameter | Type | Description |
|---|---|---|
transforms | Float32Array | Stride 12: entity, flags, position, rotation, scale. |
count | number | Number of rows. The buffer may be longer. |
Returns
void
Inherited from
by()
ts
by(method): AdapterCall[];Calls with a given method name.
Parameters
| Parameter | Type |
|---|---|
method | keyof EngineAdapter |
Returns
despawn()
ts
despawn(entity): void;Destroy an entity and everything attached to it.
Parameters
| Parameter | Type |
|---|---|
entity | number |
Returns
void
Inherited from
loadAsset()
ts
loadAsset(asset, priority): void;Start loading an asset.
Parameters
| Parameter | Type |
|---|---|
asset | number |
priority | number |
Returns
void
Inherited from
lookAt()
ts
lookAt(
entity,
target,
weight
): void;Aim a character's head and eyes.
Parameters
| Parameter | Type |
|---|---|
entity | number |
target | Vec3 | undefined |
weight | number |
Returns
void
Inherited from
moveCharacter()
ts
moveCharacter(
body,
desiredVelocity,
jump,
crouch,
maxSlopeDeg
): void;Drive a character body for one step.
Parameters
| Parameter | Type |
|---|---|
body | number |
desiredVelocity | Vec3 |
jump | boolean |
crouch | boolean |
maxSlopeDeg | number |
Returns
void
Inherited from
playSound()
ts
playSound(
sound,
asset,
entity,
position,
volume,
pitch,
looping,
bus
): void;Start a sound.
Parameters
| Parameter | Type |
|---|---|
sound | number |
asset | number |
entity | number | undefined |
position | Vec3 | undefined |
volume | number |
pitch | number |
looping | boolean |
bus | AudioBus |
Returns
void
Inherited from
removeBody()
ts
removeBody(body): void;Destroy a body.
Parameters
| Parameter | Type |
|---|---|
body | number |
Returns
void
Inherited from
reset()
ts
reset(): void;Forget every recorded call.
Returns
void
say()
ts
say(
entity,
text,
audio,
visemes
): void;Speak a line.
Parameters
| Parameter | Type |
|---|---|
entity | number |
text | string |
audio | number | undefined |
visemes | string | undefined |
Returns
void
Inherited from
setAnim()
ts
setAnim(
entity,
clip,
looping,
speed,
fadeMs,
weight
): void;Play or cross-fade an animation clip.
Parameters
| Parameter | Type |
|---|---|
entity | number |
clip | string |
looping | boolean |
speed | number |
fadeMs | number |
weight | number |
Returns
void
Inherited from
setAsset()
ts
setAsset(entity, asset): void;Attach or detach a renderable.
Parameters
| Parameter | Type |
|---|---|
entity | number |
asset | number | undefined |
Returns
void
Inherited from
setBodyEnabled()
ts
setBodyEnabled(body, enabled): void;Enable or disable a body in the broad phase.
Parameters
| Parameter | Type |
|---|---|
body | number |
enabled | boolean |
Returns
void
Inherited from
setBodyTransform()
ts
setBodyTransform(
body,
position,
rotation,
teleport
): void;Move a body directly.
Parameters
| Parameter | Type |
|---|---|
body | number |
position | Vec3 |
rotation | Quat |
teleport | boolean |
Returns
void
Inherited from
EngineAdapter.setBodyTransform
setBodyVelocity()
ts
setBodyVelocity(
body,
linear,
angular
): void;Overwrite a body's velocities; undefined leaves one untouched.
Parameters
| Parameter | Type |
|---|---|
body | number |
linear | Vec3 | undefined |
angular | Vec3 | undefined |
Returns
void
Inherited from
setCamera()
ts
setCamera(camera): void;Apply the camera the guest asked for.
Parameters
| Parameter | Type |
|---|---|
camera | CameraState |
Returns
void
Inherited from
setCharacterState()
ts
setCharacterState(
entity,
state,
velocity,
grounded
): void;Drive a character's locomotion state machine.
Parameters
| Parameter | Type |
|---|---|
entity | number |
state | string |
velocity | Vec3 |
grounded | boolean |
Returns
void
Inherited from
EngineAdapter.setCharacterState
setClipWeights()
ts
setClipWeights(
entity,
clips,
weights,
timeScale
): void;Set explicit per-clip weights.
Parameters
| Parameter | Type |
|---|---|
entity | number |
clips | readonly string[] |
weights | ArrayLike<number> |
timeScale | number |
Returns
void
Inherited from
setExpression()
ts
setExpression(
entity,
space,
weights
): void;Set facial expression coefficients.
Parameters
| Parameter | Type |
|---|---|
entity | number |
space | ExpressionSpace |
weights | ArrayLike<number> |
Returns
void
Inherited from
setHud()
ts
setHud(json): void;Apply the HUD model, or leave the previous one when undefined.
Parameters
| Parameter | Type |
|---|---|
json | string | undefined |
Returns
void
Inherited from
setListener()
ts
setListener(
position,
rotation,
velocity
): void;Place the audio listener.
Parameters
| Parameter | Type |
|---|---|
position | Vec3 |
rotation | Quat |
velocity | Vec3 |
Returns
void
Inherited from
setMaterialParam()
ts
setMaterialParam(
entity,
name,
value
): void;Set one material uniform.
Parameters
| Parameter | Type |
|---|---|
entity | number |
name | string |
value | MaterialValue |
Returns
void
Inherited from
EngineAdapter.setMaterialParam
setParent()
ts
setParent(
entity,
parent,
keepWorldTransform
): void;Reparent an entity.
Parameters
| Parameter | Type |
|---|---|
entity | number |
parent | number | undefined |
keepWorldTransform | boolean |
Returns
void
Inherited from
setPointerLock()
ts
setPointerLock(locked): void;Request or release pointer lock.
Parameters
| Parameter | Type |
|---|---|
locked | boolean |
Returns
void
Inherited from
setTimeScale()
ts
setTimeScale(scale): void;Scale simulated time.
Parameters
| Parameter | Type |
|---|---|
scale | number |
Returns
void
Inherited from
spawn()
ts
spawn(
entity,
asset,
position,
rotation,
scale,
flags
): void;Create an entity in the scene.
Parameters
| Parameter | Type |
|---|---|
entity | number |
asset | number | undefined |
position | Vec3 |
rotation | Quat |
scale | Vec3 |
flags | { name?: string; parent?: number; visible: boolean; } |
flags.name? | string |
flags.parent? | number |
flags.visible | boolean |
Returns
void
Inherited from
spawnCharacter()
ts
spawnCharacter(
entity,
bundle,
position,
rotation
): void;Instantiate a splat character bundle.
Parameters
| Parameter | Type |
|---|---|
entity | number |
bundle | number |
position | Vec3 |
rotation | Quat |
Returns
void
Inherited from
stopSound()
ts
stopSound(sound, fadeMs): void;Stop a playing sound.
Parameters
| Parameter | Type |
|---|---|
sound | number |
fadeMs | number |
Returns
void
Inherited from
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
| Parameter | Type |
|---|---|
config | HostGameConfig |
Returns
void
restore()
ts
restore(state): void;Restore a state produced by snapshot from the same build.
Parameters
| Parameter | Type |
|---|---|
state | Uint8Array |
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
| Parameter | Type |
|---|---|
input | HostFrameInput |
Returns
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
| Parameter | Type |
|---|---|
path | string |
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
| Parameter | Type |
|---|---|
getCoreModule | (path) => Promise<WebAssembly.Module> |
imports | Record<string, unknown> |
instantiateCore | typeof 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
| Parameter | Type |
|---|---|
bytes | Uint8Array |
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
| Parameter | Type | Description |
|---|---|---|
adapter | EngineAdapter | The engine. |
command | Command | The 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
| Parameter | Type | Description |
|---|---|---|
adapter | EngineAdapter | The engine. |
out | FrameOutput | The 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
| Parameter | Type | Description |
|---|---|---|
options | DirectSandboxOptions | The game definition and host services. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
options | DomHudOptions | Container, document and root class name. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
engine | Engine | The engine from createEngine. |
options | EngineAdapterOptions | Modules, HUD and capacity. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
engine | Engine | The booted engine. |
adapter | EngineAdapterHandle | The adapter, for the body-to-entity mapping queries report. |
options | EngineHostOptions | Seed, log sink and query capacity. |
Returns
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
| Parameter | Type | Default value | Description |
|---|---|---|---|
order | number | 100 | Module order. Defaults to 100: after physics, before rendering helpers. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
engine | Engine | The booted engine. |
sandbox | Sandbox | The guest, from createSandbox. |
adapter | EngineAdapterHandle | The adapter from createEngineAdapter. |
options | HostLoopOptions | Seed, capacity and the death handler. |
Returns
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
| Parameter | Type | Default value | Description |
|---|---|---|---|
maxBodies | number | 4096 | Row capacity for the packed bodies list. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
options | SandboxOptions | Direct 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
| Parameter | Type | Description |
|---|---|---|
host | HostApi | The host services. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
options | MinimalWasiOptions | Stderr 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
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
| Parameter | Type | Description |
|---|---|---|
input | HostFrameInput | The frame input to normalise. Mutated in place where it can be, which is every field the host encoder owns. |
Returns
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
| Parameter | Type | Description |
|---|---|---|
seed | number | bigint | The 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
| Parameter | Type | Description |
|---|---|---|
adapter | EngineAdapterHandle | The adapter whose queue to push onto. |
width | number | Viewport width in device pixels. |
height | number | Viewport height in device pixels. |
devicePixelRatio | number | The 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);
});