@gameable/sdk <a class="header-anchor" href="#gameable-sdk" aria-label="Permalink to &quot;@gameable/sdk&quot;">​

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

setCooldown()

setCooldown(ability, seconds): void;

Change an ability's cooldown for every owner, for example from ctx.rules. It applies from the next recharge clock that starts; a running clock keeps its duration. reset() goes back to the cooldown given at creation.

Parameters

Parameter	Type
`ability`	`string` \| `number`
`seconds`	`number`

Returns

void

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

ShapeOptions.collision

step()

step(ctx): void;

Advance active clocks by one integer step.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

use()

use(
   ctx, 
   owner, 
   ability
): boolean;

Spend one charge; start an idle recharge clock using ctx.dt.

Parameters

Parameter	Type
`ctx`	`GameContext`
`owner`	`number`
`ability`	`string` \| `number`

Returns

boolean

AbilitiesOptions

Attribute declarations, fixed storage limits and synchronous borrowed event payloads.

Example

const options: AbilitiesOptions = { attributes: { health: { base: 100, min: 0, max: 100 } } };

Properties

attributes

attributes: Record<string, {
  base: number;
  max?: number;
  min?: number;
}>;

maxAbilities?

optional maxAbilities?: number;

maxEffects?

optional maxEffects?: number;

maxTags?

optional maxTags?: number;

Methods

onAbilityActivated()?

optional onAbilityActivated(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`event`	`Readonly`<`AbilityEvent`>
`ctx`	`GameContext`

Returns

void

onAbilityEnded()?

optional onAbilityEnded(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`event`	`Readonly`<`AbilityEvent`>
`ctx`	`GameContext`

Returns

void

onAbilityFailed()?

optional onAbilityFailed(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`event`	`Readonly`<`FailedEvent`>
`ctx`	`GameContext`

Returns

void

onAttributeChanged()?

optional onAttributeChanged(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`event`	`Readonly`<`AttributeEvent`>
`ctx`	`GameContext`

Returns

void

onEffectApplied()?

optional onEffectApplied(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`event`	`Readonly`<`EffectEvent`>
`ctx`	`GameContext`

Returns

void

onEffectExpired()?

optional onEffectExpired(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`event`	`Readonly`<`EffectEvent`>
`ctx`	`GameContext`

Returns

void

AbilityDefinition

Ability definition registered at module scope or in init; cooldown starts on activation.

Example

defineAbility({ id: 'dash', cooldown: 1, cost: { attribute: 'stamina', amount: 5 } });

Extends

Gate

Properties

blockedByTags?

optional blockedByTags?: readonly string[];

Inherited from

Gate.blockedByTags

cooldown

cooldown: number;

cost

cost: object;

amount

amount: number;

attribute

attribute: string;

duration?

optional duration?: number;

grantsTagsWhileActive?

optional grantsTagsWhileActive?: readonly string[];

id

id: string;

requiresTags?

optional requiresTags?: readonly string[];

Inherited from

Gate.requiresTags

ActionObject

The thing an action is done at, as the game has it.

Properties

depth

depth: number;

height

height: number;

Its top over that floor, and its size across and along the way, metres.

id

id: number;

The game's own number for it, said back in events.

position

position: Vec3;

Its middle, on the floor it stands on, world space.

width

width: number;

yaw

yaw: number;

The way across it, radians about +Y (0 is +Z).

ActionState

A pooled button reading; read immediately, do not retain across calls.

Example

import type { ActionState } from 'gameable';
const idle: ActionState = { down: false, pressed: false, released: false };

Properties

down

down: boolean;

pressed

pressed: boolean;

released

released: boolean;

ActorCatalog

Versioned actor descriptions in class registration order.

Example

const catalog: ActorCatalog = actorCatalog();

Properties

catalogVersion

catalogVersion: 1;

classes

classes: ActorCatalogEntry[];

ActorCatalogEntry

One registered actor's authoring surface.

Example

const entry: ActorCatalogEntry = actorCatalog().classes[0];

Properties

category?

optional category?: string;

components

components: object[];

kind

kind: "character" | "box" | "sphere" | "capsule" | "mesh" | "scene";

name

name: string;

description?

optional description?: string;

events

events: readonly object[];

name

name: string;

premade

premade: boolean;

props

props: Record<string, CatalogProp>;

ActorClass

A registered, validated actor definition.

Example

const cls = defineActor('Marker', { components: { root: scene() } });

Type Parameters

Type Parameter	Default type
`P` extends `object`	`object`

Properties

name

readonly name: string;

Unique registry name.

order

readonly order: readonly string[];

Component names sorted parent before child.

prefabs

readonly prefabs: Readonly<Record<string, PrefabDef & PlaceholderSpec>>;

Resolved prefab declarations, in component order.

spec

readonly spec: ActorSpec<P>;

Declaration and hooks.

ActorComponent

Declarative scene or primitive component.

Example

const component: ActorComponent = scene();

Extends

ShapeOptions

Extended by

WaypointMovementComponent

Properties

asset?

optional asset?: string;

Manifest asset id for a mesh.

attach?

optional attach?: string;

Parent component name; defaults to root for non-root components.

Inherited from

ShapeOptions.attach

body?

optional body?: "kinematic" | "dynamic" | "static";

Blocking body motion; defaults to static.

Inherited from

ShapeOptions.body

ccd?

optional ccd?: boolean;

Continuous collision detection for fast dynamic bodies.

Inherited from

ShapeOptions.ccd

collision?

optional collision?: 
  | "none"
  | "overlap"
  | "block"
  | CollisionSetup
  | "NoCollision"
  | "BlockAll"
  | "OverlapAll"
  | "BlockAllDynamic"
  | "OverlapAllDynamic"
  | "IgnoreOnlyPawn"
  | "OverlapOnlyPawn"
  | "Pawn"
  | "Spectator"
  | "CharacterMesh"
  | "PhysicsActor"
  | "Destructible"
  | "InvisibleWall"
  | "InvisibleWallDynamic"
  | "Trigger"
  | "Ragdoll"
  | "Vehicle"
  | "UI";

Collision response; defaults to block.

Inherited from

dimensions?

optional dimensions?: readonly string[];

Spawn-time prop names supplying dimensions: ['halfExtents'] or ['radius', 'halfHeight'].

Inherited from

ShapeOptions.dimensions

dims?

optional dims?: readonly number[];

Primitive dimensions in metres.

fit?

optional fit?: "box" | "convex-hull" | "mesh";

mesh() only: give the mesh a body fitted to its own model, built by the page from the model's geometry and scale once it loads: 'box' its bounds, 'convex-hull' its hull, 'mesh' its triangles (static only).

Inherited from

ShapeOptions.fit

kind

kind: "character" | "box" | "sphere" | "capsule" | "mesh" | "scene";

Component family.

layer?

optional layer?: CollisionLayers;

Physics collision layer.

Inherited from

ShapeOptions.layer

mask?

optional mask?: CollisionLayers;

Raw physics mask; cannot accompany a named/custom collision policy.

Inherited from

ShapeOptions.mask

mass?

optional mass?: number;

Dynamic mass in kilograms.

Inherited from

ShapeOptions.mass

offset?

optional offset?: readonly [number, number, number];

Translation in the parent's space.

Inherited from

ShapeOptions.offset

reportHits?

optional reportHits?: boolean;

Request blocking contact callbacks.

Inherited from

ShapeOptions.reportHits

rotation?

optional rotation?: Quat;

Local quaternion, default identity.

Inherited from

ShapeOptions.rotation

scale?

optional scale?: readonly [number, number, number];

Local per-axis scale, default one.

Inherited from

ShapeOptions.scale

Methods

create()?

optional create(
   self, 
   ctx, 
   name
): void;

Initialize JSON-safe component state during authority spawn.

Parameters

Parameter	Type
`self`	`ActorHandle`
`ctx`	`GameContext`
`name`	`string`

Returns

void

destroy()?

optional destroy(
   self, 
   ctx, 
   name
): void;

Release component bookkeeping on authority destruction, before entities are despawned.

Parameters

Parameter	Type
`self`	`ActorHandle`
`ctx`	`GameContext`
`name`	`string`

Returns

void

step()?

optional step(
   self, 
   ctx, 
   name
): void;

Advance on each authority fixed step, before the actor tick.

Parameters

Parameter	Type
`self`	`ActorHandle`
`ctx`	`GameContext`
`name`	`string`

Returns

void

ActorHandle

A live actor backed by ECS entities.

Example

const actor: ActorHandle = spawnActor(ctx, cls, { position: { x: 0, y: 0, z: 0 } });

Type Parameters

Type Parameter	Default type
`P` extends `object`	`object`

Properties

alive

readonly alive: boolean;

False once destruction completes.

class

readonly class: ActorClass<P>;

Actor class.

entity

readonly entity: number;

Root ECS entity.

instigator?

readonly optional instigator?: ActorHandle<object>;

Actor responsible for this spawn, if any.

name

readonly name: string;

Optional instance name.

owner?

readonly optional owner?: ActorHandle<object>;

Owning actor, if any.

persist

readonly persist: "level" | "session";

Travel lifetime; session actors join the keep-list.

position

readonly position: Readonly<Vec3>;

Borrowed current world position; do not mutate.

props

readonly props: P;

Mutable instance properties.

quarantined

readonly quarantined: boolean;

True after eight consecutive failing actor steps; rendering and collision continue.

rotation

readonly rotation: Readonly<Quat>;

Borrowed current world quaternion; do not mutate.

source?

readonly optional source?: ActorSource;

The level entry that placed this actor, when one did: an editor may write it back.

state

readonly state: Record<string, unknown>;

JSON-safe instance state, included in actor snapshots. Allocate scratch separately.

Methods

addTag()

addTag(tag): void;

Add an instance tag once.

Parameters

Parameter	Type
`tag`	`string`

Returns

void

component()

component(name): number;

Find a component entity; throws on unknown names.

Parameters

Parameter	Type
`name`	`string`

Returns

number

hasTag()

hasTag(tag): boolean;

Test an instance tag.

Parameters

Parameter	Type
`tag`	`string`

Returns

boolean

removeTag()

removeTag(tag): void;

Remove an instance tag.

Parameters

Parameter	Type
`tag`	`string`

Returns

void

setPosition()

setPosition(ctx, value): void;

Set world position and teleport any body.

Parameters

Parameter	Type
`ctx`	`GameContext`
`value`	`Vec3`

Returns

void

setRotation()

setRotation(ctx, value): void;

Set world quaternion and teleport any body.

Parameters

Parameter	Type
`ctx`	`GameContext`
`value`	`Quat`

Returns

void

ActorRow

One actor as the snapshot header carries it. The page's editor reads these rows (peekSnapshotHeader) to list actors with their names, classes, props and sources.

Example

const row: ActorRow = { id: 1, entity: 2, class: 'Door', name: 'gate', props: {}, tags: [], components: { root: 2 }, begun: true, remaining: 0, pending: null };

Properties

begun

begun: boolean;

class

class: string;

components

components: Record<string, number>;

entity

entity: number;

id

id: number;

instigator?

optional instigator?: number;

name

name: string;

owner?

optional owner?: number;

pending

pending: EndPlayReason | null;

persist?

optional persist?: "level" | "session";

props

props: object;

remaining

remaining: number;

shapes?

optional shapes?: Record<string, readonly number[]>;

source?

optional source?: ActorSource;

Present when a level file placed the actor.

state?

optional state?: Record<string, unknown>;

ActorSource

Where a level file placed an actor: the level's name and the entry's index in its actors. An actor with a source is one an editor may edit and write back; an actor spawned from code has none.

Example

const source: ActorSource = { level: 'main', entry: 3 };

Properties

entry

entry: number;

The entry's index in the level file's actors.

level

level: string;

The level's name: the key in defineGame({ levels }), 'main' for a bare level.

ActorSpawnOptions

Instance overrides used by spawnActor.

Example

const options: ActorSpawnOptions = { position: { x: 0, y: 0, z: 0 }, yaw: 90 };

Type Parameters

Type Parameter	Default type
`P` extends `object`	`Record`<`string`, `unknown`>

Properties

instigator?

optional instigator?: ActorHandle<object>;

Actor responsible for this spawn.

name?

optional name?: string;

Instance lookup name.

owner?

optional owner?: ActorHandle<object>;

Owning actor.

persist?

optional persist?: "level" | "session";

Defaults to level: destroyed on travel.

position

position: Vec3;

World root position.

props?

optional props?: Partial<P>;

Override default properties.

rotation?

optional rotation?: Quat;

World quaternion; takes precedence over yaw.

scale?

optional scale?: readonly [number, number, number];

Root scale [x, y, z]. Attached components inherit it; a body does not (a body has no scale), so a box or capsule keeps its authored dims.

source?

optional source?: ActorSource;

The level entry this actor came from, when a level file placed it.

tags?

optional tags?: readonly string[];

Additional instance tags.

yaw?

optional yaw?: number;

Degrees about +Y, zero faces +Z.

ActorSpec

Default components, plain props and authority lifecycle hooks.

Example

const spec: ActorSpec = { components: { root: scene() } };

Type Parameters

Type Parameter	Default type
`P` extends `object`	`Record`<`string`, `unknown`>

Properties

category?

optional category?: string & object | "Markers" | "Volumes" | "Gameplay" | "Scene";

Place Actors group; user classes may supply any string.

components

components: Record<string, ActorComponent>;

Exactly one component named root.

description?

optional description?: string;

One-sentence purpose for authoring tools.

events?

optional events?: readonly object[];

Callbacks or events exposed to game code.

health?

optional health?: number;

Initial root hit points.

lifeSpan?

optional lifeSpan?: number;

Seconds until destruction; zero means forever.

overlaps?

optional overlaps?: boolean;

Generate overlap events on volumes.

props?

optional props?: P;

Plain JSON-safe default properties.

propsMeta?

optional propsMeta?: Record<string, PropMeta>;

Descriptions and constraints for declared default props.

tags?

optional tags?: readonly string[];

Initial tags.

Methods

beginPlay()?

optional beginPlay(self, ctx): void;

Runs at the beginning of the next actor step.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

void

clientTick()?

optional clientTick(self, ctx): void;

Client cosmetic fixed-step update.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

void

configureComponents()?

optional configureComponents(props): Readonly<Record<string, Pick<PrefabSpec, "asset" | "character" | "body" | "scale"> & PlaceholderSpec>>;

Initial prefab overrides by component name, evaluated from instance props before spawn. Keeps the declared component graph; use for assets, scale and body dimensions.

Parameters

Parameter	Type
`props`	`P`

Returns

Readonly<Record<string, Pick<PrefabSpec, "asset" | "character" | "body" | "scale"> & PlaceholderSpec>>

construct()?

optional construct(self, ctx): void;

Runs synchronously after spawn properties are applied.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

void

endPlay()?

optional endPlay(
   self, 
   ctx, 
   reason
): void;

Runs exactly once on authority destruction.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`
`reason`	`EndPlayReason`

Returns

void

interactPrompt()?

optional interactPrompt(
   self, 
   seat, 
   ctx
): string | null;

Per-player prompt; null excludes this actor from interaction selection.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`seat`	`number`
`ctx`	`GameContext`

Returns

string | null

onBeginOverlap()?

optional onBeginOverlap(
   self, 
   other, 
   ctx
): void;

An eligible actor or player entered an overlap shape.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`other`	`ActorOther`
`ctx`	`GameContext`

Returns

void

onClosed()?

optional onClosed(self, ctx): void;

A kit door reached its fully closed pose.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

void

onDamage()?

optional onDamage(
   self, 
   amount, 
   info, 
   ctx
): void;

Receives damage before health is reduced.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`amount`	`number`
`info`	`DamageInfo`
`ctx`	`GameContext`

Returns

void

onEndOverlap()?

optional onEndOverlap(
   self, 
   other, 
   ctx
): void;

An eligible actor or player exited an overlap shape.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`other`	`ActorOther`
`ctx`	`GameContext`

Returns

void

onHit()?

optional onHit(
   self, 
   other, 
   ctx, 
   contact
): void;

A reporting blocking component received a contact.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`other`	`ActorOther`
`ctx`	`GameContext`
`contact`	`Contact`

Returns

void

onInteract()?

optional onInteract(
   self, 
   who, 
   ctx
): void;

Optional interaction callback invoked by an interactable component.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`who`	`number`
`ctx`	`GameContext`

Returns

void

onLocked()?

optional onLocked(
   self, 
   who, 
   ctx
): void;

A player attempted to open a kit door without its key.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`who`	`number`
`ctx`	`GameContext`

Returns

void

onOpened()?

optional onOpened(self, ctx): void;

A kit door reached its fully open pose.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

void

onPassed()?

optional onPassed(
   self, 
   who, 
   ctx
): void;

A player crossed a kit door's closed plane while not closed.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`who`	`number`
`ctx`	`GameContext`

Returns

void

onPickedUp()?

optional onPickedUp(
   self, 
   who, 
   ctx
): void;

Optional custom pickup callback.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`who`	`number`
`ctx`	`GameContext`

Returns

void

onPossess()?

optional onPossess(
   self, 
   pawn, 
   ctx
): void;

This controller took a pawn.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`pawn`	`number`
`ctx`	`GameContext`

Returns

void

onPressed()?

optional onPressed(self, ctx): void;

A pressure plate reaches its required occupancy.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

void

onReleased()?

optional onReleased(self, ctx): void;

A pressure plate releases after its hold time.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

void

onSwitched()?

optional onSwitched(
   self, 
   on, 
   who, 
   ctx
): void;

A lever changes signal; who is the last activator, or zero for a startOn reset.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`on`	`boolean`
`who`	`number`
`ctx`	`GameContext`

Returns

void

onTravel()?

optional onTravel(
   self, 
   who, 
   ctx
): void;

A level door accepted a crossing; clear or redirect toLevel before loading.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`who`	`number`
`ctx`	`GameContext`

Returns

void

onUnlocked()?

optional onUnlocked(
   self, 
   who, 
   ctx
): void;

A player unlocked a kit door.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`who`	`number`
`ctx`	`GameContext`

Returns

void

onUnPossess()?

optional onUnPossess(
   self, 
   pawn, 
   ctx
): void;

This controller let its pawn go.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`pawn`	`number`
`ctx`	`GameContext`

Returns

void

possessedBy()?

optional possessedBy(
   self, 
   controller, 
   ctx
): void;

This pawn was taken by a controller.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`controller`	`ActorHandle`
`ctx`	`GameContext`

Returns

void

restoreState()?

optional restoreState(self): void;

Rebuild external bookkeeping from state after all actor handles and ownership are restored.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>

Returns

void

saveState()?

optional saveState(self): void;

Copy external bookkeeping into JSON-safe state immediately before an actor snapshot.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>

Returns

void

tick()?

optional tick(self, ctx): void;

Authority and solo fixed-step update.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

void

unPossessed()?

optional unPossessed(
   self, 
   controller, 
   ctx
): void;

This pawn's controller let it go.

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`controller`	`ActorHandle`
`ctx`	`GameContext`

Returns

void

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;

overlapMask?

optional overlapMask?: CollisionLayers;

Mixed response companion sensor mask.

position

position: Vec3;

restitution

restitution: number;

rotation

rotation: Quat;

shape

shape: Shape;

AddJointCmd

AddJointCmd: radians and metres at the host boundary.

Example

import type { AddJointCmd } from 'gameable';
const value: AddJointCmd = { joint: 1, kind: 'fixed', bodyA: 1, anchor: { x: 0, y: 0, z: 0 }, axis: { x: 0, y: 1, z: 0 }, limitMin: 1, limitMax: 0, maxFriction: 0, axes: [] };

Properties

anchor

anchor: Vec3;

anchorB?

optional anchorB?: Vec3;

axes

axes: readonly JointAxis[];

axis

axis: Vec3;

bodyA

bodyA: number;

bodyB?

optional bodyB?: number;

joint

joint: number;

kind

kind: JointKind;

limitMax

limitMax: number;

limitMin

limitMin: number;

maxFriction

maxFriction: number;

spring?

optional spring?: JointSpring;

AddVehicleCmd

Vehicle attachment command; body must already be dynamic.

Example

const command = { body: 1, settings, initialState };

Properties

body

body: number;

initialState

initialState: VehicleState;

settings

settings: VehicleSettings;

AIControllerProps

AI tuning, in metres, seconds and degrees.

Example

const props: AIControllerProps = { moveSpeed: 4, acceptanceRadius: 0.5, turnRate: 360, possessOnSpawn: '' };

Properties

acceptanceRadius

acceptanceRadius: number;

moveSpeed

moveSpeed: number;

possessOnSpawn

possessOnSpawn: string;

turnRate

turnRate: number;

AnimEventData

An animation clip passed a named marker: 'ended' when a once-only clip finished, 'loop' when a looping clip came round (both from the host's mixer), or a marker embedded in the clip.

Properties

clip

clip: string;

entity

entity: number;

name

name: string;

time

time: number;

Clip-local time of the marker, seconds.

ApplyImpulseCmd

Apply a one-shot impulse.

Properties

atPoint?

optional atPoint?: Vec3;

body

body: number;

impulse

impulse: Vec3;

ApplyLevelEditsOptions

What applyLevelEdits accepts besides the edits. classes names the game's own classes for a reader that has not loaded the game: the validation knows them, and a reclass to one keeps only the props the edit names, since their props are not known here.

Extends

ValidateLevelOptions

Properties

catalog?

optional catalog?: ReadonlyMap<string, ActorClass<object>>;

Detached declarations for static tools; bypasses the live registry and deprecation logging.

Inherited from

ValidateLevelOptions.catalog

classes?

optional classes?: readonly string[] | "any";

The game's own classes (defineActor in its source), for a reader that has not loaded the game's module, such as a tool on Node: a listed class passes as known, with its props unchecked. 'any' accepts every well-formed class name; prefer the list when the names are at hand.

Inherited from

ValidateLevelOptions.classes

validate?

optional validate?: boolean;

Run validateLevel on the result: the premade classes must be imported first.

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;

AssetLoadedEvent

An asset finished loading.

Properties

asset

asset: number;

name

name: string;

AttachmentOptions

Local transform shared by actor components and actor attachments.

Example

const local: AttachmentOptions = { offset: [0, 1, 0] };

Extended by

ComponentOptions

Properties

offset?

optional offset?: readonly [number, number, number];

Translation in the parent's space.

rotation?

optional rotation?: Quat;

Local quaternion, default identity.

scale?

optional scale?: readonly [number, number, number];

Local per-axis scale, default one.

AudioComponentOptions

Playback settings for an entity-attached sound.

Example

const options: AudioComponentOptions = { autoPlay: true };

Extends

ComponentOptions

Properties

attach?

optional attach?: string;

Parent component name; defaults to root for non-root components.

Inherited from

autoPlay?

optional autoPlay?: boolean;

bus?

optional bus?: AudioBus;

looping?

optional looping?: boolean;

offset?

optional offset?: readonly [number, number, number];

Translation in the parent's space.

Inherited from

pitch?

optional pitch?: number;

rotation?

optional rotation?: Quat;

Local quaternion, default identity.

Inherited from

scale?

optional scale?: readonly [number, number, number];

Local per-axis scale, default one.

Inherited from

SlidingDoorProps.action

volume?

optional volume?: number;

AudioVolumeProps

Solo listener region settings.

Example

const props: Partial<AudioVolumeProps> = { reverb: 'cave', priority: 2 };

Properties

bus

bus: AudioBus;

fadeMs

fadeMs: number;

halfExtents

halfExtents: [number, number, number];

priority

priority: number;

reverb

reverb: FxPreset;

AutomaticDoorProps

Automatic sliding door tuning.

Example

const props: Partial<AutomaticDoorProps> = { holdSeconds: 1 };

Extends

SlidingDoorProps

Properties

action

action: string;

Inherited from

asset?

optional asset?: string;

Inherited from

SlidingDoorProps.asset

autoCloseSeconds

autoCloseSeconds: number;

Inherited from

SlidingDoorProps.autoCloseSeconds

closePrompt

closePrompt: string;

Inherited from

SlidingDoorProps.closePrompt

closeSound

closeSound: string;

Inherited from

SlidingDoorProps.closeSound

colour

colour: [number, number, number];

Inherited from

SlidingDoorProps.colour

consumeKey

consumeKey: boolean;

Inherited from

SlidingDoorProps.consumeKey

enabled

enabled: boolean;

Inherited from

SlidingDoorProps.enabled

facingDegrees

facingDegrees: number;

Inherited from

SlidingDoorProps.facingDegrees

height

height: number;

Closed doorway height in metres.

Inherited from

SlidingDoorProps.height

holdSeconds

holdSeconds: number;

lockedBy

lockedBy: string;

Inherited from

SlidingDoorProps.lockedBy

lockedMessage

lockedMessage: string;

Inherited from

SlidingDoorProps.lockedMessage

lockedPrompt

lockedPrompt: string;

Inherited from

SlidingDoorProps.lockedPrompt

lockedSound

lockedSound: string;

Inherited from

SlidingDoorProps.lockedSound

look

look: "none" | "wood" | "metal";

Inherited from

SlidingDoorProps.look

once

once: boolean;

Inherited from

SlidingDoorProps.once

openPrompt

openPrompt: string;

Inherited from

SlidingDoorProps.openPrompt

openSound

openSound: string;

Inherited from

SlidingDoorProps.openSound

opensWhen

opensWhen: string[];

Inherited from

SlidingDoorProps.opensWhen

panels

panels: 1 | 2;

Inherited from

SlidingDoorProps.panels

prompt

prompt: string;

Inherited from

SlidingDoorProps.prompt

range

range: number;

Inherited from

SlidingDoorProps.range

seconds

seconds: number;

Inherited from

SlidingDoorProps.seconds

slide

slide: "left" | "right" | "up";

Inherited from

SlidingDoorProps.slide

startOpen

startOpen: boolean;

Inherited from

SlidingDoorProps.startOpen

stayOpen

stayOpen: boolean;

Inherited from

SlidingDoorProps.stayOpen

thickness

thickness: number;

Leaf thickness in metres.

Inherited from

SlidingDoorProps.thickness

toggledBy

toggledBy: "proximity" | "interact" | "signal";

Inherited from

SlidingDoorProps.toggledBy

travel

travel: number;

Inherited from

SlidingDoorProps.travel

width

width: number;

Closed doorway width in metres.

Inherited from

SlidingDoorProps.width

Axis2

A two-axis reading. Each facade returns its own object, the same one every call.

Properties

x

x: number;

y

y: number;

BeatEvent

beat-event payload.

Example

`const value: BeatEvent = { beat: 0, bar: 0, beatInBar: 0, lateMs: 4 };`

Properties

bar

bar: number;

Bar number from zero.

beat

beat: number;

Beat number from zero.

beatInBar

beatInBar: number;

Beat within the bar.

lateMs

lateMs: number;

Milliseconds since the beat was heard.

BehaviorTree

A compiled tree with independent, preallocated memory for each entity.

Example

import { bt, createBehaviorTree, type BehaviorTree } from 'gameable';
const tree: BehaviorTree<null> = createBehaviorTree(bt.wait(1));
tree.tick(null, 0, 1 / 60);

Type Parameters

Type Parameter
`C`

Properties

nodeCount

readonly nodeCount: number;

Number of node occurrences in the compiled tree.

Methods

reset()

reset(entity): void;

Forget all timers, memory and stamps for this entity.

Parameters

Parameter	Type	Description
`entity`	`number`	An integer in [0, maxEntities).

Returns

void

Nothing.

tick()

tick(
   ctx, 
   entity, 
   dt
): BtStatus;

Tick once per fixed step for this entity. Game callbacks must not allocate.

Parameters

Parameter	Type	Description
`ctx`	`C`	The game's context.
`entity`	`number`	An integer in [0, maxEntities).
`dt`	`number`	Fixed-step seconds.

Returns

BtStatus

The root status.

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;

physicsOnly?

optional physicsOnly?: boolean;

Simulates but is excluded from queries.

queryOnly?

optional queryOnly?: boolean;

Found by queries without simulation response.

reportContacts?

optional reportContacts?: boolean;

sensor?

optional sensor?: boolean;

BodySpec

The physics body a prefab carries.

Properties

collision?

optional collision?: 
  | CollisionSetup
  | "NoCollision"
  | "BlockAll"
  | "OverlapAll"
  | "BlockAllDynamic"
  | "OverlapAllDynamic"
  | "IgnoreOnlyPawn"
  | "OverlapOnlyPawn"
  | "Pawn"
  | "Spectator"
  | "CharacterMesh"
  | "PhysicsActor"
  | "Destructible"
  | "InvisibleWall"
  | "InvisibleWallDynamic"
  | "Trigger"
  | "Ragdoll"
  | "Vehicle"
  | "UI";

Collision policy; excludes raw layer/mask.

dims?

optional dims?: readonly number[];

Dimensions: box half-extents; sphere [r]; capsule/cylinder [r, cylinder half-height]; plane normal.

fit?

optional fit?: string | boolean;

Shape built from the model as drawn: true (asset) or a model id; box, convex-hull, mesh.

flags?

optional flags?: BodyFlags;

Per-body switches.

friction?

optional friction?: number;

Coulomb friction. Default 0.5.

kind

kind: BodyKind;

Body kind; character uses CharacterVirtual.

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;

Mass in kg (dynamic only). Default 1.

restitution?

optional restitution?: number;

Bounciness in 0..1. Default 0.

shape

shape: ShapeKind;

Collision shape family.

BtNode

An opaque, stateless description. Build once, including at module scope.

Example

import { bt, type BtNode } from 'gameable';
const pause: BtNode<null> = bt.wait(1);

Type Parameters

Type Parameter
`C`

BurstOptions

Burst direction, size, brightness and colour overrides.

Example

import { vfx, type BurstOptions } from 'gameable';
const options: BurstOptions = { scale: 2 };
vfx.burst('explosion', { x: 0, y: 1, z: 0 }, options);

Extended by

StartOptions

Properties

direction?

optional direction?: Vec3;

Emission direction; absent uses the preset's own direction.

intensity?

optional intensity?: number;

Count and brightness multiplier, default 1.

scale?

optional scale?: number;

Size multiplier, default 1.

tint?

optional tint?: Vec3;

Linear RGB override; values over 1 glow under bloom.

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;

Capsule

Capsule dimensions; halfHeight excludes the hemispheres.

Example

const capsule: Capsule = { radius: 0.35, halfHeight: 0.55 };

Properties

halfHeight

halfHeight: number;

radius

radius: number;

CatalogProp

A detached JSON property default and its authoring metadata.

Example

const prop: CatalogProp = { default: 2, description: 'Reach.', type: 'number' };

Extends

PropMeta

Properties

const?

optional const?: boolean;

Restrict a boolean branch to one literal value.

Inherited from

PropMeta.const

default

default: unknown;

description

description: string;

Inherited from

PropMeta.description

fields?

optional fields?: Record<string, PropMeta>;

Inherited from

PropMeta.fields

group?

optional group?: string;

Shared reference table; actor-specific differences remain documented on the actor.

Inherited from

PropMeta.group

items?

optional items?: PropMeta;

Inherited from

PropMeta.items

max?

optional max?: number;

Inherited from

PropMeta.max

min?

optional min?: number;

Inherited from

PropMeta.min

nullable?

optional nullable?: boolean;

Accept null in addition to the described shape.

Inherited from

PropMeta.nullable

oneOf?

optional oneOf?: readonly PropMeta[];

Inherited from

PropMeta.oneOf

optional?

optional optional?: boolean;

Allow this field to be omitted from a fixed-shape object.

Inherited from

PropMeta.optional

type?

optional type?: 
  | "string"
  | "number"
  | "boolean"
  | "object"
  | "color"
  | "vec3"
  | "array"
  | "enum";

Inherited from

PropMeta.type

unit?

optional unit?: string;

Inherited from

PropMeta.unit

values?

optional values?: readonly string[];

Inherited from

PropMeta.values

CharacterMovement

Mutable movement state, owned independently by each mover.

Example

const speed = Math.hypot(movement.velocity.x, movement.velocity.z);

Properties

currentFloor

currentFloor: FloorResult;

forceNextFloorCheck

forceNextFloorCheck: boolean;

justTeleported

justTeleported: boolean;

mode

mode: "walking" | "falling";

settings

settings: CharacterMovementSettings;

velocity

velocity: Vec3;

work

readonly work: MovementWork;

Preallocated algorithm scratch; do not modify.

CharacterMovementOptions

Movement solver settings plus root capsule and facing options. Dims override capsule settings.

Example

const options: CharacterMovementOptions = { maxWalkSpeed: 4, rotationRate: 540 };

Extends

Partial<CharacterMovementSettings>

Properties

airControl?

optional airControl?: number;

Inherited from

CharacterMovementSettings.airControl

airControlBoostMultiplier?

optional airControlBoostMultiplier?: number;

Inherited from

CharacterMovementSettings.airControlBoostMultiplier

airControlBoostVelocityThreshold?

optional airControlBoostVelocityThreshold?: number;

Inherited from

CharacterMovementSettings.airControlBoostVelocityThreshold

alwaysCheckFloor?

optional alwaysCheckFloor?: boolean;

Inherited from

CharacterMovementSettings.alwaysCheckFloor

brakeToStopVelocity?

optional brakeToStopVelocity?: number;

Inherited from

CharacterMovementSettings.brakeToStopVelocity

brakingDecelerationFalling?

optional brakingDecelerationFalling?: number;

Inherited from

CharacterMovementSettings.brakingDecelerationFalling

brakingDecelerationWalking?

optional brakingDecelerationWalking?: number;

Inherited from

CharacterMovementSettings.brakingDecelerationWalking

brakingFriction?

optional brakingFriction?: number;

Inherited from

CharacterMovementSettings.brakingFriction

brakingFrictionFactor?

optional brakingFrictionFactor?: number;

Inherited from

CharacterMovementSettings.brakingFrictionFactor

brakingSubStepTime?

optional brakingSubStepTime?: number;

Inherited from

CharacterMovementSettings.brakingSubStepTime

canWalkOffLedges?

optional canWalkOffLedges?: boolean;

Inherited from

CharacterMovementSettings.canWalkOffLedges

canWalkOffLedgesWhenCrouching?

optional canWalkOffLedgesWhenCrouching?: boolean;

Inherited from

CharacterMovementSettings.canWalkOffLedgesWhenCrouching

capsuleHalfHeight?

optional capsuleHalfHeight?: number;

Inherited from

CharacterMovementSettings.capsuleHalfHeight

capsuleRadius?

optional capsuleRadius?: number;

Inherited from

CharacterMovementSettings.capsuleRadius

collision?

optional collision?: 
  | "none"
  | "overlap"
  | "block"
  | CollisionSetup
  | "NoCollision"
  | "BlockAll"
  | "OverlapAll"
  | "BlockAllDynamic"
  | "OverlapAllDynamic"
  | "IgnoreOnlyPawn"
  | "OverlapOnlyPawn"
  | "Pawn"
  | "Spectator"
  | "CharacterMesh"
  | "PhysicsActor"
  | "Destructible"
  | "InvisibleWall"
  | "InvisibleWallDynamic"
  | "Trigger"
  | "Ragdoll"
  | "Vehicle"
  | "UI";

dims?

optional dims?: readonly [number, number];

enablePhysicsInteraction?

optional enablePhysicsInteraction?: boolean;

Inherited from

CharacterMovementSettings.enablePhysicsInteraction

fallingLateralFriction?

optional fallingLateralFriction?: number;

Inherited from

CharacterMovementSettings.fallingLateralFriction

forceNextFloorCheck?

optional forceNextFloorCheck?: boolean;

Inherited from

CharacterMovementSettings.forceNextFloorCheck

gravity?

optional gravity?: number;

Inherited from

CharacterMovementSettings.gravity

gravityScale?

optional gravityScale?: number;

Inherited from

CharacterMovementSettings.gravityScale

groundFriction?

optional groundFriction?: number;

Inherited from

CharacterMovementSettings.groundFriction

initialPushForceFactor?

optional initialPushForceFactor?: number;

Inherited from

CharacterMovementSettings.initialPushForceFactor

jumpZVelocity?

optional jumpZVelocity?: number;

Inherited from

CharacterMovementSettings.jumpZVelocity

ledgeCheckThreshold?

optional ledgeCheckThreshold?: number;

Inherited from

CharacterMovementSettings.ledgeCheckThreshold

maintainHorizontalGroundVelocity?

optional maintainHorizontalGroundVelocity?: boolean;

Inherited from

CharacterMovementSettings.maintainHorizontalGroundVelocity

mass?

optional mass?: number;

Inherited from

CharacterMovementSettings.mass

maxAcceleration?

optional maxAcceleration?: number;

Inherited from

CharacterMovementSettings.maxAcceleration

maxDepenetrationWithGeometry?

optional maxDepenetrationWithGeometry?: number;

Inherited from

CharacterMovementSettings.maxDepenetrationWithGeometry

maxDepenetrationWithGeometryAsProxy?

optional maxDepenetrationWithGeometryAsProxy?: number;

Inherited from

CharacterMovementSettings.maxDepenetrationWithGeometryAsProxy

maxDepenetrationWithPawn?

optional maxDepenetrationWithPawn?: number;

Inherited from

CharacterMovementSettings.maxDepenetrationWithPawn

maxDepenetrationWithPawnAsProxy?

optional maxDepenetrationWithPawnAsProxy?: number;

Inherited from

CharacterMovementSettings.maxDepenetrationWithPawnAsProxy

maxFloorDist?

optional maxFloorDist?: number;

Inherited from

CharacterMovementSettings.maxFloorDist

maxSimulationIterations?

optional maxSimulationIterations?: number;

Inherited from

CharacterMovementSettings.maxSimulationIterations

maxSimulationTimeStep?

optional maxSimulationTimeStep?: number;

Inherited from

CharacterMovementSettings.maxSimulationTimeStep

maxStepHeight?

optional maxStepHeight?: number;

Inherited from

CharacterMovementSettings.maxStepHeight

maxStepSideZ?

optional maxStepSideZ?: number;

Inherited from

CharacterMovementSettings.maxStepSideZ

maxWalkSpeed?

optional maxWalkSpeed?: number;

Inherited from

CharacterMovementSettings.maxWalkSpeed

maxWalkSpeedCrouched?

optional maxWalkSpeedCrouched?: number;

Inherited from

CharacterMovementSettings.maxWalkSpeedCrouched

minAnalogWalkSpeed?

optional minAnalogWalkSpeed?: number;

Inherited from

CharacterMovementSettings.minAnalogWalkSpeed

minFloorDist?

optional minFloorDist?: number;

Inherited from

CharacterMovementSettings.minFloorDist

minTickTime?

optional minTickTime?: number;

Inherited from

CharacterMovementSettings.minTickTime

orientRotationToMovement?

optional orientRotationToMovement?: boolean;

penetrationOverlapCheckInflation?

optional penetrationOverlapCheckInflation?: number;

Inherited from

CharacterMovementSettings.penetrationOverlapCheckInflation

penetrationPullbackDistance?

optional penetrationPullbackDistance?: number;

Inherited from

CharacterMovementSettings.penetrationPullbackDistance

perchAdditionalHeight?

optional perchAdditionalHeight?: number;

Inherited from

CharacterMovementSettings.perchAdditionalHeight

perchRadiusThreshold?

optional perchRadiusThreshold?: number;

Inherited from

CharacterMovementSettings.perchRadiusThreshold

planeZ?

optional planeZ?: number;

Lock movement to this world Z plane.

pushForceFactor?

optional pushForceFactor?: number;

Inherited from

CharacterMovementSettings.pushForceFactor

repulsionForce?

optional repulsionForce?: number;

Inherited from

CharacterMovementSettings.repulsionForce

rotationRate?

optional rotationRate?: number;

standingDownwardForceScale?

optional standingDownwardForceScale?: number;

Inherited from

CharacterMovementSettings.standingDownwardForceScale

sweepEdgeRejectDistance?

optional sweepEdgeRejectDistance?: number;

Inherited from

CharacterMovementSettings.sweepEdgeRejectDistance

terminalVelocity?

optional terminalVelocity?: number;

Inherited from

CharacterMovementSettings.terminalVelocity

useFlatBaseForFloorChecks?

optional useFlatBaseForFloorChecks?: boolean;

Inherited from

CharacterMovementSettings.useFlatBaseForFloorChecks

useRVOAvoidance?

optional useRVOAvoidance?: boolean;

Inherited from

CharacterMovementSettings.useRVOAvoidance

useSeparateBrakingFriction?

optional useSeparateBrakingFriction?: boolean;

Inherited from

CharacterMovementSettings.useSeparateBrakingFriction

verticalSlopeNormalZ?

optional verticalSlopeNormalZ?: number;

Inherited from

CharacterMovementSettings.verticalSlopeNormalZ

walkableFloorAngle?

optional walkableFloorAngle?: number;

Inherited from

CharacterMovementSettings.walkableFloorAngle

walkableFloorZ?

optional walkableFloorZ?: number;

Inherited from

CharacterMovementSettings.walkableFloorZ

CharacterMovementSettings

Metre-based movement settings. Gravity and terminal speed are port/world inputs.

Example

const settings: Partial<CharacterMovementSettings> = { maxWalkSpeed: 4 };

Properties

airControl

airControl: number;

airControlBoostMultiplier

airControlBoostMultiplier: number;

airControlBoostVelocityThreshold

airControlBoostVelocityThreshold: number;

alwaysCheckFloor

alwaysCheckFloor: boolean;

brakeToStopVelocity

brakeToStopVelocity: number;

brakingDecelerationFalling

brakingDecelerationFalling: number;

brakingDecelerationWalking

brakingDecelerationWalking: number;

brakingFriction

brakingFriction: number;

brakingFrictionFactor

brakingFrictionFactor: number;

brakingSubStepTime

brakingSubStepTime: number;

canWalkOffLedges

canWalkOffLedges: boolean;

canWalkOffLedgesWhenCrouching

canWalkOffLedgesWhenCrouching: boolean;

capsuleHalfHeight

capsuleHalfHeight: number;

capsuleRadius

capsuleRadius: number;

enablePhysicsInteraction

enablePhysicsInteraction: boolean;

fallingLateralFriction

fallingLateralFriction: number;

forceNextFloorCheck

forceNextFloorCheck: boolean;

gravity

gravity: number;

gravityScale

gravityScale: number;

groundFriction

groundFriction: number;

initialPushForceFactor

initialPushForceFactor: number;

jumpZVelocity

jumpZVelocity: number;

ledgeCheckThreshold

ledgeCheckThreshold: number;

maintainHorizontalGroundVelocity

maintainHorizontalGroundVelocity: boolean;

mass

mass: number;

maxAcceleration

maxAcceleration: number;

maxDepenetrationWithGeometry

maxDepenetrationWithGeometry: number;

maxDepenetrationWithGeometryAsProxy

maxDepenetrationWithGeometryAsProxy: number;

maxDepenetrationWithPawn

maxDepenetrationWithPawn: number;

maxDepenetrationWithPawnAsProxy

maxDepenetrationWithPawnAsProxy: number;

maxFloorDist

maxFloorDist: number;

maxSimulationIterations

maxSimulationIterations: number;

maxSimulationTimeStep

maxSimulationTimeStep: number;

maxStepHeight

maxStepHeight: number;

maxStepSideZ

maxStepSideZ: number;

maxWalkSpeed

maxWalkSpeed: number;

maxWalkSpeedCrouched

maxWalkSpeedCrouched: number;

minAnalogWalkSpeed

minAnalogWalkSpeed: number;

minFloorDist

minFloorDist: number;

minTickTime

minTickTime: number;

penetrationOverlapCheckInflation

penetrationOverlapCheckInflation: number;

penetrationPullbackDistance

penetrationPullbackDistance: number;

perchAdditionalHeight

perchAdditionalHeight: number;

perchRadiusThreshold

perchRadiusThreshold: number;

pushForceFactor

pushForceFactor: number;

repulsionForce

repulsionForce: number;

standingDownwardForceScale

standingDownwardForceScale: number;

sweepEdgeRejectDistance

sweepEdgeRejectDistance: number;

terminalVelocity

terminalVelocity: number;

useFlatBaseForFloorChecks

useFlatBaseForFloorChecks: boolean;

useRVOAvoidance

useRVOAvoidance: boolean;

useSeparateBrakingFriction

useSeparateBrakingFriction: boolean;

verticalSlopeNormalZ

verticalSlopeNormalZ: number;

walkableFloorAngle

walkableFloorAngle: number;

walkableFloorZ

walkableFloorZ: number;

CharacterReadyEvent

A character bundle finished loading and reported its expression space.

Properties

bundle

bundle: number;

entity

entity: number;

expressionDim

expressionDim: number;

space

space: ExpressionSpace;

CharactersOptions

Options for the characters feature.

Properties

motion?

optional motion?: 
  | false
  | {
  actions?: boolean;
  carry?: boolean;
  feet?: "own" | "performed";
  footPlant?: boolean;
  legs?: "performed" | "bent";
  naturalness?: number;
  responsiveness?: number;
  set?: string;
  stand?: "middle" | "sole" | "bearing";
  standing?: "set" | "own";
  turn?: "easy" | "quick";
};

The movement system (exported characters moved by whole takes of a performer, their feet held where they land): on by default. false turns it off for the game: every character walks by the clips' blend, as before. An object keeps it on and sets how it moves every character: whether the take carries the walker (carry, default true), and the two dials, each 0 to 1, default 0.6 (responsiveness: how hard a character follows what is asked; naturalness: how far it may leave its place to move as the take does), what it stands on at rest (standing: 'own', the character's own captured stance, the default; 'set', the takes' own standing) and whether the feet are held (footPlant).

Union Members

false

Type Literal

{
  actions?: boolean;
  carry?: boolean;
  feet?: "own" | "performed";
  footPlant?: boolean;
  legs?: "performed" | "bent";
  naturalness?: number;
  responsiveness?: number;
  set?: string;
  stand?: "middle" | "sole" | "bearing";
  standing?: "set" | "own";
  turn?: "easy" | "quick";
}

actions?

optional actions?: boolean;

Actions of the character's set (a hurdle, a jump: character.do). Off by default: the default is standing, walking, running, starts, stops, turns and the foot hold.

carry?

optional carry?: boolean;

feet?

optional feet?: "own" | "performed";

How a move's ankle and toe turns are laid on a character's feet: 'performed' (the default: the performer's joint turns as they stand) or 'own' (laid on the character's own stand's sole, so a character made on a raised heel or in a shoe rolls over its own sole as the performer does over his). Left out, nothing changes.

footPlant?

optional footPlant?: boolean;

legs?

optional legs?: "performed" | "bent";

How straight a leg the foot hold moves may be: 'bent' (the default: never over 0.995 of its length, which dips the hips about 4 mm once a walking step) or 'performed' (as straight as the move has the leg, and no straighter). Left out, nothing changes.

naturalness?

optional naturalness?: number;

responsiveness?

optional responsiveness?: number;

set?

optional set?: string;

The set every character starts on: 'shared' (the engine's shared set alone: a character's own takes are not laid over it), 'own', or a name the page gave a set. Absent: a character's own takes laid over the shared set, part by part.

stand?

optional stand?: "middle" | "sole" | "bearing";

How a walk is stood on the floor: 'middle' (the default: by the middle of the joints of the feet marked down), 'sole' (on the character's own lowest sole point of those feet) or 'bearing' (on her lowest sole point, the toe's end too, of every foot from the frame its sole is down to the frame its toes leave). Only the height the hips are drawn at changes; left out, nothing does.

standing?

optional standing?: "set" | "own";

turn?

optional turn?: "easy" | "quick";

The pace of a turn on the spot, where the set marks its turns by pace: 'quick' (the default) or 'easy' (unhurried: a character in a room).

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.

ChaseOptions

Pursuit prediction in seconds/metres. A ram lasts 0.5 seconds; cooldown starts at its onset.

Example

chaseVehicle(ctx, ai, suspect, { leadTime: 0.5, ramCooldown: 4 });

Extends

DriveOptions

Properties

acceptanceRadius?

optional acceptanceRadius?: number;

Inherited from

DriveOptions.acceptanceRadius

leadTime?

optional leadTime?: number;

maxLead?

optional maxLead?: number;

ramCooldown?

optional ramCooldown?: number;

ramDistance?

optional ramDistance?: number;

speed?

optional speed?: number;

Inherited from

DriveOptions.speed

stopAtTarget?

optional stopAtTarget?: boolean;

Inherited from

DriveOptions.stopAtTarget

tuning?

optional tuning?: Partial<DriveTuning>;

Inherited from

DriveOptions.tuning

CheckpointModuleOptions

Negative-Z checkpoint thresholds and fall recovery.

Example

import type { CheckpointModuleOptions } from 'gameable';
const options: CheckpointModuleOptions = { axis: 'z', direction: 'decreasing', thresholds: [-22], points: [[0,3,-23]], spawns: [[0,3,0]], maxAbsX: 4, minY: 2, fallY: -5, lobbyRespawn: 'seat-start', resetKnock: true };
console.log(options.thresholds);

Properties

axis

axis: "z";

direction

direction: "decreasing";

fallY

fallY: number;

lobbyRespawn

lobbyRespawn: "seat-start";

maxAbsX

maxAbsX: number;

minY

minY: number;

points

points: readonly readonly number[][];

resetKnock

resetKnock: boolean;

spawns

spawns: readonly readonly number[][];

thresholds

thresholds: readonly number[];

CheckpointProps

Ordered checkpoint data; a higher order never regresses to a lower checkpoint.

Example

const props: Partial<CheckpointProps> = {order: 1, once: true};

Properties

forwardOnly

forwardOnly: boolean;

mode

mode: "ordered" | "lap";

once

once: boolean;

order

order: number;

raceId

raceId: string;

respawnOffset

respawnOffset: [number, number, number];

CircuitGate

Gate plane faces local +Z; angles are radians, extents are half sizes.

Example

const gate: CircuitGate = { position: [0,0,10], yaw: 0, halfExtents: [3,2,1] };

Properties

forwardOnly?

optional forwardOnly?: boolean;

Accept reverse crossings too when false; defaults to true.

halfExtents

halfExtents: CircuitPoint;

position

position: CircuitPoint;

respawnOffset?

optional respawnOffset?: CircuitPoint;

Local safe-pose offset; defaults to [0, 1, -1].

yaw

yaw: number;

CircuitOptions

Circuit configuration; array order is dense gate order, with gate zero the start.

Example

const options: CircuitOptions = {id:'race',laps:3,maxRacers:8,gates:[{position:[0,0,0],yaw:0,halfExtents:[3,2,1]},{position:[0,0,20],yaw:0,halfExtents:[3,2,1]}]};

Properties

gates

gates: readonly (string | CircuitGate)[];

Named box actors resolve once at init; explicit gates can be used without actors.

id

id: string;

laps

laps: number;

line?

optional line?: 
  | {
  actor: string;
  component: string;
}
  | readonly readonly CircuitPoint[][];

One authored polyline per gate-to-next-gate section, or a named spline sampled at init.

maxRacers

maxRacers: number;

onRespawn?

optional onRespawn?: (ctx, racer) => void;

Runs after pawn respawn; vehicle adapters can clear their simulation here.

Parameters

Parameter	Type
`ctx`	`GameContext`
`racer`	`Readonly`<`RaceProgress`>

Returns

void

racerRadius?

optional racerRadius?: number;

Occupancy sphere radius in metres; defaults to 0.5.

resetOnDisconnect?

optional resetOnDisconnect?: boolean;

CircuitRace

Circuit lifecycle and borrowed standings. Teleport adapters must call markTeleported before the next system.

Example

const configure = (o: CircuitOptions): CircuitRace => createCircuitRace(o);

Properties

standings

readonly standings: readonly Readonly<RaceProgress>[];

Methods

bindEntity()

bindEntity(racer, entity): void;

Parameters

Parameter	Type
`racer`	`number`
`entity`	`number`

Returns

void

crossGate()

crossGate(
   ctx, 
   racer, 
   gate, 
   fraction
): boolean;

Internal adapter entry: must supply a genuine forward crossing, in global fraction/id order.

Parameters

Parameter	Type
`ctx`	`GameContext`
`racer`	`number`
`gate`	`number`
`fraction`	`number`

Returns

boolean

disconnect()

disconnect(racer): void;

Parameters

Parameter	Type
`racer`	`number`

Returns

void

init()

init(ctx): void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

markTeleported()

markTeleported(racer): void;

Parameters

Parameter	Type
`racer`	`number`

Returns

void

progress()

progress(racer): Readonly<RaceProgress> | undefined;

Parameters

Parameter	Type
`racer`	`number`

Returns

Readonly<RaceProgress> | undefined

register()

register(ctx, racer): RaceProgress;

Parameters

Parameter	Type
`ctx`	`GameContext`
`racer`	`CircuitRacer`

Returns

RaceProgress

reset()

reset(): void;

Returns

void

respawn()

respawn(ctx, racer): boolean;

Respawn at the last accepted gate. Returns false and retries every 0.25s while occupied.

Parameters

Parameter	Type
`ctx`	`GameContext`
`racer`	`number`

Returns

boolean

restore()

restore(state): void;

Parameters

Parameter	Type
`state`	`unknown`

Returns

void

snapshot()

snapshot(): unknown;

Returns

unknown

spectate()

spectate(racer, value): void;

Parameters

Parameter	Type
`racer`	`number`
`value`	`boolean`

Returns

void

system()

system(ctx): void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

unregister()

unregister(racer): void;

Parameters

Parameter	Type
`racer`	`number`

Returns

void

CircuitRacer

Stable identity registration. Reuse the racer id only for the same person; unregister on seat reuse.

Example

const racer: CircuitRacer = {racer:42,seat:0,entity:12};

Extended by

RaceProgress

Properties

entity

entity: number;

racer

racer: number;

seat

seat: number | null;

CircuitStandings

Full circuit HUD publication. Revision advances only when a public row changes.

Example

const show = (state: CircuitStandings) => console.log(state.revision, state.rows);

Properties

revision

readonly revision: number;

rows

readonly rows: readonly Readonly<Omit<RaceProgress, "respawnPose">>[];

CollisionCell

Solid grid cell, with height measured from ground y=0 in metres.

Example

const cell: CollisionCell = { x: 0, z: 0, height: 2 };

Properties

height

height: number;

x

x: number;

z

z: number;

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;

CollisionSetup

Complete per-component collision policy.

Example

const setup: CollisionSetup = { objectType: 'pawn', enabled: 'query', responses: { default: 'block' } };

Properties

enabled

enabled: CollisionEnabled;

objectType

objectType: CollisionChannel;

responses

responses: CollisionResponses;

CollisionShapeSetup

Shape routing keeps the simple aggregate separate from triangle geometry.

Example

const setup: CollisionShapeSetup<string> = { simple: 'capsule', complex: 'triangles', collisionTraceFlag: 'simpleAndComplex' };

Type Parameters

Type Parameter
`T`

Properties

collisionTraceFlag

collisionTraceFlag: CollisionTraceFlag;

complex

complex: T;

defaultFlag?

optional defaultFlag?: "simpleAndComplex" | "simpleAsComplex" | "complexAsSimple";

Required for useDefault; must be a resolved project choice.

simple

simple: T;

traceComplex?

optional traceComplex?: boolean;

Request complex geometry for this query. Default false.

ComponentCatalog

Versioned component factory descriptions in registration order.

Example

const catalog: ComponentCatalog = componentCatalog();

Properties

catalogVersion

catalogVersion: 1;

components

components: ComponentCatalogEntry[];

ComponentCatalogEntry

JSON-safe metadata for a reusable component factory. Callback parameters are listed as events.

Example

const entry: ComponentCatalogEntry = { name: 'scene', description: 'Transform.', options: {} };

Properties

description

description: string;

events?

optional events?: readonly object[];

name

name: string;

options

options: Record<string, PropMeta>;

ComponentOptions

Options common to scene components.

Example

const options: ComponentOptions = { attach: 'root' };

Extends

AttachmentOptions

Properties

attach?

optional attach?: string;

Parent component name; defaults to root for non-root components.

offset?

optional offset?: readonly [number, number, number];

Translation in the parent's space.

Inherited from

AttachmentOptions.offset

rotation?

optional rotation?: Quat;

Local quaternion, default identity.

Inherited from

AttachmentOptions.rotation

scale?

optional scale?: readonly [number, number, number];

Local per-axis scale, default one.

Inherited from

AttachmentOptions.scale

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;

overlap?

optional overlap?: boolean;

True for a mixed-profile companion overlap.

phase

phase: ContactPhase;

point

point: Vec3;

ConversationCmd

Structural interview controls; service addresses stay in host configuration.

Properties

action

action: 
  | "start"
  | "end"
  | "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: "input" | "error" | "status" | "subtitle" | "story";

text

text: string;

Story events carry the versioned full snapshot as JSON.

ConversationStory

A talking character's story as the game reads it: the conversation service's snapshot after a turn, sent as the text of a story conversation event. The service judges the objectives and player state; the game decides what they mean (a permission, a refusal, a clue) and owns every outcome.

Properties

completedObjectives

completedObjectives: string[];

Objective ids the service judged complete.

currentPhase

currentPhase: string;

The story phase now.

playerState

playerState: Record<string, string>;

What the service judged about the player (player_state objectives), as plain strings.

revision

revision: number;

Rises with every snapshot of a session; an older one than the last read is stale.

transitionCause

transitionCause: string;

Why the phase last changed, as the service put it.

Crowd

A fixed-capacity crowd. Live slots are visited in ascending order; removing an agent leaves a hole, reused by the next add. Queries write caller-owned storage.

Example

import { createCrowd, createNavGrid, type Crowd } from 'gameable';
const nav = createNavGrid({ min: [-10, -10], max: [10, 10] });
nav.buildFlat();
const crowd: Crowd = createCrowd(nav);
crowd.add(1);
crowd.moveTo(1, 5, 5);
crowd.step(1 / 60);

Properties

count

readonly count: number;

Number of live agents.

Methods

add()

add(entity, options?): boolean;

Add an entity with optional agent tuning.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.
`options?`	`CrowdAgentOptions`	Agent tuning.

Returns

boolean

False if full, invalid or present.

follow()

follow(entity, field): void;

Follow a shared navigation field.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.
`field`	`FlowField`	Shared navigation field.

Returns

void

Nothing.

has()

has(entity): boolean;

Check whether an entity belongs to this crowd.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.

Returns

boolean

Whether it belongs to this crowd.

moveTo()

moveTo(
   entity, 
   x, 
   z
): boolean;

Plan a path towards a goal.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.
`x`	`number`	Goal x.
`z`	`number`	Goal z.

Returns

boolean

Whether a path exists.

position()

position(entity, out): boolean;

Read an agent's simulated position.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.
`out`	`NavPoint`	Position destination.

Returns

boolean

Whether found.

remove()

remove(entity): void;

Remove an entity from the crowd.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity to remove.

Returns

void

Nothing.

setPosition()

setPosition(
   entity, 
   x, 
   z
): void;

Set an agent's simulated position.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.
`x`	`number`	World x.
`z`	`number`	World z.

Returns

void

Nothing.

state()

state(entity): AgentState;

Read an agent's current state.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.

Returns

AgentState

Current state, or Idle for unknown entities.

step()

step(dt): void;

Advance the crowd simulation.

Parameters

Parameter	Type	Description
`dt`	`number`	Elapsed seconds; nonpositive values do nothing.

Returns

void

Nothing.

stop()

stop(entity): void;

Stop an agent and let it decelerate.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.

Returns

void

Nothing; becomes Idle and decelerates.

update()

update(ctx): void;

Read transforms and apply movement and facing.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Frame context; reads Transform and applies velocity and facing.

Returns

void

Nothing.

velocity()

velocity(entity, out): boolean;

Read an agent's simulated velocity.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity id.
`out`	`NavPoint`	Velocity destination.

Returns

boolean

Whether found.

CrowdAgentOptions

Per-agent tuning.

Properties

arriveDistance?

readonly optional arriveDistance?: number;

Distance at which the goal counts as reached. Default 0.3.

maxAccel?

readonly optional maxAccel?: number;

Metres per second squared. Default 20.

maxSpeed?

readonly optional maxSpeed?: number;

Metres per second. Default 3.5.

radius?

readonly optional radius?: number;

Default: the nav's agentRadius.

CrowdOptions

Crowd-wide tuning.

Properties

face?

readonly optional face?: boolean;

Turn each moving agent to face where it walks (faceToward). Default true.

maxAgents?

readonly optional maxAgents?: number;

Most agents at once. Default 128.

maxPathPoints?

readonly optional maxPathPoints?: number;

Most points one agent's path holds. Default 64.

move?

readonly optional move?: CrowdMove;

character: physics.moveCharacter. velocity: the guest-integrated Velocity. Default character.

neighbourRadius?

readonly optional neighbourRadius?: number;

How far an agent looks for others to avoid. Default 3.

timeHorizon?

readonly optional timeHorizon?: number;

Seconds ahead an agent predicts collisions. Default 2.

CursorHit

Caller-owned cursor query result; allocate once and reuse.

Example

const hit: CursorHit = { point: { x: 0, y: 0, z: 0 }, normal: { x: 0, y: 1, z: 0 }, entity: 0, distance: 0 };

Properties

distance

distance: number;

entity

entity: number;

normal

normal: Vec3;

point

point: Vec3;

CutsceneCmd

A cutscene: a clip the page draws over the stage at a moment that matters. preload fetches it ahead so play starts at once; skip ends the one playing. The clip is a video asset of the manifest, never a URL.

Properties

action

action: "preload" | "play" | "skip";

asset

asset: number;

The video asset; 0 for skip.

fadeInMs

fadeInMs: number;

Milliseconds of fade in over the stage.

fadeOutMs

fadeOutMs: number;

Milliseconds of fade out.

pause

pause: boolean;

The stage pauses under it and the game's sound is ducked.

skippable

skippable: boolean;

A tap or a key ends it early.

CutsceneEvent

How a cutscene ended.

Properties

asset

asset: number;

The video asset that was played.

kind

kind: "ended" | "skipped" | "failed";

The clip reached its end, the person skipped it, or it could not play.

seconds

seconds: number;

Seconds from the call to the end, fades included.

CutscenePlayOptions

Options for cutscene.play.

Properties

fadeIn?

optional fadeIn?: number;

Fade in over the stage, milliseconds. Default 400.

fadeOut?

optional fadeOut?: number;

Fade out, milliseconds. Default 400.

pause?

optional pause?: boolean;

Pause the stage under it and duck the game's sound. Default true.

skippable?

optional skippable?: boolean;

A tap or a key ends it early. Default true.

Damage

Health operations and fixed-step invulnerability. Write Health through this part: step does not infer deaths from external writes. Positive hp clears stale death flags. Snapshot contains only sparse [entity, dead, iframes] rows; the engine saves Health.

Example

import { createDamage, defineGame, type Damage } from 'gameable';
const hits: Damage = createDamage();
hits.reset();
export default defineGame({ systems: [ctx => { hits.fraction(ctx, 0); }] });

Extends

GameplayPart

Methods

damage()

damage(
   ctx, 
   entity, 
   amount, 
   source?
): number;

Remove hp; onDamage precedes onDeath synchronously for this entity.

Parameters

Parameter	Type
`ctx`	`GameContext`
`entity`	`number`
`amount`	`number`
`source?`	`number`

Returns

number

forget()

forget(entity): void;

Clear the death flag and i-frames; call when you despawn an entity.

Parameters

Parameter	Type
`entity`	`number`

Returns

void

fraction()

fraction(ctx, entity): number;

Current / max clamped to [0, 1], or zero outside the entity range, without Health in ctx.world, or without positive maximum health.

Parameters

Parameter	Type
`ctx`	`GameContext`
`entity`	`number`

Returns

number

heal()

heal(
   ctx, 
   entity, 
   amount
): number;

Restore living hp, capped at max; onHeal receives the actual amount.

Parameters

Parameter	Type
`ctx`	`GameContext`
`entity`	`number`
`amount`	`number`

Returns

number

isDead()

isDead(entity): boolean;

Read the death flag while current hp is nonpositive; clear stale flags and i-frames.

Parameters

Parameter	Type
`entity`	`number`

Returns

boolean

isInvulnerable()

isInvulnerable(entity): boolean;

Whether any i-frames remain.

Parameters

Parameter	Type
`entity`	`number`

Returns

boolean

kill()

kill(
   ctx, 
   entity, 
   source?
): void;

Kill regardless of i-frames; onDamage precedes onDeath when hp was removed.

Parameters

Parameter	Type
`ctx`	`GameContext`
`entity`	`number`
`source?`	`number`

Returns

void

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

Inherited from

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

revive()

revive(
   ctx, 
   entity, 
   hpFraction?
): void;

Revive a flagged death, clamping fraction to [1 hp, max]; fires onRevive.

Parameters

Parameter	Type
`ctx`	`GameContext`
`entity`	`number`
`hpFraction?`	`number`

Returns

void

setInvulnerable()

setInvulnerable(
   ctx, 
   entity, 
   seconds
): void;

Replace i-frames; nonpositive seconds clears them.

Parameters

Parameter	Type
`ctx`	`GameContext`
`entity`	`number`
`seconds`	`number`

Returns

void

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

InteractableProps.action

step()

step(ctx): void;

Count down i-frames in ascending entity order; does not infer deaths.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

DamageInfo

Attribution attached to a damage operation.

Example

const info: DamageInfo = { type: 'fire' };

Properties

causer?

optional causer?: ActorHandle<object>;

Actor directly causing the damage.

instigator?

optional instigator?: ActorHandle<object>;

Actor responsible for the damage.

type?

optional type?: string;

Game-defined damage category.

DataFacade

The ctx.data facade, one per guest. Only the authority writes: on a client every call is a no-op (logged once).

Saving is not free: save serialises the document. Call it when the document changed, not every tick; the room writes at most one per player every 6 s anyway, and always when the player leaves or the room closes.

Example

function earn(ctx: GameContext): void {
  for (const [id, p] of ctx.players) {
    const doc = (p.data ?? { coins: 0 }) as { coins: number };
    if (ctx.frame % 600 === 0) ctx.data.save(id, { ...doc, coins: doc.coins + 1 });
  }
  for (const r of ctx.data.results()) if (!r.ok) ctx.net.send('trade-failed', { id: r.id, why: r.reason });
}

Accessors

game

Get Signature

get game(): unknown;

Returns

unknown

The game's own saved document, once the room has handed it over; else null.

Methods

exchange()

exchange(
   a, 
   b, 
   give, 
   take
): number;

Trade between two players, all or nothing: a gives b everything in give and takes from b everything in take (numbers move amounts, lists move items; see applyTransfer). The result arrives as an exchange-result event a tick or more later, in DataFacade.results; on success both players' data already show the trade.

Parameters

Parameter	Type	Description
`a`	`number`	The first player.
`b`	`number`	The second player.
`give`	`TransferDoc`	What a gives b, such as `{ coins: 5 }`.
`take`	`TransferDoc`	What a takes from b, such as `{ owned: ['gem'] }`.

Returns

number

The exchange's id, or 0 on a client.

results()

results(): readonly Pick<ExchangeResultEvent, "id" | "ok" | "reason">[];

Returns

readonly Pick<ExchangeResultEvent, "id" | "ok" | "reason">[]

This tick's exchange results, in arrival order; reused, read during the tick.

save()

save(player, doc): void;

Keep a player's document. ctx.players.get(player).data is the new document at once; the room writes it to its store (throttled).

Parameters

Parameter	Type	Description
`player`	`number`	A joined player.
`doc`	`unknown`	Any JSON value; at most 64 KB as JSON.

Returns

void

saveGame()

saveGame(doc): void;

Keep the game's own document (one per game, shared by every room).

Parameters

Parameter	Type	Description
`doc`	`unknown`	Any JSON value; at most 64 KB as JSON.

Returns

void

DataFieldSchema

One content field's authoring constraints. Bounds on vec3 apply to each component.

Example

const field: DataFieldSchema = { type: 'number', min: 0, description: 'Health.' };

Properties

description

description: string;

max?

optional max?: number;

min?

optional min?: number;

type

type: "string" | "number" | "boolean" | "vec3" | "enum" | "tableRef";

values?

optional values?: readonly string[];

DataRowHandle

A JSON-safe reference, suitable for level props and saved games.

Example

const handle: DataRowHandle = { table: 'Items', key: 'potion' };

Properties

key

readonly key: string;

table

readonly table: string;

DataTable

Immutable named rows. Missing rows return undefined; find returns the first match. Curves use finite numeric keys and finite numeric field values, with endpoint clamping. Lookup, search, weighted selection and curve sampling allocate no storage per call.

Example

const items: DataTable<{ cost: number }> = defineDataTable('Items', {
  description: 'Shop.', rows: { potion: { cost: 5 } },
});
const cost = items.get('potion')?.cost;

Type Parameters

Type Parameter
`Row` extends `object`

Properties

name

readonly name: string;

size

readonly size: number;

Methods

curve()

curve(field, x): number;

Equal numeric coordinates use the last row in key order.

Parameters

Parameter	Type
`field`	keyof `Row` & `string`
`x`	`number`

Returns

number

find()

find(predicate): FrozenData<Row> | undefined;

Parameters

Parameter	Type
`predicate`	(`row`, `key`) => `boolean`

Returns

FrozenData<Row> | undefined

get()

get(key): FrozenData<Row> | undefined;

Parameters

Parameter	Type
`key`	`string`

Returns

FrozenData<Row> | undefined

has()

has(key): boolean;

Parameters

Parameter	Type
`key`	`string`

Returns

boolean

keys()

keys(): readonly string[];

Returns

readonly string[]

pickWeighted()

pickWeighted(rng, weightField): FrozenData<Row>;

Nonnegative finite weights are required; empty/all-zero tables throw.

Parameters

Parameter	Type
`rng`	`Rng`
`weightField`	keyof `Row` & `string`

Returns

FrozenData<Row>

DataTableCatalogEntry

A detached catalog entry for content authoring tools.

Example

const entries: DataTableCatalogEntry[] = describeDataTables();

Properties

description

description: string;

name

name: string;

rowKeys

rowKeys: string[];

schema

schema: DataSchema;

DoCharacterActionCmd

Ask a character to do an action of its motion set (see character.do).

Properties

action

action: string;

The action's name in the set.

entity

entity: number;

object?

optional object?: ActionObject;

plain

plain: boolean;

The plain way, for a comparison: the take simply started, nothing fitted.

DoorCoreProps

Shared authored door properties.

Example

const props: Partial<DoorCoreProps> = { lockedBy: 'key' };

Extends

InteractableProps

Extended by

HingedDoorProps
SlidingDoorProps
DoubleDoorProps
GateProps
TrapDoorProps

Properties

action

action: string;

Inherited from

asset?

optional asset?: string;

Inherited from

InteractableProps.asset

autoCloseSeconds

autoCloseSeconds: number;

closePrompt

closePrompt: string;

closeSound

closeSound: string;

colour

colour: [number, number, number];

consumeKey

consumeKey: boolean;

enabled

enabled: boolean;

Inherited from

InteractableProps.enabled

facingDegrees

facingDegrees: number;

Inherited from

InteractableProps.facingDegrees

height

height: number;

Closed doorway height in metres.

lockedBy

lockedBy: string;

lockedMessage

lockedMessage: string;

lockedPrompt

lockedPrompt: string;

lockedSound

lockedSound: string;

look

look: "none" | "wood" | "metal";

once

once: boolean;

Inherited from

InteractableProps.once

openPrompt

openPrompt: string;

openSound

openSound: string;

opensWhen

opensWhen: string[];

prompt

prompt: string;

Inherited from

InteractableProps.prompt

range

range: number;

Inherited from

InteractableProps.range

seconds

seconds: number;

startOpen

startOpen: boolean;

stayOpen

stayOpen: boolean;

thickness

thickness: number;

Leaf thickness in metres.

toggledBy

toggledBy: "proximity" | "interact" | "signal";

width

width: number;

Closed doorway width in metres.

DoorProps

Sliding or yaw-rotating door data. Offset is world-relative to the closed spawn transform; a nonzero openYaw selects rotation instead.

Example

const props: Partial<DoorProps> = {openOffset: [2,0,0], lockedBy: 'key', consumeKey: true};

Extends

InteractableProps

Properties

action

action: string;

Inherited from

InteractableProps.action

asset?

optional asset?: string;

Inherited from

InteractableProps.asset

autoCloseSeconds

autoCloseSeconds: number;

consumeKey

consumeKey: boolean;

enabled

enabled: boolean;

Inherited from

InteractableProps.enabled

facingDegrees

facingDegrees: number;

Inherited from

InteractableProps.facingDegrees

lockedBy

lockedBy: string;

once

once: boolean;

Inherited from

InteractableProps.once

openOffset

openOffset: [number, number, number];

openYaw

openYaw: number;

prompt

prompt: string;

Inherited from

InteractableProps.prompt

range

range: number;

Inherited from

InteractableProps.range

seconds

seconds: number;

startOpen

startOpen: boolean;

DoorStatus

Borrowed door status.

Example

console.log(doorState(door).phase);

Properties

fraction

readonly fraction: number;

locked

readonly locked: boolean;

phase

readonly phase: "open" | "closed" | "opening" | "closing";

DoubleDoorProps

Double leaf tuning; width measures the entire doorway.

Example

const props: Partial<DoubleDoorProps> = { swingDegrees: 90 };

Extends

DoorCoreProps

Properties

action

action: string;

Inherited from

asset?

optional asset?: string;

Inherited from

autoCloseSeconds

autoCloseSeconds: number;

Inherited from

closePrompt

closePrompt: string;

Inherited from

closeSound

closeSound: string;

Inherited from

colour

colour: [number, number, number];

Inherited from

consumeKey

consumeKey: boolean;

Inherited from

enabled

enabled: boolean;

Inherited from

facingDegrees

facingDegrees: number;

Inherited from

height

height: number;

Closed doorway height in metres.

Inherited from

lockedBy

lockedBy: string;

Inherited from

lockedMessage

lockedMessage: string;

Inherited from

lockedPrompt

lockedPrompt: string;

Inherited from

lockedSound

lockedSound: string;

Inherited from

look

look: "none" | "wood" | "metal";

Inherited from

once

once: boolean;

Inherited from

openPrompt

openPrompt: string;

Inherited from

openSound

openSound: string;

Inherited from

opensWhen

opensWhen: string[];

Inherited from

prompt

prompt: string;

Inherited from

range

range: number;

Inherited from

seconds

seconds: number;

Inherited from

startOpen

startOpen: boolean;

Inherited from

stayOpen

stayOpen: boolean;

Inherited from

swingAway

swingAway: boolean;

swingDegrees

swingDegrees: number;

thickness

thickness: number;

Leaf thickness in metres.

Inherited from

toggledBy

toggledBy: "proximity" | "interact" | "signal";

Inherited from

width

width: number;

Closed doorway width in metres.

Inherited from

DriveTuning.brakeGain

DriveOptions

Shared request options; speeds are metres/second and distances metres.

Example

driveTowards(ctx, ai, point, { speed: 15, tuning: { maxSpeed: 20 } });

Extended by

RacingLineOptions
ChaseOptions

Properties

acceptanceRadius?

optional acceptanceRadius?: number;

speed?

optional speed?: number;

stopAtTarget?

optional stopAtTarget?: boolean;

tuning?

optional tuning?: Partial<DriveTuning>;

DriveSettings

Pure driver settings; negative speed requests reverse travel.

Example

const settings: DriveSettings = { ...defaultDriveTuning, speed: 12, acceptanceRadius: 1, stopAtTarget: true };

Extends

DriveTuning

Properties

acceptanceRadius

acceptanceRadius: number;

brakeGain

brakeGain: number;

Inherited from

lookAheadMin

lookAheadMin: number;

Inherited from

DriveTuning.lookAheadMin

lookAheadTime

lookAheadTime: number;

Inherited from

DriveTuning.lookAheadTime

maxSpeed

maxSpeed: number;

Inherited from

DriveTuning.maxSpeed

reverseSeconds

reverseSeconds: number;

Inherited from

DriveTuning.reverseSeconds

speed

speed: number;

speedGain

speedGain: number;

Inherited from

DriveTuning.speedGain

steerGain

steerGain: number;

Inherited from

DriveTuning.steerGain

stopAtTarget

stopAtTarget: boolean;

stuckSeconds

stuckSeconds: number;

Inherited from

DriveTuning.stuckSeconds

DriveState

Borrowed chassis pose and signed longitudinal speed.

Example

const state: DriveState = { position: car.position, yaw: 0, speed: 0 };

Properties

position

position: Vec3;

speed

speed: number;

yaw

yaw: number;

DriveTuning

Driving gains in SI units; steerGain converts pursuit curvature to normalized steer.

Example

const tuning: DriveTuning = { ...defaultDriveTuning, maxSpeed: 20 };

Extended by

DriveSettings

Properties

brakeGain

brakeGain: number;

lookAheadMin

lookAheadMin: number;

lookAheadTime

lookAheadTime: number;

maxSpeed

maxSpeed: number;

reverseSeconds

reverseSeconds: number;

speedGain

speedGain: number;

steerGain

steerGain: number;

stuckSeconds

stuckSeconds: number;

EffectCmd

Particle command payload, copied into a pool by the SDK.

Example

import type { EffectCmd } from 'gameable';
const command: EffectCmd = {
  action: 'play', effect: 0, preset: 'dust', position: { x: 0, y: 0, z: 0 },
  direction: { x: 0, y: 0, z: 0 }, scale: 1, intensity: 1,
};

Properties

action

action: EffectAction;

direction

direction: Vec3;

Emission direction (a surface normal for sparks); zero is the preset's own.

effect

effect: number;

Guest-minted handle; 0 is a one-shot that cannot be moved or stopped.

entity?

optional entity?: number;

Follow an entity.

intensity

intensity: number;

Count and brightness multiplier; 1 is the preset.

position

position: Vec3;

World position; with entity, an offset from the entity.

preset

preset: string;

Preset name: hit-sparks, explosion, smoke, fire, magic, dust, trail. play only.

scale

scale: number;

Size multiplier; 1 is the preset.

tint?

optional tint?: Vec3;

Colour override, linear RGB; over 1 glows under bloom.

EffectDefinition

Effect definition registered at module scope or during game init. Periodic effects pulse first after one period.

Example

defineEffect({ id: 'heal', duration: 'instant', modifiers: [{ attribute: 'health', op: 'add', magnitude: 10 }] });

Extends

Gate

Properties

blockedByTags?

optional blockedByTags?: readonly string[];

Inherited from

Gate.blockedByTags

duration

duration: number | "instant" | "infinite";

grantTags?

optional grantTags?: readonly string[];

id

id: string;

maxStacks?

optional maxStacks?: number;

modifiers

modifiers: readonly object[];

period?

optional period?: number;

requiresTags?

optional requiresTags?: readonly string[];

Inherited from

Gate.requiresTags

stacking?

optional stacking?: "stack" | "none" | "refresh";

ExchangeCmd

Trade between two players' documents; the result is an exchange-result event.

Properties

a

a: number;

b

b: number;

give

give: string;

JSON: what a gives b.

id

id: number;

Guest-minted; echoed in the result.

take

take: string;

JSON: what a takes from b.

ExchangeResultEvent

The outcome of an exchange command, matched by its id.

Properties

aData

aData: string;

Player a's document after the trade, as the store wrote it (JSON); empty unless ok.

bData

bData: string;

Player b's document after the trade (JSON); empty unless ok.

id

id: number;

ok

ok: boolean;

reason

reason: string;

Empty when ok.

FaceCharacterCmd

Turn a character on the spot to face a way (see character.face).

Properties

entity

entity: number;

facing

facing: number;

Radians about +Y (0 faces +Z).

quick

quick: boolean;

The quickest turn the set has, instead of an unhurried one.

FeatureSpec

The features a game may declare. A key that is false is the same as absent.

Properties

characters?

optional characters?: boolean | CharactersOptions;

The splat character bridge (spawn-character and friends).

multiplayer?

optional multiplayer?: boolean | MultiplayerOptions;

Rooms, players and replication.

vfx?

optional vfx?: boolean | VfxOptions;

Particle effects and post processing, optionally with a declared base look.

FightBase

The fight kit's script door: the take under a fighter's state and how it plays (the pack's name, or '' for the key-pose stance; a hold, start, end or frames below 0 means none; upper '' for none).

Properties

end

end: number;

fade

fade: number;

frames

frames: number;

hold

hold: number;

looped

looped: boolean;

name

name: string;

rate

rate: number;

start

start: number;

upper

upper: string;

FightBaseOptions

The take under a fighter's state (the fight pack's name) and how it plays; every field but the name optional.

Properties

fade?

optional fade?: number;

Frames to cross-fade in over.

frames?

optional frames?: number;

from?

optional from?: number;

A window of the take (fractions) stretched over frames game frames.

hold?

optional hold?: number;

A still: the take held at this fraction of its length.

loop?

optional loop?: boolean;

Looped (a stance, a walk); once by default.

name

name: string;

rate?

optional rate?: number;

Playback rate, 1 as captured.

to?

optional to?: number;

upper?

optional upper?: string;

The body above the hips from this take instead (a walk's legs under the fighter's own stance).

FightBodyEvent

A fighter's body the host leads this step (thrown, lying, or rising): where it is (the pelvis, world), whether it is in the air, whether it lies face up, and the yaw it faces. Said every step the body is the host's, so the game's rules keep its place.

Properties

airborne

airborne: boolean;

entity

entity: number;

faceUp

faceUp: boolean;

facing

facing: number;

point

point: Vec3;

FightCameraCmd

The fight camera, run on the host (see camera.fight).

Properties

a

a: number;

b

b: number;

closeUp

closeUp: number;

half

half: number;

hero

hero: number;

on

on: boolean;

openFloor

openFloor: boolean;

ropeLine

ropeLine: number;

shake

shake: number;

sides

sides: number;

wideFor

wideFor: number;

FightContactEvent

A fighter's strike met the other body this step (the fight kit's script door): the striker, the body it met (the strike's target), the part struck (0 the head, 1 the body, 2 the legs), where (world), and which of the struck body's legs is the nearer to the striker (+1 its left, -1 its right). Said every step the striking part is in the other body while the strike can hit; take the first and decide what the blow does.

Properties

entity

entity: number;

leg

leg: number;

point

point: Vec3;

target

target: number;

zone

zone: number;

FightFallCmd

A fighter thrown into the rag-doll (see character.fightFall).

Properties

entity

entity: number;

kick

kick: boolean;

The body is thrown already: the blow is blended into its flight.

spin

spin: number;

turn

turn: number;

velocity

velocity: Vec3;

FightGetUpCmd

A fighter up off the floor (see character.fightGetUp).

Properties

entity

entity: number;

quick

quick: boolean;

FightHitCmd

A blow on a fighter (see character.fightHit).

Properties

blocked

blocked: boolean;

Taken on the guard: the block's push and the legs' give by k, nothing else.

dir

dir: number;

The way the blow came along the floor (+1 / -1, the striker's facing) and the striker's line's turn.

entity

entity: number;

k

k: number;

leg

leg: number;

reaction

reaction: string;

reactionAmount

reactionAmount: number;

reactionFrames

reactionFrames: number;

rising

rising: boolean;

side

side: number;

stagger

stagger: boolean;

staggerSide

staggerSide: number;

staggerUp

staggerUp: number;

throws

throws: boolean;

The blow throws the body (a fightFall follows): the push on the joints only.

turn

turn: number;

zone

zone: number;

FightHitOptions

A blow on a fighter, as character.fightHit takes it.

Properties

blocked?

optional blocked?: boolean;

Taken on the guard: the block's push on the arms and the legs' give by k, nothing else.

dir

dir: number;

The way the blow came along the floor: +1 / -1, the striker's facing.

k

k: number;

How hard, 0 to 1.

leg?

optional leg?: number;

+1 the left leg was struck, -1 the right.

reaction?

optional reaction?: 
  | {
  amount?: number;
  clip: string;
  frames?: number;
}
  | null;

The reaction take laid on top (the pack's hit_head_left and the like), its amount (0 to 1) and frames.

rising?

optional rising?: boolean;

An uppercut: it lifts the chin.

side?

optional side?: number;

From which side: +1 the fighter's left, -1 its right, 0 straight on.

stagger?

optional stagger?: 
  | {
  side?: number;
  up?: number;
}
  | null;

The stagger (a big blow throws the body loose above the knees for a moment): from which side, up (1 for a rising blow).

throws?

optional throws?: boolean;

The blow throws the body (a character.fightFall follows): the push on the joints only.

turn?

optional turn?: number;

The striker's line's turn (rad); 0 one on one.

zone

zone: number;

Where: 0 the head, 1 the body, 2 the legs.

FightSetEvent

The fight pack the page's bridge loaded (the fight kit's script door), handed to the game once it is read: the pack's name and its fight block as the pack carries it, JSON text (strikes: every strike's frames, level, limb, radius, push, hitstop, strength, launch, travel, aim, its power version, its styles). Read it with JSON.parse and keep no table of your own. Said once, on the first tick after the set is in.

Properties

json

json: string;

name

name: string;

FightShotOptions

The fight camera's request, as camera.fight takes it; everything but the two fighters optional.

Properties

a

a: number;

The two fighters framed.

b

b: number;

closeUp?

optional closeUp?: number;

Lean in on a knockout, 0 to 1.

half?

optional half?: number;

hero?

optional hero?: number;

The winner it goes in close on.

on?

optional on?: boolean;

Off: the camera is yours again.

openFloor?

optional openFloor?: boolean;

The ring: an open floor with ropes (default) or a line between walls; the walls' half width; the ropes' line from the middle; the sides.

ropeLine?

optional ropeLine?: number;

shake?

optional shake?: number;

A shake added this step (0.02 a hit, 0.1 a knockout).

sides?

optional sides?: number;

wideFor?

optional wideFor?: number;

Glide out to the wide shot and hold it this many seconds (a knockdown), then back.

FightStateCmd

What a fighter's body is doing this step (see character.fight).

Properties

anchor

anchor: number;

The base take's root held (1 where it started, 2 in place); a turn laid on the pose, radians.

arc

arc: number;

A jump with no strike in it: its arc (0 to 1; below 0 none), its way (+1 in, -1 back, 0 up), a somersault.

base

base: FightBase;

blend

blend: number;

Frames to blend from the pose as it was, on the step the state changes (0 none; -1 the driver's own).

bounce

bounce: number;

bulk

bulk: number;

How thick the body is to a blow, 1 as built.

crouch

crouch: boolean;

crouched

crouched: boolean;

entity

entity: number;

facing

facing: number;

fists

fists: string;

The take whose hands make the fists in the guard (the fighter's idle); '' for the base's own hands.

flip

flip: boolean;

frozen

frozen: boolean;

grounded

grounded: boolean;

guard

guard: number;

guardUp

guardUp: boolean;

held

held: boolean;

The impact freeze as it was at the start of the step: the physics and the reaction stand still.

jumpDir

jumpDir: number;

look

look: Vec3 | undefined;

lookWeight

lookWeight: number;

mirrored

mirrored: boolean;

on

on: boolean;

False ends the fight on this body; the next true starts afresh.

pitch

pitch: number;

place

place: Vec3;

Where the fighter stands (world) and the yaw its object is turned by.

posture

posture: boolean;

reach

reach: number;

The fighter's real reach, metres (0: the figure's own).

recoil

recoil: number;

reset

reset: boolean;

A round starts again: the blows' push, the stagger, the springs and the rag-doll cleared.

squash

squash: number;

Nudges on the springs this step: the legs' give, the spine's pitch; the legs' give cleared; the striker's recoil.

squashReset

squashReset: boolean;

strike

strike: FightStrike;

target

target: number;

The other fighter (0 none): the strike is aimed at its body and met against it (fight-contact events).

turning

turning: number;

turnTo

turnTo: number;

yaw

yaw: number;

FightStateOptions

What a fighter's body is doing this step; every field optional (the defaults: standing still on its feet).

Properties

anchor?

optional anchor?: number;

The base take's root: 0 as the take moves, 1 started where the fighter stands (a celebration), 2 held in place (a dance).

arc?

optional arc?: number;

A jump with no strike in it: where in its arc (0 leaving the floor, 1 landing), its way (+1 in, -1 back, 0 up), a somersault.

base?

optional base?: FightBaseOptions | null;

The take under the state, or null for the key-pose stance.

blend?

optional blend?: number;

Frames to blend from the pose as it was, said on the step the state changes (0 none). Left out, the driver blends four frames on its own whenever what plays changes.

bounce?

optional bounce?: number;

The idle's bounce on the key-pose stance, 0 to 1.

bulk?

optional bulk?: number;

How thick the body is to a blow (the hurt areas' radius, squared), 1 as built.

crouch?

optional crouch?: boolean;

The crouch wanted.

crouched?

optional crouched?: boolean;

The key-pose stance is the crouch.

facing?

optional facing?: number;

+1 or -1 along its line (1 by default).

fists?

optional fists?: string;

The take whose hands make the fists in the guard (the fighter's idle); none: the base's own hands.

flip?

optional flip?: boolean;

frozen?

optional frozen?: boolean;

The impact freeze after this step (the takes, the stagger and the blend stand still), and held, the freeze as it was at the start of the step (the blows' springs, the legs' give, the rag-doll, the reaction and the rise stand still): a game whose freeze counts down inside its step says both. held follows frozen when left out.

grounded?

optional grounded?: boolean;

A standing state: the feet plant, the crouch applies (true by default).

guard?

optional guard?: number;

The fists brought up to the face, 0 none to 1.

guardUp?

optional guardUp?: boolean;

Blocking: the guard laid on the stance, the gloves up, the chin down.

held?

optional held?: boolean;

jumpDir?

optional jumpDir?: number;

look?

optional look?: Vec3 | null;

A point the face turns to (world), by lookWeight (0 none to 1).

lookWeight?

optional lookWeight?: number;

mirrored?

optional mirrored?: boolean;

Facing the other way: the pose is the mirror image.

pitch?

optional pitch?: number;

posture?

optional posture?: boolean;

The spine and neck kept near how the character is built (true by default).

reach?

optional reach?: number;

The fighter's real reach, metres: the glove lands that much further than the figure's own arm (none: the figure's).

recoil?

optional recoil?: number;

The striker's own recoil this step, by the blow's strength.

reset?

optional reset?: boolean;

A round starts again: the blows' push, the stagger, the springs and the rag-doll cleared, the body standing where the entity is; its takes cross-fade on. Say it on the round's first step.

squash?

optional squash?: number;

Nudges on the springs this step: the legs' give (a landing, a dash, a special's wind-up), the spine's pitch (an armored hit).

squashReset?

optional squashReset?: boolean;

The legs' give cleared (a jump leaving the floor).

strike?

optional strike?: FightStrikeOptions | null;

target?

optional target?: number;

The other fighter (an entity): a strike with no aim of its own is aimed at that body, and met against it: a fight-contact event in ctx.events every step the striking part is in it while the strike can hit (the part struck, the point, the nearer leg); your rules take the first and decide what the blow does.

turning?

optional turning?: number;

Turning round on the spot: how much of the half turn is still to show, 0 to 1.

turnTo?

optional turnTo?: number;

A turn about the vertical laid on the pose, radians (a winner turning to the camera).

FightStrike

A strike under way: the pack's strike id ('' none), its frame, the fighter's speed stretch, extra recovery frames, the aim.

Properties

aim

aim: Vec3 | undefined;

aimWeight

aimWeight: number;

extra

extra: number;

frame

frame: number;

id

id: string;

speed

speed: number;

FightStrikeOptions

A strike under way: the pack's strike id and its frame (0 the first); the rest optional.

Properties

aim?

optional aim?: Vec3;

Where the striking part is aimed (world), pulled there by aimWeight (0 to 1, 1 by default). None: aimed at the state's target fighter's body as the pack's strike says (the face, the chin, the ribs, the nearer thigh, the raised gloves), the pull growing through the wind-up, held while it can hit, let go in the recovery; with no target either, the take as captured.

aimWeight?

optional aimWeight?: number;

extra?

optional extra?: number;

Frames added to the recovery.

frame

frame: number;

id

id: string;

speed?

optional speed?: number;

The fighter's speed stretch on the startup and the recovery, 1 as written.

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.

FittedShape

Fitted primitive with local center and capsule orientation (engine local Y).

Example

const shape: FittedShape = fitBox(new Float32Array([-1,-1,-1,1,1,1]));

Properties

center

center: Vec3;

dims

dims: readonly number[];

rotation

rotation: Quat;

shape

shape: "box" | "sphere" | "capsule";

FlatPoint

A point on the ground plane; y is ignored.

Properties

x

readonly x: number;

z

readonly z: number;

FloorResult

Cached support; distances are measured from the full capsule bottom.

Example

const distance = movement.currentFloor.floorDist;

Properties

blockingHit

blockingHit: boolean;

floorDist

floorDist: number;

hit

hit: SweepHit;

lineDist

lineDist: number;

lineTrace

lineTrace: boolean;

sweepLocation

sweepLocation: Vec3;

Capsule centre at the original floor sweep contact, before pullback.

walkableFloor

walkableFloor: boolean;

FlowField

One goal for many agents: every cell knows which way to go. After an obstacle or cost area is added or removed the field re-integrates towards its goal on its next query, so it never goes stale.

Methods

direction()

direction(
   x, 
   z, 
   out
): boolean;

Parameters

Parameter	Type	Description
`x`	`number`	World x.
`z`	`number`	World z.
`out`	`NavPoint`	Receives a unit direction towards the goal.

Returns

boolean

false where the goal cannot be reached (or at the goal itself).

distance()

distance(x, z): number;

Parameters

Parameter	Type
`x`	`number`
`z`	`number`

Returns

number

Weighted travel cost to the goal in metres, Infinity if unreachable.

setGoal()

setGoal(x, z): boolean;

Recompute the field towards a goal. Cost grows with the grid, not the agents.

Parameters

Parameter	Type
`x`	`number`
`z`	`number`

Returns

boolean

false when the goal is not on walkable ground.

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.

ForceFieldProps

Properties for a radial force source.

Example

const props: Partial<ForceFieldProps> = { fireOnBeginPlay: true, radius: 8 };

Properties

active

active: boolean;

falloff

falloff: "linear" | "constant";

fireOnBeginPlay

fireOnBeginPlay: boolean;

forceStrength

forceStrength: number;

impulseStrength

impulseStrength: number;

radius

radius: number;

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;

players

players: readonly PlayerInput[];

Every player's input in a room, ascending by id. Empty for a single-player game. A held seat (its player dropped) is left out until they are back.

vehicles?

optional vehicles?: ArrayLike<number>;

Versioned vehicle telemetry; absent for older direct hosts.

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.

localCommands

localCommands: readonly Command[];

Applied by the authority after commands; never forwarded to a client.

look?

optional look?: object;

Final local player look after game camera rules, for the page input sequence.

pitch

pitch: number;

yaw

yaw: number;

transforms

transforms: Float32Array;

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

ui?

optional ui?: string;

UI JSON, present only on the frames it changed.

FxOptions

Bus effect overrides.

Example

`audio.fx('music', 'underwater', { fadeMs: 500 });`

Properties

compressor?

optional compressor?: boolean;

Enable compression.

fadeMs?

optional fadeMs?: number;

Ramp duration.

highpassHz?

optional highpassHz?: number;

High-pass cutoff.

lowpassHz?

optional lowpassHz?: number;

Low-pass cutoff.

reverb?

optional reverb?: number;

Wet level.

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.

fx()

fx(
   bus, 
   preset, 
   options?
): void;

Set bus effects.

Parameters

Parameter	Type	Description
`bus`	`AudioBus`	Mixer bus.
`preset`	`FxPreset`	Base preset.
`options?`	`FxOptions`	Overrides and fade.

Returns

void

Example

`audio.fx('sfx', 'cave');`

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.

occlude()

occlude(
   sound, 
   amount, 
   fadeMs?
): void;

Muffle a sound.

Parameters

Parameter	Type	Default value	Description
`sound`	`number`	`undefined`	Sound handle.
`amount`	`number`	`undefined`	Occlusion from zero to one.
`fadeMs`	`number`	`0`	Ramp duration.

Returns

void

Example

`audio.occlude(1, 0.8, 120);`

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.

playOnBeat()

playOnBeat(asset, options?): number;

Schedule a sound on the music grid.

Parameters

Parameter	Type	Description
`asset`	`string` \| `number`	Manifest id or handle.
`options?`	`PlayOnBeatOptions`	Grid and mixer options.

Returns

number

Sound handle or zero for an unknown asset.

Example

`audio.playOnBeat('kick', { subdivision: 2 });`

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;

Returns

CameraState

fight()

fight(shot): void;

The fight camera (the fight kit's script door), run on the host: from the side, between the two fighters, pulled back as they part, raised when one flies, never still, inside the ropes; a wide shot on a knockdown, in close on the winner. Say it every step while it is on; the camera is yours again with on: false.

Parameters

Parameter	Type	Description
`shot`	`FightShotOptions`	The two fighters and the moment.

Returns

void

Nothing.

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(point): void;

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

Parameters

Parameter	Type	Description
`point`	`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.

cancelAction()

cancelAction(entity): void;

Take an action's request back (it cannot be taken back between its gathering and its landing).

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.

Returns

void

Nothing.

do()

do(
   entity, 
   action, 
   object?, 
   plain?
): void;

Ask a character to do an action of its motion set (a hurdle, a jump, a sit), at an object when the action needs one. What follows comes as motion-events in ctx.events: started, contact, release (with the point and its velocity, for a thing let go), landed, done, or failed with its reason.

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Entity with a `Character` component.
`action`	`string`	`undefined`	The action's name in the set.
`object?`	`Readonly`<`ActionObject`>	`undefined`	The thing it is done at, as the game has it; left out for an action without one.
`plain?`	`boolean`	`false`	The plain way, for a comparison: the take simply started, nothing fitted.

Returns

void

Nothing.

Example

character.do(hero, 'hurdle', { id: bar, position: barAt, yaw: 0, height: 0.6, width: 1.2, depth: 0.05 });

face()

face(
   entity, 
   facing, 
   arrive?
): void;

Turn a character on the spot to face a way, by its set's own turns. The motion-event arrived named 'face' says when it faces there.

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Entity with a `Character` component.
`facing`	`number`	`undefined`	Radians about +Y (0 faces +Z).
`arrive`	`"easy"` \| `"quick"`	`'easy'`	`'easy'` (the default: an unhurried turn) or `'quick'` (the quickest the set has).

Returns

void

Nothing.

Example

character.face(guide, Math.PI / 2);

fight()

fight(entity, state?): void;

The fight kit's script door: what this fighter's body is doing this step. The host's fight driver makes the pose on the character's own body from the fight pack (the page's bridge names the set) and lays it on the bones after the character's own clips: the base take under the state, the stance or the crouch, the guard, the look, the strike by the pack's id and its frame pulled to its aim, the posture, the lean, the planted feet. Say it every step. Where the fighter stands is its entity's transform: set the position (x, up, z) and the rotation (the yaw, facing * PI / 2 + turn) yourself. The host answers with motion-events in ctx.events: down (a thrown body came to rest, kind landed) and risen (the get-up finished, kind done), each with point where the body is and facing the yaw it faces: put the entity there. Name the other fighter (target) and the strike is aimed at its body and met against it: a fight-contact event says where. The pack's own table of moves comes once as a fight-set event (its fight block, JSON text).

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`state`	`FightStateOptions` \| `null`	What the body is doing; every field optional. `null` ends the fight on this body (a round's reset): the clips have it again, and the next call starts afresh, standing.

Returns

void

Nothing.

Example

character.fight(me, { base: { name: 'fight_idle_bounce', loop: true, fade: 10 }, facing: 1, bounce: 0.7 });
character.fight(me, { base: null, strike: { id: 'jab', frame, aim: theirHead } });

fightFall()

fightFall(
   entity, 
   velocity, 
   spin?, 
   turn?, 
   kick?
): void;

A fighter thrown into the fight kit's rag-doll: it flies at velocity (metres a second, world), turning at spin, falls, bounces, slides and comes to rest; the entity follows the body; the motion-event down says when it lies still and where. Then character.fightGetUp.

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Entity with a `Character` component.
`velocity`	`Vec3`	`undefined`	Metres a second, world.
`spin`	`number`	`2`	Radians a second about the axis across the blow's line (0.4 to 3 reads as a knockdown).
`turn`	`number`	`0`	The blow's line's angle on the floor (0 along x).
`kick`	`boolean`	`false`	The body is thrown already (a hit in the air): the blow is blended into its flight.

Returns

void

Nothing.

fightGetUp()

fightGetUp(entity, quick?): void;

A fighter up off the floor: the get-up take chosen by how the body lies (on its back the spring-up, or the kip-up when quick; face down the stomach get-up), facing the way the head points. Keep saying character.fight with grounded: false while it rises; the motion-event risen says when it stands, where, and which way (facing, a yaw).

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Entity with a `Character` component.
`quick`	`boolean`	`false`	The kip-up.

Returns

void

Nothing.

fightHit()

fightHit(entity, hit): void;

A blow on a fighter on the fight kit's door: the push on its joints, the stagger and the reaction take, as the fight pack's own blows do. Your rules decide the damage and the stun; this is the body's answer.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`hit`	`FightHitOptions`	The blow.

Returns

void

Nothing.

hit()

hit(entity, blow): void;

A blow. Every exported character has a physics body (its parts on the engine's physics); the nearest part to at takes the blow along direction, and the body reacts for real: a small hit flinches and recovers over about a second, a big one falls onto the floor and stays down until character.recover, a shot is sharper, a push shoves. Use this before writing a reaction of your own.

What happened comes back as anim-events on the clip ragdoll: hit, fell (the body came to rest on the floor), recovered.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`blow`	{ `at`: `Vec3`; `direction?`: `Vec3`; `strength`: `number` \| `"small"` \| `"big"` \| `"shot"` \| `"big-shot"`; }	Where it lands (`at`, world), which way it travels (`direction`, world; omitted: from the character's front) and how hard (`strength`: `'small'`, `'big'`, `'shot'`, `'big-shot'`, or a push's newton-seconds: 40 staggers, 90 and over floors).
`blow.at`	`Vec3`	-
`blow.direction?`	`Vec3`	-
`blow.strength`	`number` \| `"small"` \| `"big"` \| `"shot"` \| `"big-shot"`	-

Returns

void

Nothing.

Example

character.hit(enemy, { at: swordTip, direction: swing, strength: 'small' });
character.hit(enemy, { at: swordTip, direction: swing, strength: 'big' }); // down

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.

motion()

motion(entity, options?): void;

How the movement system moves a character. A character with a motion set (its package's own, else the engine's shared one) is moved by whole takes of a performer matched to the velocity given to character.setState: its starts, stops and turns are the performer's own, its feet are held where they land. That is the default; this call changes it for one character: off, another set, whether the take carries the walker, the two dials, and which kind of stop it makes from a run. What is left out stays as it is.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`options`	`CharacterMotionOptions`	What to change.

Returns

void

Nothing.

Example

character.motion(hero, { responsiveness: 0.9 }); // a snappier hero
character.motion(guard, { on: false }); // this one by the clips' blend, as before
character.motion(hero, { stop: 'hard' }); // from a run it brakes, instead of slowing to a stand

recover()

recover(entity): void;

Back into the animation: a character that is down (or reacting) blends back over about a second, where it stood. Move the entity to where the body lies first (anim-event fell; the head and root joints read where it lies) to have it get up there.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.

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?, 
   facing?
): 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.
`facing?`	`number`	`undefined`	Optional held world yaw in radians; permits backpedalling without turning.

Returns

void

Nothing.

stopWalk()

stopWalk(entity): void;

Give up a walk to a spot: the character stops where it is, as its takes stop.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.

Returns

void

Nothing.

walkTo()

walkTo(
   entity, 
   target, 
   how?
): void;

Send a character to a spot: it turns, walks or runs there and arrives facing the way asked. The motion-event arrived (in ctx.events) says it got there; failed says why not; started and then done, both named stop, say when its stop begins and when it no longer travels; limited says once that the speed it is given (amount) is not the one asked. A velocity given to character.setState while it walks takes over.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`target`	`Vec3`	The spot, world space, on the floor.
`how`	{ `arrive?`: `"easy"` \| `"quick"`; `facing?`: `number`; `pace?`: `number`; `start?`: `"moving"`; `stop?`: `StopStyle`; }	The facing to arrive with (`facing`, radians about +Y, 0 faces +Z; left out: as it arrives), the pace (`pace`, metres a second; left out: the set's own walk; above the speeds its walk covers it runs, when its set has a run and the spot is far enough to run to), how it stops (`arrive`: `'easy'`, the default, the takes' unhurried stops; `'quick'`, the shortest stops and turns the set has) and which kind of stop this one walk ends with (`stop`: `'gradual'`, it slows and stands upright; `'hard'`, it brakes; left out: the character's own, see `character.motion`). `arrive` says how soon it must be there, `stop` says which kind of stop; a `'quick'` walk that states no `stop` stops as a quick walk always did. A kind is read on a run's stops: a walk's stop and a sprint's stop are the same under both on the engine's shared set. And how it is begun (`start`: `'moving'`, the game says the body is under way already: it comes out of a get-up, it was carried or thrown; the walk is then planned as of a body under way: no turn on the spot first, no start from standing; left out: as its takes have the body).
`how.arrive?`	`"easy"` \| `"quick"`	-
`how.facing?`	`number`	-
`how.pace?`	`number`	-
`how.start?`	`"moving"`	-
`how.stop?`	`StopStyle`	-

Returns

void

Nothing.

Example

character.walkTo(guide, { x: 2, y: 0, z: -3 }, { facing: Math.PI });
character.walkTo(rider, bikeSide, { pace: 3.4 }); // a run's pace: it runs there
character.walkTo(rider, bikeSide, { pace: 3.4, stop: 'hard' }); // and brakes at the spot
character.walkTo(rider, bikeSide, { pace: 3.4, start: 'moving' }); // out of a get-up: no turn on the spot first

config

readonly config: GameConfig;

The init config.

contacts

readonly contacts: readonly Contact[];

Contacts reported since the previous tick.

data

readonly data: DataFacade;

Saved player/game documents and trades. Only the authority writes.

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.

touch

touch: object;

Fingers on a touch screen, as the host's touch layer packs them: the first finger is the pointer (mouse), a tap is pressed('Tap'), and the thumb sticks, the pinch and the turn are here.

touch.active

Get Signature

get active(): boolean;

Is a finger on the screen? (The touch pad is connected.)

Returns

boolean

True while any finger is down.

touch.pinch

Get Signature

get pinch(): number;

Two fingers' pinch this step, as a scale factor: over 1 the fingers moved apart (zoom in), under 1 together, exactly 1 with no pinch.

Returns

number

The scale factor.

touch.turn

Get Signature

get turn(): number;

Two fingers' turn this step, in radians, counter-clockwise on the screen positive.

Returns

number

The turn.

touch.stick()

stick(side): Axis2;

A thumb stick's push.

Parameters

Parameter	Type	Description
`side`	`"left"` \| `"right"`	The left stick (movement) or the right one (the camera).

Returns

A pooled { x, y }, -1..1, y up the screen positive. Never retain it.

control

Get Signature

get control(): Readonly<NonNullable<InputState["control"]>>;

Received page control for this frame. Owned by the SDK; read during the tick.

Returns

Readonly<NonNullable<InputState["control"]>>

The control state received with this input sequence.

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

The modifiers for this frame.

mouse

Get Signature

get mouse(): MouseState;

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

Returns

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

action()

action(name): ActionState;

Read a declared button into pooled storage. Unknown names throw.

Parameters

Parameter	Type	Description
`name`	`string`	Declared button action name.

Returns

Pooled button state; read immediately.

axis2()

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

Pass a declared axis action name alone, or four keys. A two-axis reading built from four keys, plus a thumb stick on a touch screen: the left one by default, so axis2('A', 'D', 'S', 'W') moves on a phone with no other binding. Pass 'right' for a camera axis, 'none' for keys only. With the left stick and opposing WASD/arrow movement pairs, uses combined movement (both key sets, left touch and first physical pad, radial deadzone and unit-circle clamp), with each binding's requested sign. Page control supplies that same movement when present. Other bindings read only their four keys and the requested touch stick.

Parameters

Parameter	Type	Default value	Description
`negX`	`string`	`undefined`	Declared axis name, or key driving x negative, e.g. `'A'`.
`posX?`	`string`	`undefined`	Key that drives x positive, for example `'D'`.
`negY?`	`string`	`undefined`	Key that drives y negative, for example `'S'`.
`posY?`	`string`	`undefined`	Key that drives y positive, for example `'W'`.
`stick?`	`StickSide`	`'left'`	Which thumb stick to add, `'left'` by default.

Returns

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.

levels

readonly levels: LevelsFacade;

The levels: names(), current, load(ctx, name).

localPlayer

readonly localPlayer: PlayerHandle | null;

This page's player on a client; null on the authority and in solo.

music

readonly music: object;

Music and the beat.

bar

Get Signature

get bar(): number;

Last heard bar number.

Returns

number

beat

Get Signature

get beat(): number;

Last heard beat number.

Returns

number

beatInBar

Get Signature

get beatInBar(): number;

Last heard beat within the bar.

Returns

number

beatsPerBar

Get Signature

get beatsPerBar(): number;

Beats per bar of the last playback request.

Returns

number

bpm

Get Signature

get bpm(): number;

Tempo of the last playback request.

Returns

number

layer()

layer(
   index, 
   gain, 
   fadeMs?
): void;

Change a stem gain.

Parameters

Parameter	Type	Default value	Description
`index`	`number`	`undefined`	Stem index.
`gain`	`number`	`undefined`	Linear gain.
`fadeMs`	`number`	`0`	Ramp duration.

Returns

void

nearestBeat()

nearestBeat(): number;

The number of the beat nearest to now, as heard: the beat offsetMs() measures from. A press just before beat 12 gives 12, just after it also 12, so a chart of beat numbers is judged with nearestBeat() === note and Math.abs(offsetMs()).

Returns

number

The beat number, or NaN before a beat or without a tempo.

Example

import { music } from 'gameable';

if (music.nearestBeat() === 12 && Math.abs(music.offsetMs()) <= 45) console.log('perfect');

offsetMs()

offsetMs(): number;

Signed milliseconds since the nearest beat; negative when it is still ahead.

Returns

number

Offset, or NaN before a beat or without a tempo.

play()

play(assets, options?): void;

Stream a track or playlist.

Parameters

Parameter	Type	Description
`assets`	`string` \| `number` \| readonly (`string` \| `number`)[]	Manifest ids or handles.
`options?`	`MusicOptions`	Playback options.

Returns

void

stems()

stems(assets, options?): void;

Play synchronized stems.

Parameters

Parameter	Type	Description
`assets`	readonly (`string` \| `number`)[]	Manifest ids or handles.
`options?`	`StemOptions`	Playback options and gains.

Returns

void

stop()

stop(fadeMs?): void;

Stop music.

Parameters

Parameter	Type	Default value	Description
`fadeMs`	`number`	`0`	Fade duration.

Returns

void

net

readonly net: NetFacade;

Where this guest runs, game messages in and out, and local-only commands.

pause

readonly pause: object;

Named pause owners; release from the host page while simulation is stopped.

pop()

pop(reason): void;

Parameters

Parameter	Type
`reason`	`string`

Returns

void

push()

push(reason): void;

Parameters

Parameter	Type
`reason`	`string`

Returns

void

reasons()

reasons(): readonly string[];

Returns

readonly string[]

physics

readonly physics: object;

Physics queries and body commands.

ALL_LAYERS

ALL_LAYERS: CollisionLayers;

Every collision layer, for queries that should hit anything.

vehicle

vehicle: object;

Host arcade handling on guest body handles.

vehicle.create()

create(
   body, 
   settings, 
   initialState?
): Readonly<VehicleState>;

Attach once to an existing dynamic body. State is borrowed until removal.

Parameters

Parameter	Type
`body`	`number`
`settings`	`VehicleSettings`
`initialState?`	`Readonly`<`VehicleState`>

Returns

Readonly<VehicleState>

Example

physics.vehicle.create(body, settings);

vehicle.remove()

remove(body): void;

Remove handling; the chassis remains alive. Safe to repeat.

Parameters

Parameter	Type
`body`	`number`

Returns

void

Example

physics.vehicle.remove(body);

vehicle.reset()

reset(
   body, 
   position, 
   rotation
): void;

Teleport and clear motion, controls and handling history.

Parameters

Parameter	Type
`body`	`number`
`position`	`Vec3`
`rotation`	`Quat`

Returns

void

Example

physics.vehicle.reset(body, position, rotation);

vehicle.setInput()

setInput(
   body, 
   controls, 
   gripScale?
): void;

Submit transient controls; omitted steps use the host parking brake.

Parameters

Parameter	Type	Default value
`body`	`number`	`undefined`
`controls`	`Readonly`<`VehicleInput`>	`undefined`
`gripScale`	`number`	`1`

Returns

void

Example

physics.vehicle.setInput(body, controls, 0.5);

vehicle.state()

state(body): Readonly<VehicleState> | undefined;

Borrow the last post-step state without allocating.

Parameters

Parameter	Type
`body`	`number`

Returns

Readonly<VehicleState> | undefined

Example

const speed = physics.vehicle.state(body)?.speed;

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.

boxCast()

boxCast(
   position, 
   halfExtents, 
   rotation, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Cast a box with a quaternion orientation.

Parameters

Parameter	Type	Description
`position`	`Vec3`	World-space query centre.
`halfExtents`	`Vec3`	Box half-size in metres.
`rotation`	`Quat`	Unit quaternion orientation.
`direction`	`Vec3`	Sweep direction; need not be normalised.
`maxDistance`	`number`	Maximum travel in metres.
`mask?`	`CollisionLayers`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	Entity to skip.

Returns

RayHit | null

The closest hit, or null on a miss; hit.distance is the shape travel in metres.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const forward = { x: 0, y: 0, z: 1 };
    const halfExtents = { x: 0.5, y: 0.5, z: 0.5 };
    const hit = physics.boxCast(position, halfExtents, rotation, forward, 1);
    console.log('can the crate be pushed forward one metre?', hit === null);
  },
});

capsuleCast()

capsuleCast(
   position, 
   radius, 
   halfHeight, 
   rotation, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Cast a capsule; halfHeight is half its straight segment.

Parameters

Parameter	Type	Description
`position`	`Vec3`	World-space query centre.
`radius`	`number`	Radius in metres.
`halfHeight`	`number`	Half the straight capsule segment in metres.
`rotation`	`Quat`	Unit quaternion orientation.
`direction`	`Vec3`	Sweep direction; need not be normalised.
`maxDistance`	`number`	Maximum travel in metres.
`mask?`	`CollisionLayers`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	Entity to skip.

Returns

RayHit | null

The closest hit, or null on a miss; hit.distance is the shape travel in metres.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const forward = { x: 0, y: 0, z: 1 };
    const hit = physics.capsuleCast(position, 0.3, 0.6, rotation, forward, 0.4);
    console.log('can the character step here?', hit === null);
  },
});

distance()

distance(
   a, 
   b, 
   options
): number;

Create a distance joint. Bodyless entities return 0; b=0 anchors to the world. With no limits, this is a rigid rod that keeps its initial length. Set min/max in metres to constrain a rope or rod length.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; `anchorB?`: `Vec3`; `max?`: `number`; `min?`: `number`; `spring?`: `JointSpring`; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.
`options.anchorB?`	`Vec3`	World-space second distance-joint end.
`options.max?`	`number`	Upper linear limit in metres.
`options.min?`	`number`	Lower linear limit in metres.
`options.spring?`	`JointSpring`	Limit frequency in Hz and damping ratio.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Weight = prefab({ body: { shape: 'sphere', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const weight = ctx.spawn(Weight, { x: 0, y: 1, z: 0 });
    // No limits: a rigid rod that keeps its initial 3 metre length.
    physics.distance(weight, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      anchorB: { x: 0, y: 4, z: 0 },
    });
  },
});

fixed()

fixed(
   a, 
   b, 
   options?
): number;

Create a fixed joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Default value	Description
`a`	`number`	`undefined`	First entity, with a physics body.
`b`	`number`	`undefined`	Second entity, or 0 to join to the world.
`options`	{ `anchor?`: `Vec3`; }	`EMPTY_JOINT_OPTIONS`	Joint or motor settings.
`options.anchor?`	`Vec3`	`undefined`	World-space anchor at creation.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Crate = prefab({ body: { shape: 'box', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const crateA = ctx.spawn(Crate, { x: 0, y: 1, z: 0 });
    const crateB = ctx.spawn(Crate, { x: 1.1, y: 1, z: 0 });
    physics.fixed(crateA, crateB); // Weld the two crates together.
  },
});

hinge()

hinge(
   a, 
   b, 
   options
): number;

Create a hinge joint. Bodyless entities return 0; b=0 anchors to the world.

Values and targets measure how far entity a has moved relative to entity b (or the world). Slider positive is along +axis; hinge positive follows the right-hand rule about +axis. Rotation values and rotational position targets are degrees; angular velocity targets are degrees per second.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; `axis`: `Vec3`; `friction?`: `number`; `maxDeg?`: `number`; `minDeg?`: `number`; `spring?`: `JointSpring`; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.
`options.axis`	`Vec3`	World-space axis; positive motion follows +axis.
`options.friction?`	`number`	Maximum friction torque in N·m.
`options.maxDeg?`	`number`	Upper angular limit in degrees.
`options.minDeg?`	`number`	Lower angular limit in degrees.
`options.spring?`	`JointSpring`	Limit frequency in Hz and damping ratio.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Door = prefab({ body: { shape: 'box', dims: [0.5, 1, 0.05], kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const door = ctx.spawn(Door, { x: 0.5, y: 1, z: 0 });
    physics.hinge(door, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      axis: { x: 0, y: 1, z: 0 },
      minDeg: -90,
      maxDeg: 90,
    });
  },
});

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.

jointValue()

jointValue(id, axis?): number | null;

Read a joint coordinate, degrees for rotation, metres for translation or distance length. Distance returns the current unsigned length; unavailable coordinates return null.

Parameters

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	Guest-minted joint handle.
`axis`	`number`	`0`	Joint axis: 0 for one-axis joints, 0 through 5 for six-dof.

Returns

number | null

The coordinate in degrees for rotation or metres for translation/length, or null when unavailable.

Example

import { defineGame, physics, prefab } from 'gameable';

const Lever = prefab({ body: { shape: 'box', kind: 'dynamic' } });
let leverJoint = 0;
export default defineGame({
  init(ctx) {
    const lever = ctx.spawn(Lever, { x: 0, y: 1, z: 0 });
    leverJoint = physics.hinge(lever, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      axis: { x: 1, y: 0, z: 0 },
      minDeg: -90,
      maxDeg: 90,
    });
  },
  systems: [
    () => {
      const angle = physics.jointValue(leverJoint);
      const isLeverDown = angle !== null && angle < -80;
      if (isLeverDown) console.log('lever down');
    },
  ],
});

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.

overlapBox()

overlapBox(
   position, 
   halfExtents, 
   rotation, 
   maxResults?, 
   mask?, 
   ignoreEntity?
): readonly OverlapHit[];

Overlap a box.

Parameters

Parameter	Type	Default value	Description
`position`	`Vec3`	`undefined`	World-space query centre.
`halfExtents`	`Vec3`	`undefined`	Box half-size in metres.
`rotation`	`Quat`	`undefined`	Unit quaternion orientation.
`maxResults`	`number`	`16`	Maximum number of hits.
`mask?`	`CollisionLayers`	`undefined`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	`undefined`	Entity to skip.

Returns

readonly OverlapHit[]

The overlapping hits, nearest first; an empty list when nothing overlaps.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const halfExtents = { x: 2, y: 1, z: 2 };
    const hits = physics.overlapBox(position, halfExtents, rotation);
    console.log(
      'bodies in this area',
      hits.map((hit) => hit.entity),
    );
  },
});

overlapCapsule()

overlapCapsule(
   position, 
   radius, 
   halfHeight, 
   rotation, 
   maxResults?, 
   mask?, 
   ignoreEntity?
): readonly OverlapHit[];

Overlap a capsule.

Parameters

Parameter	Type	Default value	Description
`position`	`Vec3`	`undefined`	World-space query centre.
`radius`	`number`	`undefined`	Radius in metres.
`halfHeight`	`number`	`undefined`	Half the straight capsule segment in metres.
`rotation`	`Quat`	`undefined`	Unit quaternion orientation.
`maxResults`	`number`	`16`	Maximum number of hits.
`mask?`	`CollisionLayers`	`undefined`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	`undefined`	Entity to skip.

Returns

readonly OverlapHit[]

The overlapping hits, nearest first; an empty list when nothing overlaps.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const hits = physics.overlapCapsule(position, 2, 1, rotation);
    console.log(
      'bodies in this area',
      hits.map((hit) => hit.entity),
    );
  },
});

overlapShape()

overlapShape(
   shape, 
   position, 
   rotation, 
   maxResults?, 
   mask?, 
   ignoreEntity?
): readonly OverlapHit[];

Overlap a primitive shape.

Parameters

Parameter	Type	Default value	Description
`shape`	`QueryShape`	`undefined`	Primitive shape and its dimensions in metres.
`position`	`Vec3`	`undefined`	World-space query centre.
`rotation`	`Quat`	`undefined`	Unit quaternion orientation.
`maxResults`	`number`	`16`	Maximum number of hits.
`mask?`	`CollisionLayers`	`undefined`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	`undefined`	Entity to skip.

Returns

readonly OverlapHit[]

Hits nearest first, with the deepest contact point on each other body and real penetration depth (bounds centre and zero depth if no contact is available).

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const shape = { kind: 'cylinder', halfExtents: { x: 2, y: 1, z: 0 } } as const;
    const hits = physics.overlapShape(shape, position, rotation);
    console.log(
      'bodies in this area',
      hits.map((hit) => hit.entity),
    );
  },
});

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.

point()

point(
   a, 
   b, 
   options
): number;

Create a point joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Lamp = prefab({ body: { shape: 'sphere', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const lamp = ctx.spawn(Lamp, { x: 0, y: 3, z: 0 });
    physics.point(lamp, 0, { anchor: { x: 0, y: 4, z: 0 } });
  },
});

raycast()

raycast(
   origin, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?, 
   ignoreBody?
): 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.
`ignoreBody?`	`number`	Additional body to skip, such as a projectile while ignoring its owner entity.

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.

removeJoint()

removeJoint(id): void;

Remove a joint.

Parameters

Parameter	Type	Description
`id`	`number`	Guest-minted joint handle.

Returns

void

Nothing.

Example

import { defineGame, physics, prefab } from 'gameable';

const Crate = prefab({ body: { shape: 'box', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const crate = ctx.spawn(Crate, { x: 0, y: 1, z: 0 });
    const weld = physics.fixed(crate, 0);
    physics.removeJoint(weld);
  },
});

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.

setMotor()

setMotor(id, options): void;

Set a motor; rotational targets use degrees or degrees per second.

Parameters

Parameter	Type	Description
`id`	`number`	Guest-minted joint handle.
`options`	{ `axis?`: `number`; `maxForce?`: `number`; `mode`: `MotorMode`; `target`: `number`; }	Joint or motor settings.
`options.axis?`	`number`	Motor axis index: 0 for hinge/slider, 0..5 for six-dof.
`options.maxForce?`	`number`	Force limit in N or torque limit in N·m; omitted or 0 means 100, too weak to lift anything heavy (a 20 kg lift needs over 196 N).
`options.mode`	`MotorMode`	Off, velocity, or position control.
`options.target`	`number`	Metres or degrees; per second for velocity mode.

Returns

void

Nothing.

Example

import { defineGame, physics, prefab } from 'gameable';

const Body = prefab({ body: { shape: 'box', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const door = ctx.spawn(Body, { x: 0.5, y: 1, z: 0 });
    const doorJoint = physics.hinge(door, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      axis: { x: 0, y: 1, z: 0 },
      minDeg: -90,
      maxDeg: 90,
    });
    physics.setMotor(doorJoint, { mode: 'position', target: 90 });
    const lift = ctx.spawn(Body, { x: 3, y: 1, z: 0 });
    const liftJoint = physics.slider(lift, 0, {
      anchor: { x: 3, y: 1, z: 0 },
      axis: { x: 0, y: 1, z: 0 },
      min: 0,
      max: 5,
    });
    physics.setMotor(liftJoint, { mode: 'velocity', target: 1 }); // 1 m/s upward.
  },
});

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.

shapeCast()

shapeCast(
   shape, 
   position, 
   rotation, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Cast a primitive shape along a direction.

Parameters

Parameter	Type	Description
`shape`	`QueryShape`	Primitive shape and its dimensions in metres.
`position`	`Vec3`	World-space query centre.
`rotation`	`Quat`	Unit quaternion orientation.
`direction`	`Vec3`	Sweep direction; need not be normalised.
`maxDistance`	`number`	Maximum travel in metres.
`mask?`	`CollisionLayers`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	Entity to skip.

Returns

RayHit | null

The closest hit, or null on a miss; hit.distance is the shape travel in metres.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const forward = { x: 0, y: 0, z: 1 };
    const shape = { kind: 'cylinder', halfExtents: { x: 0.4, y: 0.5, z: 0 } } as const;
    const hit = physics.shapeCast(shape, position, rotation, forward, 2);
    console.log('travel before contact', hit?.distance);
  },
});

sixDof()

sixDof(
   a, 
   b, 
   options
): number;

Create a sixDof joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; `axes`: readonly [`JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`]; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.
`options.axes`	readonly [`JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`]	Six axis settings: tx, ty, tz, rx, ry, rz; rotational limits in degrees.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Hook = prefab({ body: { shape: 'box', kind: 'dynamic' } });
const locked = { mode: 'locked', min: 0, max: 0 } as const;
const free = { mode: 'free', min: 0, max: 0 } as const;
export default defineGame({
  init(ctx) {
    const hook = ctx.spawn(Hook, { x: 0, y: 3, z: 0 });
    physics.sixDof(hook, 0, {
      anchor: { x: 0, y: 3, z: 0 },
      axes: [locked, locked, locked, free, free, free],
    });
  },
});

slider()

slider(
   a, 
   b, 
   options
): number;

Create a slider joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; `axis`: `Vec3`; `friction?`: `number`; `max?`: `number`; `min?`: `number`; `spring?`: `JointSpring`; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.
`options.axis`	`Vec3`	World-space axis; positive motion follows +axis.
`options.friction?`	`number`	Maximum friction force in N.
`options.max?`	`number`	Upper linear limit in metres.
`options.min?`	`number`	Lower linear limit in metres.
`options.spring?`	`JointSpring`	Limit frequency in Hz and damping ratio.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Drawer = prefab({ body: { shape: 'box', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const drawer = ctx.spawn(Drawer, { x: 0, y: 1, z: 0 });
    physics.slider(drawer, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      axis: { x: 0, y: 0, z: 1 },
      min: 0,
      max: 0.6,
    });
  },
});

sphereCast()

sphereCast(
   position, 
   radius, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Cast a sphere.

Parameters

Parameter	Type	Description
`position`	`Vec3`	World-space query centre.
`radius`	`number`	Radius in metres.
`direction`	`Vec3`	Sweep direction; need not be normalised.
`maxDistance`	`number`	Maximum travel in metres.
`mask?`	`CollisionLayers`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	Entity to skip.

Returns

RayHit | null

The closest hit, or null on a miss; hit.distance is the shape travel in metres.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const forward = { x: 0, y: 0, z: 1 };
    const hit = physics.sphereCast(position, 0.5, forward, 2);
    console.log('will the ball fit through this passage?', hit === null);
  },
});

teleport()

teleport(
   entity, 
   x, 
   y, 
   z, 
   rotation?
): 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.
`rotation?`	`Quat`	Optional facing; defaults to identity for existing callers.

Returns

void

Nothing.

player

readonly player: number;

The entity the player block spawned in a single-player game, or 0; in a room, playerEntity(id).

players

readonly players: Players;

Players by id; host, and list in id order. Solo uses seat 0.

rng

readonly rng: Rng;

The seeded generator. Never Math.random.

rules

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

The rules object from defineGame, verbatim.

started

readonly started: boolean;

True after the page's start event, until init; use to gate gameplay.

ui

readonly ui: object;

The game's UI.

events

Get Signature

get events(): readonly UiEvent[];

This tick's UI events in arrival order; the array is reused each tick.

Returns

readonly UiEvent[]

The pooled event array.

clear()

clear(): void;

Clear the UI once; subsequent clears emit nothing.

Returns

void

clicked()

clicked(id): boolean;

Parameters

Parameter	Type	Description
`id`	`string`	Button or clickable card id.

Returns

boolean

Whether it was clicked this tick.

dropped()

dropped(id): UiEvent | null;

Parameters

Parameter	Type	Description
`id`	`string`	Draggable node id.

Returns

UiEvent | null

Its drop event this tick, including the target, or null.

invalidate()

invalidate(): void;

Forget the previous model so the next set emits again.

Returns

void

set()

set(nodes, options?): boolean;

Emit a model only when its value changes, comparing up to 24 levels.

Parameters

Parameter	Type	Description
`nodes`	`UiNode` \| readonly `UiNode`[]	One node or the ordered top-level nodes.
`options?`	{ `theme?`: `UiTheme`; }	Optional theme overrides.
`options.theme?`	`UiTheme`	Theme token overrides.

Returns

boolean

True when JSON will cross this frame.

submitted()

submitted(id): boolean;

Parameters

Parameter	Type	Description
`id`	`string`	Input id.

Returns

boolean

Whether Enter submitted it this tick.

value()

value(id): string | null;

Parameters

Parameter	Type	Description
`id`	`string`	Input id.

Returns

string | null

Latest changed or submitted text across ticks, or null if unedited.

vfx

readonly vfx: object;

Effects and post.

burst()

burst(
   preset, 
   at, 
   options?
): void;

Play a one-shot preset at a world position.

Parameters

Parameter	Type	Description
`preset`	`VfxPreset`	Built-in preset name.
`at`	`Vec3`	World position.
`options?`	`BurstOptions`	Optional overrides.

Returns

void

Nothing.

Example

import { vfx } from 'gameable';
vfx.burst('dust', { x: 0, y: 0, z: 0 });

move()

move(id, at): void;

Move an emitter (or change its entity offset).

Parameters

Parameter	Type	Description
`id`	`number`	Handle from start; 0 is ignored.
`at`	`Vec3`	Position or offset.

Returns

void

Nothing.

Example

import { vfx } from 'gameable';
const id = vfx.start('fire', {});
vfx.move(id, { x: 1, y: 0, z: 0 });

post()

post(settings): void;

Apply partial post settings.

Parameters

Parameter	Type	Description
`settings`	`PostSettings`	Fields to change; reset first restores neutral values.

Returns

void

Nothing.

Example

import { vfx } from 'gameable';
vfx.post({ reset: true, exposure: 1.2 });

start()

start(preset, options): number;

Start an emitter that runs until stopped.

Parameters

Parameter	Type	Description
`preset`	`VfxPreset`	Built-in preset name.
`options`	`StartOptions`	Position or entity attachment and overrides.

Returns

number

A guest-minted effect handle.

Example

import { vfx } from 'gameable';
const id = vfx.start('smoke', { at: { x: 0, y: 0, z: 0 } });
vfx.stop(id);

stop()

stop(id): void;

Stop an emitter.

Parameters

Parameter	Type	Description
`id`	`number`	Handle from start; 0 is ignored.

Returns

void

Nothing.

Example

import { vfx } from 'gameable';
const id = vfx.start('trail', {});
vfx.stop(id);

world

readonly world: object;

The bitecs world, for query and addComponent.

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

playerEntity()

playerEntity(id): number;

A room player's spawned entity, or 0.

Parameters

Parameter	Type
`id`	`number`

Returns

number

spawn()

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

Instantiate a prefab.

Parameters

Parameter	Type
`def`	`PrefabDef`
`position`	`Vec3`
`rotation?`	`Quat`

Returns

number

GameDataEvent

The room's saved game-wide document as JSON.

Properties

data

data: string;

GameError

The error payload of init and restore.

Properties

code

code: ErrorCode;

message

message: string;

GameModeHooks

Mode extension points, independent of actor tick.

Example

const hooks: GameModeHooks<GameModeProps> = {};

Type Parameters

Type Parameter
`P` extends `object`

Methods

onLogout()?

optional onLogout(
   self, 
   controller, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`controller`	`ActorHandle`
`ctx`	`GameContext`

Returns

void

onMatchEnded()?

optional onMatchEnded(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`event`	`Readonly`<`RuleEvent`>
`ctx`	`GameContext`

Returns

void

onMatchStateChanged()?

optional onMatchStateChanged(
   self, 
   state, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`state`	`MatchState`
`ctx`	`GameContext`

Returns

void

onPhaseEnded()?

optional onPhaseEnded(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`event`	`Readonly`<`RuleEvent`>
`ctx`	`GameContext`

Returns

void

onPhaseStarted()?

optional onPhaseStarted(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`event`	`Readonly`<`RuleEvent`>
`ctx`	`GameContext`

Returns

void

onPlayerDied()?

optional onPlayerDied(
   self, 
   victim, 
   killer, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`victim`	`ActorHandle`
`killer`	`ActorHandle`<`object`> \| `null`
`ctx`	`GameContext`

Returns

void

onPostLogin()?

optional onPostLogin(
   self, 
   controller, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`controller`	`ActorHandle`
`ctx`	`GameContext`

Returns

void

onRoundEnded()?

optional onRoundEnded(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`event`	`Readonly`<`RuleEvent`>
`ctx`	`GameContext`

Returns

void

onRoundStarted()?

optional onRoundStarted(
   self, 
   event, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`event`	`Readonly`<`RuleEvent`>
`ctx`	`GameContext`

Returns

void

readyToEndMatch()?

optional readyToEndMatch(self, ctx): boolean;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

boolean

readyToStartMatch()?

optional readyToStartMatch(self, ctx): boolean;

Parameters

Parameter	Type
`self`	`ActorHandle`<`P`>
`ctx`	`GameContext`

Returns

boolean

GameModeProps

Match rules and framework classes.

Example

const rules: Partial<GameModeProps> = { matchTime: 60 };

Properties

allowLateJoin

allowLateJoin: boolean;

autoAssign

autoAssign: "none" | "balanced";

friendlyFire

friendlyFire: boolean;

gameStateClass

gameStateClass: string;

killScore

killScore: number;

lastTeamStanding

lastTeamStanding: boolean;

matchTime

matchTime: number;

minPlayers

minPlayers: number;

phases

phases: readonly object[];

Ordered phases, repeated for each round; an empty list keeps legacy match flow.

playerControllerClass

playerControllerClass: string;

playerStateClass

playerStateClass: string;

respawnDelay

respawnDelay: number;

restartAfter

restartAfter: number;

rounds

rounds: number;

roundsToWin

roundsToWin: number;

scoreToWin

scoreToWin: number;

startDelay

startDelay: number;

teams

teams: readonly object[];

tieBreak

tieBreak: "draw" | "suddenDeath";

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;

GameplayModule

A headless module with snapshot-safe initialization and one fixed-step system.

Example

import type { GameplayModule } from 'gameable';
const module: GameplayModule = { init() {}, system() {} };
console.log(module.system);

Extended by

MatchModule
MoverModule
WalkJumpModule

Properties

init

init: (ctx) => void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

system

system: (ctx) => void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

GameplayPart

The lifecycle every gameplay part shares.

Example

import { createTimers, type GameplayPart } from 'gameable';
const part: GameplayPart = createTimers({ capacity: 4 });
part.reset();

Extended by

Timers
Tweens
Triggers
Damage
Inventory
Abilities
Quests
Waves
Turns

Methods

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

GameSpec

Everything a game declares.

Properties

actions?

optional actions?: Record<string, ActionDecl>;

Named device bindings, compiled at guest creation.

assets?

optional assets?: readonly string[];

Manifest string ids to resolve during init and cache.

features?

optional features?: FeatureSpec;

Engine modules this game needs (featuresOf).

framework?

optional framework?: "default";

Opt in to default match actors, an origin start and match HUD.

init?

optional init?: (ctx) => void;

Extra setup, run after the declarative spawns.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

level?

optional level?: LevelFile;

Level actors: the level main.

levels?

optional levels?: Record<string, LevelFile>;

Named levels, one at a time; ctx.levels.load switches.

limits?

optional limits?: object;

Spawn caps; default 64 per step, 2048 live.

actors?

optional actors?: number;

spawnsPerStep?

optional spawnsPerStep?: number;

player?

optional player?: PlayerSpec;

Player and camera: spawned at solo init, or per room join on the authority.

restore?

optional restore?: (state, options?) => void;

Read back what snapshot returned.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

rules?

optional rules?: Record<string, unknown>;

Arbitrary tuning values, handed back as ctx.rules.

save?

optional save?: object;

Save schema; migrate[n] upgrades version n - 1 to n. Omit for legacy JSON.

migrate?

optional migrate?: Record<number, (data) => unknown>;

version

version: number;

shutdown?

optional shutdown?: (ctx) => void;

Called once before the guest is torn down.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

snapshot?

optional snapshot?: () => unknown;

JSON state folded into snapshot().

Returns

unknown

spawns?

optional spawns?: readonly SpawnSpec[];

Entities to create during init.

startLevel?

optional startLevel?: string;

Level init loads: options' level, else main, else the first.

systems?

optional systems?: readonly (System | SidedSystem)[];

User systems, after the built-ins; { run, on } picks where (default: authority when multiplayer).

update?

optional update?: (ctx) => void;

One more system, after systems.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

world?

optional world?: WorldSpec;

World settings.

GameStateProps

Mode-owned match mirrors; consumers should only read these.

Example

const state: MatchState = gameState()?.props.matchState ?? 'waitingToStart';

Properties

elapsed

readonly elapsed: number;

matchState

readonly matchState: MatchState;

phase

readonly phase: string;

phaseTimeRemaining

readonly phaseTimeRemaining: number;

remaining

readonly remaining: number;

round

readonly round: number;

rulesState

readonly rulesState: "ended" | "inProgress" | "waiting";

Normalized lifecycle for legacy and phased modes: waiting, inProgress or ended.

teamScores

readonly teamScores: readonly number[];

winners

readonly winners: readonly number[];

GateProps

Rising gate tuning.

Example

const props: Partial<GateProps> = { lip: 0.2 };

Extends

DoorCoreProps

Properties

action

action: string;

Inherited from

asset?

optional asset?: string;

Inherited from

autoCloseSeconds

autoCloseSeconds: number;

Inherited from

closePrompt

closePrompt: string;

Inherited from

closeSound

closeSound: string;

Inherited from

colour

colour: [number, number, number];

Inherited from

consumeKey

consumeKey: boolean;

Inherited from

enabled

enabled: boolean;

Inherited from

facingDegrees

facingDegrees: number;

Inherited from

height

height: number;

Closed doorway height in metres.

Inherited from

lip

lip: number;

lockedBy

lockedBy: string;

Inherited from

lockedMessage

lockedMessage: string;

Inherited from

lockedPrompt

lockedPrompt: string;

Inherited from

lockedSound

lockedSound: string;

Inherited from

look

look: "none" | "wood" | "metal";

Inherited from

once

once: boolean;

Inherited from

openPrompt

openPrompt: string;

Inherited from

openSound

openSound: string;

Inherited from

opensWhen

opensWhen: string[];

Inherited from

prompt

prompt: string;

Inherited from

range

range: number;

Inherited from

seconds

seconds: number;

Inherited from

startOpen

startOpen: boolean;

Inherited from

stayOpen

stayOpen: boolean;

Inherited from

thickness

thickness: number;

Leaf thickness in metres.

Inherited from

toggledBy

toggledBy: "proximity" | "interact" | "signal";

Inherited from

width

width: number;

Closed doorway width in metres.

Inherited from

GuestExports.shutdown

GridMovementOptions

Tile stepping settings and synchronous callbacks; callback tiles are borrowed.

Example

const options: GridMovementOptions = { tileSize: 1, stepSeconds: 0.22 };

Properties

blockMask?

optional blockMask?: CollisionLayers;

collision?

optional collision?: 
  | CollisionSetup
  | "NoCollision"
  | "BlockAll"
  | "OverlapAll"
  | "BlockAllDynamic"
  | "OverlapAllDynamic"
  | "IgnoreOnlyPawn"
  | "OverlapOnlyPawn"
  | "Pawn"
  | "Spectator"
  | "CharacterMesh"
  | "PhysicsActor"
  | "Destructible"
  | "InvisibleWall"
  | "InvisibleWallDynamic"
  | "Trigger"
  | "Ragdoll"
  | "Vehicle"
  | "UI";

dims?

optional dims?: 
  | readonly [number, number, number]
  | readonly [number, number];

Capsule radius/straight half height, or box half extents.

directions?

optional directions?: 4 | 8;

interpolation?

optional interpolation?: "linear" | "smoothstep";

origin?

optional origin?: GridTile;

runMultiplier?

optional runMultiplier?: number;

stepSeconds?

optional stepSeconds?: number;

tileSize?

optional tileSize?: number;

turnInPlaceSeconds?

optional turnInPlaceSeconds?: number;

Methods

onBump()?

optional onBump(
   self, 
   tile, 
   hitEntity, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`tile`	`Readonly`<`GridTile`>
`hitEntity`	`number` \| `undefined`
`ctx`	`GameContext`

Returns

void

onStepEnd()?

optional onStepEnd(
   self, 
   tile, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`tile`	`Readonly`<`GridTile`>
`ctx`	`GameContext`

Returns

void

onStepStart()?

optional onStepStart(
   self, 
   tile, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`tile`	`Readonly`<`GridTile`>
`ctx`	`GameContext`

Returns

void

GridState

Borrowed grid state; read without retaining or mutating.

Example

const moving: GridState['moving'] = false;

Properties

bumped

bumped: boolean;

facing

facing: GridDirection;

moving

moving: boolean;

progress

progress: number;

tile

tile: GridTile;

GridTile

Integer tile coordinates.

Example

const tile: GridTile = { x: 2, z: 3 };

Properties

x

x: number;

z

z: number;

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.

rehydrateReload?

optional rehydrateReload?: (state, apply) => () => void;

Dev-only: rehydrate a freshly booted host through normal lifecycle commands.

Parameters

Parameter	Type
`state`	`Uint8Array`
`apply`	(`output`) => `void`

Returns

() => void

Example

guest.rehydrateReload?.(saved, output => applyOutput(adapter, output));

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

restoreAcrossBuild()

restoreAcrossBuild(state): void;

Restore an older build, migrating actor props by name and typeof. Throws snapshot-version-mismatch when a kept prop changes type. This overwrites the realm's shared stores, just like ordinary restore.

Parameters

Parameter	Type	Description
`state`	`ArrayLike`<`number`>	A snapshot from an older build of this game.

Returns

void

Example

nextGuest.restoreAcrossBuild(oldGuest.snapshot());

shutdown()

shutdown(): void;

Returns

void

Inherited from

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;

HingedDoorProps

Hinged leaf tuning, measured in its closed local frame.

Example

const props: Partial<HingedDoorProps> = { hinge: 'right' };

Extends

DoorCoreProps

Extended by

LevelDoorProps

Properties

action

action: string;

Inherited from

asset?

optional asset?: string;

Inherited from

autoCloseSeconds

autoCloseSeconds: number;

Inherited from

closePrompt

closePrompt: string;

Inherited from

closeSound

closeSound: string;

Inherited from

colour

colour: [number, number, number];

Inherited from

consumeKey

consumeKey: boolean;

Inherited from

enabled

enabled: boolean;

Inherited from

facingDegrees

facingDegrees: number;

Inherited from

height

height: number;

Closed doorway height in metres.

Inherited from

hinge

hinge: "left" | "right";

lockedBy

lockedBy: string;

Inherited from

lockedMessage

lockedMessage: string;

Inherited from

lockedPrompt

lockedPrompt: string;

Inherited from

lockedSound

lockedSound: string;

Inherited from

look

look: "none" | "wood" | "metal";

Inherited from

once

once: boolean;

Inherited from

openPrompt

openPrompt: string;

Inherited from

openSound

openSound: string;

Inherited from

opensWhen

opensWhen: string[];

Inherited from

prompt

prompt: string;

Inherited from

range

range: number;

Inherited from

seconds

seconds: number;

Inherited from

startOpen

startOpen: boolean;

Inherited from

stayOpen

stayOpen: boolean;

Inherited from

swingAway

swingAway: boolean;

swingDegrees

swingDegrees: number;

thickness

thickness: number;

Leaf thickness in metres.

Inherited from

toggledBy

toggledBy: "proximity" | "interact" | "signal";

Inherited from

width

width: number;

Closed doorway width in metres.

Inherited from

HitCharacterCmd

A blow on a character: the nearest part of its physics body to at takes an impulse along direction, and the body reacts on the physics. The anim-events hit, fell and recovered on the clip ragdoll say what happened.

Properties

at

at: Vec3;

Where the blow lands, world space.

direction

direction: Vec3;

Which way the blow travels, world space; zero means from the character's front.

entity

entity: number;

strength

strength: HitStrength;

HostApi

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

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

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

jointValue()

jointValue(joint, axis): number | null | undefined;

Joint coordinate, in radians or metres.

Parameters

Parameter	Type
`joint`	`number`
`axis`	`number`

Returns

number | 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

overlapShape()

overlapShape(
   shape, 
   position, 
   rotation, 
   filter, 
   maxResults
): readonly OverlapHit[];

Bodies overlapping a primitive shape.

Parameters

Parameter	Type
`shape`	`QueryShape`
`position`	`Vec3`
`rotation`	`Quat`
`filter`	`QueryFilter`
`maxResults`	`number`

Returns

readonly OverlapHit[]

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

shapeCast()

shapeCast(
   shape, 
   position, 
   rotation, 
   direction, 
   maxDistance, 
   filter
): RayHit | null | undefined;

Sweep a primitive shape, in metres.

Parameters

Parameter	Type
`shape`	`QueryShape`
`position`	`Vec3`
`rotation`	`Quat`
`direction`	`Vec3`
`maxDistance`	`number`
`filter`	`QueryFilter`

Returns

RayHit | null | undefined

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;

players

players: readonly PlayerInput[];

vehicles?

optional vehicles?: Float32Array<ArrayBufferLike>;

Versioned packed vehicle telemetry.

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;

InputMods

Keyboard modifier state. Every key is present on input.

Properties

alt

alt: boolean;

capsLock

capsLock: boolean;

ctrl

ctrl: boolean;

numLock

numLock: boolean;

shift

shift: boolean;

InputState

Everything the host knows about input for one fixed step.

Properties

control?

optional control?: object;

Page-decided absolute direction, final movement axes and last observed spawn. Missing keeps local key/stick and pointer integration.

moveX

moveX: number;

moveY

moveY: number;

pitch

pitch: number;

spawn

spawn: number;

yaw

yaw: number;

focused

focused: boolean;

gamepads

gamepads: readonly GamepadState[];

keys

keys: KeyState;

mods

mods: InputMods;

mouse

mouse: MouseState;

InteractableProps

Interaction tuning. Action is a keyboard/touch action name supported by the input facade; default E.

Example

const props: InteractableProps = {prompt: 'Open', range: 2, facingDegrees: 75, action: 'E', once: false, enabled: true, asset: ''};

Extended by

DoorProps
DoorCoreProps
LeverProps

Properties

action

action: string;

asset?

optional asset?: string;

enabled

enabled: boolean;

facingDegrees

facingDegrees: number;

once

once: boolean;

prompt

prompt: string;

range

range: number;

Inventory

A fixed-slot bag for each owner. Owners are indices 0..owners-1, not entity ids. Counts and amounts are nonnegative safe integers. Moves preserve totals and emit no events. Transfers notify in ascending owner order; clear notifies in ascending item order. Other changes notify once, synchronously, after the whole mutation. Reset and restore do not notify. A transfer to oneself succeeds if the items exist.

Example

import { createInventory, type Inventory } from 'gameable';
const bag: Inventory = createInventory({ owners: 1, slots: 4, items: [{ id: 'key' }] });
bag.add(0, 'key');

Extends

GameplayPart

Methods

add()

add(
   owner, 
   item, 
   amount?
): number;

Fill existing stacks, then empty slots, lowest first; return overflow.

Parameters

Parameter	Type
`owner`	`number`
`item`	`string` \| `number`
`amount?`	`number`

Returns

number

clear()

clear(owner): void;

Empty an owner's bag.

Parameters

Parameter	Type
`owner`	`number`

Returns

void

count()

count(owner, item): number;

Total amount of an item.

Parameters

Parameter	Type
`owner`	`number`
`item`	`string` \| `number`

Returns

number

has()

has(
   owner, 
   item, 
   amount?
): boolean;

Whether at least amount (default 1) is held.

Parameters

Parameter	Type
`owner`	`number`
`item`	`string` \| `number`
`amount?`	`number`

Returns

boolean

item()

item(id): number;

Resolve an item id; unknown ids throw with the known ids.

Parameters

Parameter	Type
`id`	`string`

Returns

number

itemId()

itemId(index): string;

Get an item's id. Invalid indices throw.

Parameters

Parameter	Type
`index`	`number`

Returns

string

move()

move(
   owner, 
   fromSlot, 
   toSlot
): void;

Merge matching stacks; otherwise swap slots. Moving onto itself does nothing.

Parameters

Parameter	Type
`owner`	`number`
`fromSlot`	`number`
`toSlot`	`number`

Returns

void

remove()

remove(
   owner, 
   item, 
   amount?
): boolean;

Remove from highest slots first, atomically; zero always succeeds.

Parameters

Parameter	Type
`owner`	`number`
`item`	`string` \| `number`
`amount?`	`number`

Returns

boolean

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

Inherited from

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

slotCount()

slotCount(owner, slot): number;

Count at a slot, or zero when empty.

Parameters

Parameter	Type
`owner`	`number`
`slot`	`number`

Returns

number

slotItem()

slotItem(owner, slot): number;

Item index at a slot, or -1 when empty.

Parameters

Parameter	Type
`owner`	`number`
`slot`	`number`

Returns

number

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

HingedDoorProps.action

transfer()

transfer(
   fromOwner, 
   toOwner, 
   item, 
   amount
): boolean;

Transfer atomically, only if the source holds and destination fits everything.

Parameters

Parameter	Type
`fromOwner`	`number`
`toOwner`	`number`
`item`	`string` \| `number`
`amount`	`number`

Returns

boolean

InventoryComponentOptions

Bag schema and synchronous notifications. Amounts count bag items, excluding equipment. Identical schemas share storage. Callbacks observe committed state.

Example

const options: InventoryComponentOptions = { slots: 4, items: [{ id: 'key' }] };

Properties

equipSlots?

optional equipSlots?: readonly string[];

Unique equipment slot names; defaults to none.

items

items: readonly object[];

Unique ids, per-slot stack limits (default one), and optional allowed equipment slot.

onInventoryFull?

optional onInventoryFull?: (actor, item, overflow) => void;

Once when an insertion cannot fit, with its overflow; failed atomic operations keep all items.

Parameters

Parameter	Type
`actor`	`ActorHandle`
`item`	`string`
`overflow`	`number`

Returns

void

onItemAdded?

optional onItemAdded?: (actor, item, amount) => void;

Once per successful insertion, with the amount inserted.

Parameters

Parameter	Type
`actor`	`ActorHandle`
`item`	`string`
`amount`	`number`

Returns

void

onItemEquipped?

optional onItemEquipped?: (actor, slot, item) => void;

Once after equipping, with the equipment slot and item id.

Parameters

Parameter	Type
`actor`	`ActorHandle`
`slot`	`string`
`item`	`string`

Returns

void

onItemRemoved?

optional onItemRemoved?: (actor, item, amount) => void;

Once per successful removal, with the amount removed.

Parameters

Parameter	Type
`actor`	`ActorHandle`
`item`	`string`
`amount`	`number`

Returns

void

onItemUnequipped?

optional onItemUnequipped?: (actor, slot, item) => void;

Once after unequipping or replacing equipment.

Parameters

Parameter	Type
`actor`	`ActorHandle`
`slot`	`string`
`item`	`string`

Returns

void

slots

slots: number;

Positive number of bag slots per actor.

JointAxis

JointAxis: radians and metres at the host boundary.

Example

import type { JointAxis } from 'gameable';
const value: JointAxis = { mode: 'locked', min: 0, max: 0 };

Properties

max

max: number;

min

min: number;

mode

mode: JointAxisMode;

JointSpring

JointSpring: radians and metres at the host boundary.

Example

import type { JointSpring } from 'gameable';
const value: JointSpring = { frequency: 2, damping: 1 };

Properties

damping

damping: number;

frequency

frequency: number;

JumpPadProps

Jump launch velocity and optional mesh appearance.

Example

const props: Partial<JumpPadProps> = { launch: [0,12,4] };

Properties

asset

asset: string;

Manifest mesh id; empty means no mesh.

launch

launch: [number, number, number];

Launch velocity in metres/second.

scale

scale: [number, number, number];

Mesh scale only; collider remains in world metres.

tint

tint: [number, number, number];

Mesh RGB material colour.

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>;

LevelActor

One placeable actor. Attached transforms are local to the named parent. Quaternion rotation takes precedence over yaw.

Example

const entry: LevelActor = { class: 'PlayerStart', position: [0, 0, 0] };

Properties

attachTo?

optional attachTo?: string;

class

class: string;

name?

optional name?: string;

Unique within the level. Left out, the actor is still named: Door1, Door2, ... (levelActorNames).

position

position: readonly [number, number, number];

props?

optional props?: Record<string, unknown>;

rotation?

optional rotation?: readonly [number, number, number, number];

scale?

optional scale?: readonly [number, number, number];

Root scale [x, y, z]; attached parts inherit it, a body's dims do not.

tags?

optional tags?: readonly string[];

yaw?

optional yaw?: number;

Degrees about +Y; zero faces +Z.

LevelDoorProps

A door's destination and which players travel through it.

Example

const props: Partial<LevelDoorProps> = { toLevel: 'cave', toPlayerStart: 'stairs' };

Extends

HingedDoorProps

Properties

action

action: string;

Inherited from

asset?

optional asset?: string;

Inherited from

HingedDoorProps.asset

autoCloseSeconds

autoCloseSeconds: number;

Inherited from

HingedDoorProps.autoCloseSeconds

closePrompt

closePrompt: string;

Inherited from

HingedDoorProps.closePrompt

closeSound

closeSound: string;

Inherited from

HingedDoorProps.closeSound

colour

colour: [number, number, number];

Inherited from

HingedDoorProps.colour

consumeKey

consumeKey: boolean;

Inherited from

HingedDoorProps.consumeKey

enabled

enabled: boolean;

Inherited from

HingedDoorProps.enabled

facingDegrees

facingDegrees: number;

Inherited from

HingedDoorProps.facingDegrees

height

height: number;

Closed doorway height in metres.

Inherited from

HingedDoorProps.height

hinge

hinge: "left" | "right";

Inherited from

HingedDoorProps.hinge

lockedBy

lockedBy: string;

Inherited from

HingedDoorProps.lockedBy

lockedMessage

lockedMessage: string;

Inherited from

HingedDoorProps.lockedMessage

lockedPrompt

lockedPrompt: string;

Inherited from

HingedDoorProps.lockedPrompt

lockedSound

lockedSound: string;

Inherited from

HingedDoorProps.lockedSound

look

look: "none" | "wood" | "metal";

Inherited from

HingedDoorProps.look

once

once: boolean;

Inherited from

HingedDoorProps.once

openPrompt

openPrompt: string;

Inherited from

HingedDoorProps.openPrompt

opens

opens: "slide" | "swing";

openSound

openSound: string;

Inherited from

HingedDoorProps.openSound

opensWhen

opensWhen: string[];

Inherited from

HingedDoorProps.opensWhen

prompt

prompt: string;

Inherited from

HingedDoorProps.prompt

range

range: number;

Inherited from

HingedDoorProps.range

requireOpen

requireOpen: boolean;

seconds

seconds: number;

Inherited from

HingedDoorProps.seconds

startOpen

startOpen: boolean;

Inherited from

HingedDoorProps.startOpen

stayOpen

stayOpen: boolean;

Inherited from

HingedDoorProps.stayOpen

swingAway

swingAway: boolean;

Inherited from

HingedDoorProps.swingAway

swingDegrees

swingDegrees: number;

Inherited from

HingedDoorProps.swingDegrees

thickness

thickness: number;

Leaf thickness in metres.

Inherited from

HingedDoorProps.thickness

toggledBy

toggledBy: "proximity" | "interact" | "signal";

Inherited from

HingedDoorProps.toggledBy

toLevel

toLevel: string;

toPlayerStart

toPlayerStart: string;

travel

travel: "player" | "party";

travelPrompt

travelPrompt: string;

width

width: number;

Closed doorway width in metres.

Inherited from

HingedDoorProps.width

LevelFile

Versioned JSON actor placement document. Import premade/user classes before validation.

Example

const level: LevelFile = { format: 1, actors: [] };

Properties

$schema?

optional $schema?: string;

The schema's address, for an editor.

actors

actors: readonly LevelActor[];

format

format: 1;

place?

optional place?: string;

Where this level plays: the manifest id of its world (env.*). Left out, the page's default place. Switching to a level with another place swaps the world.

LevelsFacade

ctx.levels: which levels the game has and which is loaded.

Example

import { levels, type LevelsFacade } from 'gameable';

const facade: LevelsFacade = levels;
console.log(facade.names(), facade.current);

Properties

current

readonly current: string | null;

The loaded level's name, or null when none is.

Methods

load()

load(
   ctx, 
   name, 
   options?
): object;

Unload the loaded level, then place name's actors.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	The game context.
`name`	`string`	A declared level.
`options?`	{ `arrival?`: `string` \| `true`; }	Require the first PlayerStart or a named arrival marker before teardown.
`options.arrival?`	`string` \| `true`	-

Returns

object

The placed actors, as loadLevel returns them.

actors

actors: ActorHandle<object>[];

named

named: Record<string, ActorHandle>;

Throws

When the destination or requested arrival is invalid.

names()

names(): readonly string[];

Every declared level, in declaration order.

Returns

readonly string[]

place()

place(name?): string | null;

The world a level plays in.

Parameters

Parameter	Type	Description
`name?`	`string`	A level; the loaded one when left out.

Returns

string | null

Its place, or null when it has none.

unload()

unload(ctx): void;

Destroy the loaded level's actors with reason levelUnload. Actors from code are removed unless marked session.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	The game context.

Returns

void

LeverProps

Authored lever tuning; a positive resetSeconds makes a momentary button.

Example

const props: Partial<LeverProps> = { resetSeconds: 2, lockedBy: 'key' };

Extends

InteractableProps

Properties

action

action: string;

Inherited from

InteractableProps.action

asset?

optional asset?: string;

Inherited from

InteractableProps.asset

colour

colour: [number, number, number];

consumeKey

consumeKey: boolean;

enabled

enabled: boolean;

Inherited from

InteractableProps.enabled

facingDegrees

facingDegrees: number;

Inherited from

InteractableProps.facingDegrees

lockedBy

lockedBy: string;

lockedMessage

lockedMessage: string;

lockedPrompt

lockedPrompt: string;

offPrompt

offPrompt: string;

once

once: boolean;

Inherited from

InteractableProps.once

onPrompt

onPrompt: string;

prompt

prompt: string;

Inherited from

InteractableProps.prompt

range

range: number;

Inherited from

InteractableProps.range

resetSeconds

resetSeconds: number;

seconds

seconds: number;

startOn

startOn: boolean;

switchSound

switchSound: string;

LoadAssetCmd

Ask the host to start loading an asset.

Properties

asset

asset: number;

priority

priority: number;

LoadLevelOptions

What loadLevel accepts besides the document.

Properties

name?

optional name?: string;

The level's name, written into every actor's source. Defaults to 'main'.

LookAtCmd

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

Properties

entity

entity: number;

target?

optional target?: Vec3;

weight

weight: number;

LoweredCollision

Lowered body fields plus information the current body command cannot carry.

Example

const body: LoweredCollision = lowerCollision('Pawn');

Properties

flags

flags: BodyFlags;

layer

layer: CollisionLayers;

mask

mask: CollisionLayers;

overlapMask

overlapMask: CollisionLayers;

physicsOnly

physicsOnly: boolean;

queryOnly

queryOnly: boolean;

MatchHudModuleOptions

HUD namespace and elapsed-time quantization.

Example

import type { MatchHudModuleOptions } from 'gameable';
const options: MatchHudModuleOptions = { namespace: 'race', secondsStep: 0.1 };
console.log(options.namespace);

Properties

namespace

namespace: string;

secondsStep

secondsStep: number;

MatchModule

The match module and its shared seat state.

Example

import type { MatchModule } from 'gameable';
const inspect = (match: MatchModule) => match.state.phase;
console.log(inspect);

Extends

GameplayModule

Properties

init

init: (ctx) => void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

Inherited from

GameplayModule.init

state

readonly state: object;

checkpoint

checkpoint: Uint8Array;

entity

entity: Uint32Array;

first

first: number;

hitAfter

hitAfter: Float64Array;

knockUntil

knockUntil: Float64Array;

knockX

knockX: Float32Array;

knockZ

knockZ: Float32Array;

loaded

loaded: Uint8Array;

next: number;

phase

phase: string;

place

place: Uint8Array;

ready

ready: Uint8Array;

revision

revision: number;

round

round: number;

since

since: number;

spectator

spectator: Uint8Array;

system

system: (ctx) => void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

Inherited from

GameplayModule.system

MatchModuleOptions

All-ready match deadlines and seat policy.

Example

import type { MatchModuleOptions } from 'gameable';
const options: MatchModuleOptions = { maxPlayers: 1, history: 8, spawns: [[0,3,0]], start: 'all-ready', minPlayers: 2, soloMinPlayers: 1, lateJoin: 'spectate-after-loading', spectatorSpawnZ: 3, loadingSeconds: 20, cardSeconds: 1.5, countdownSeconds: 4.5, limitSeconds: 180, afterFirstSeconds: 90, resultsSeconds: 8 };
console.log(options.maxPlayers);

Properties

afterFirstSeconds

afterFirstSeconds: number;

cardSeconds

cardSeconds: number;

countdownSeconds

countdownSeconds: number;

history

history: number;

lateJoin

lateJoin: "spectate-after-loading";

limitSeconds

limitSeconds: number;

loadingSeconds

loadingSeconds: number;

maxPlayers

maxPlayers: number;

minPlayers

minPlayers: number;

resultsSeconds

resultsSeconds: number;

soloMinPlayers

soloMinPlayers: number;

spawns

spawns: readonly readonly number[][];

spectatorSpawnZ

spectatorSpawnZ: number;

start

start: "all-ready";

MatchPlayerSummary

One logged-in player's public statistics.

Example

const row: MatchPlayerSummary = { seat: 0, name: '', score: 0, kills: 0, deaths: 0, team: 0 };

Properties

deaths

deaths: number;

kills

kills: number;

name

name: string;

score

score: number;

seat

seat: number;

team

team: number;

MatchSummary

Borrowed match model, refreshed after actor hooks each authority or solo step.

Example

ctx.hud.set({ match: matchSummary() });

Properties

elapsed

elapsed: number;

players

players: readonly Readonly<MatchPlayerSummary>[];

remaining

remaining: number;

state

state: MatchState;

winners

winners: readonly number[];

MessageOptions

Options for defineMessage.

Example

const Chat = defineMessage('chat', (p): p is string => typeof p === 'string', { maxBytes: 256 });

Properties

maxBytes?

optional maxBytes?: number;

The largest payload, in UTF-8 bytes of its JSON; 1 to 2,048. Default 2,048, the wire cap.

ModuleCatalog

Gameplay factory metadata in registration order.

Example

const catalog: ModuleCatalog = moduleCatalog();

Properties

modules

modules: ModuleCatalogEntry[];

ModuleCatalogEntry

A detached gameplay factory entry with its public import source.

Example

const entry: ModuleCatalogEntry = moduleCatalog().modules[0];

Extends

ModuleDescription

Properties

aliases

aliases: readonly string[];

Overrides

ModuleDescription.aliases

description

description: string;

Inherited from

ModuleDescription.description

events

events: readonly object[];

Overrides

ModuleDescription.events

example

example: string;

Overrides

ModuleDescription.example

import

import: "gameable";

kind

kind: "module";

name

name: string;

Inherited from

ModuleDescription.name

options

options: Record<string, ModuleOptionMeta>;

Overrides

ModuleDescription.options

ModuleDescription

Authoring metadata registered beside a gameplay factory.

Example

const entry: ModuleDescription = { name: 'custom', category: 'gameplay', description: 'Custom helper.' };

Extended by

ModuleCatalogEntry

Properties

aliases?

optional aliases?: readonly string[];

description

description: string;

events?

optional events?: readonly object[];

example?

optional example?: string;

name

name: string;

options?

optional options?: Record<string, ModuleOptionMeta>;

ModuleOptionMeta

Factory option hints, including callback signatures and actual defaults. Omitted defaults mean required options or optional callbacks without a default.

Example

const option: ModuleOptionMeta = { type: 'number', description: 'Slots.', min: 0 };

Extends

Omit<PropMeta, "type" | "items" | "fields">

Properties

const?

optional const?: boolean;

Restrict a boolean branch to one literal value.

Inherited from

CatalogProp.const

default?

optional default?: string | number | boolean;

description

description: string;

Inherited from

CatalogProp.description

fields?

optional fields?: Record<string, ModuleOptionMeta>;

group?

optional group?: string;

Shared reference table; actor-specific differences remain documented on the actor.

Inherited from

CatalogProp.group

items?

optional items?: ModuleOptionMeta;

max?

optional max?: number;

Inherited from

CatalogProp.max

min?

optional min?: number;

Inherited from

CatalogProp.min

nullable?

optional nullable?: boolean;

Accept null in addition to the described shape.

Inherited from

CatalogProp.nullable

oneOf?

optional oneOf?: readonly PropMeta[];

Inherited from

CatalogProp.oneOf

optional?

optional optional?: boolean;

Allow this field to be omitted from a fixed-shape object.

Inherited from

CatalogProp.optional

type?

optional type?: 
  | "string"
  | "number"
  | "boolean"
  | "object"
  | "function"
  | "color"
  | "vec3"
  | "array"
  | "enum";

unit?

optional unit?: string;

Inherited from

CatalogProp.unit

values?

optional values?: readonly string[];

Inherited from

CatalogProp.values

MotionEvent

What the movement system says of a character.

Properties

amount

amount: number;

For arrived: how far from the spot asked it stands, metres (for 'face': how far from the facing asked, radians). For limited: the speed it is given, metres a second.

entity

entity: number;

facing

facing: number;

The way the character faces there, radians about +Y (0 faces +Z): where a walk left it.

kind

kind: 
  | "limited"
  | "failed"
  | "ready"
  | "arrived"
  | "started"
  | "contact"
  | "release"
  | "landed"
  | "done";

ready (its motion set has the body), arrived (a walk to a spot got there), an action's moments (started, contact, release, landed, done), or failed.

limb

limb: number;

The limb (0 left hand, 1 right hand, 2 left foot, 3 right foot), or -1.

name

name: string;

The action's name; the set's name for ready; 'walk' for a walk to a spot, 'face' for a turn on the spot; the gait ('walk', 'run') for limited.

object

object: number;

The object's id as the game gave it, or -1.

point

point: Vec3;

Where, world space: the contact, the hand at a release, where the walk arrived.

reason

reason: string;

Why, for failed; empty otherwise.

velocity

velocity: Vec3;

How fast that point moves, world metres a second: a release gives the object this.

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;

MoveQuery

Blocking-world adapter. Returned records may be reused by the next query. Probes/rays enable the exact shrunken-capsule floor algorithm; basic adapters use full sweeps.

Example

const empty: MoveQuery = { sweep: () => null, overlap: () => [] };

Methods

overlap()

overlap(at, inflation?): readonly Penetration[];

Parameters

Parameter	Type
`at`	`Vec3`
`inflation?`	`number`

Returns

readonly Penetration[]

raycast()?

optional raycast(from, delta): SweepHit | null;

Parameters

Parameter	Type
`from`	`Vec3`
`delta`	`Vec3`

Returns

SweepHit | null

sweep()

sweep(from, delta): SweepHit | null;

Parameters

Parameter	Type
`from`	`Vec3`
`delta`	`Vec3`

Returns

SweepHit | null

sweepCapsule()?

optional sweepCapsule(
   from, 
   delta, 
   capsule
): SweepHit | null;

Parameters

Parameter	Type
`from`	`Vec3`
`delta`	`Vec3`
`capsule`	`Capsule`

Returns

SweepHit | null

sweepFloorBox()?

optional sweepFloorBox(
   from, 
   delta, 
   radius, 
   halfHeight, 
   rotated
): SweepHit | null;

Parameters

Parameter	Type
`from`	`Vec3`
`delta`	`Vec3`
`radius`	`number`
`halfHeight`	`number`
`rotated`	`boolean`

Returns

SweepHit | null

MoverModule

Kinematic authority system and declarative course spawns.

Example

import type { MoverModule } from 'gameable';
const inspect = (movers: MoverModule) => movers.spawns.length;
console.log(inspect);

Extends

GameplayModule

Properties

init

init: (ctx) => void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

Inherited from

GameplayModule.init

spawns

readonly spawns: readonly SpawnSpec[];

system

system: (ctx) => void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

Inherited from

GameplayModule.system

MoverModuleOptions

Explicit course bodies, motion and contact policies.

Example

import type { MoverModuleOptions } from 'gameable';
const inspect = (options: MoverModuleOptions) => options.movers.length;
console.log(inspect);

Properties

contact

contact: object;

carryTolerance

carryTolerance: number;

foot

foot: number;

floors

floors: readonly readonly number[][];

knock

knock: object;

cooldown

cooldown: number;

duration

duration: number;

margin

margin: number;

speed

speed: number;

movers

movers: readonly object[];

palette

palette: readonly readonly number[][];

MovingPlatformProps

Moving platform data; points are relative to spawn. Wait occurs at path endpoints.

Example

const props: Partial<MovingPlatformProps> = {points: [[4, 0, 0]], seconds: 3, mode: 'pingPong'};

Extends

WaypointMovementOptions

Properties

asset

asset: string;

mode

mode: "loop" | "once" | "pingPong";

Inherited from

WaypointMovementOptions.mode

points

points: readonly (readonly [number, number, number] | Vec3)[];

Inherited from

WaypointMovementOptions.points

seconds?

optional seconds?: number;

Inherited from

WaypointMovementOptions.seconds

speed?

optional speed?: number;

Inherited from

WaypointMovementOptions.speed

startPaused?

optional startPaused?: boolean;

Inherited from

WaypointMovementOptions.startPaused

waitSeconds?

optional waitSeconds?: number;

Inherited from

WaypointMovementOptions.waitSeconds

MultiplayerOptions

Options for the multiplayer feature.

Properties

maxPlayers?

optional maxPlayers?: number;

Seats in a room, ids 0..maxPlayers - 1. Default 8. roomSeats reads it, for the guest's player slots and for the room's door alike.

predict?

optional predict?: boolean;

Predict each page's own character body: the page steps its own Jolt world (the level's static colliders and the body its client guest adds for its player) so the player moves on key-down, and the authority's rows correct it. Default false. See the multiplayer concept page.

sendHz?

optional sendHz?: number;

Transform rows per second sent to each player. Default 20.

MusicOptions

Music playback options.

Example

`music.play('theme', { bpm: 120 });`

Extended by

StemOptions

Properties

beatsPerBar?

optional beatsPerBar?: number;

Beats in each bar; defaults to four.

bpm?

optional bpm?: number;

Beats per minute; zero disables the clock.

fadeMs?

optional fadeMs?: number;

Crossfade duration.

firstBeat?

optional firstBeat?: number;

Seconds to beat zero.

loop?

optional loop?: boolean;

Loop playback.

start?

optional start?: BeatQuantize;

Starting grid; defaults to now.

volume?

optional volume?: number;

Linear gain.

MusicTrackEvent

music-track-event payload.

Example

`const value: MusicTrackEvent = { index: 0, asset: 1 };`

Properties

asset

asset: number;

Manifest asset handle.

index

index: number;

Playlist track index.

NavGrid

A grid over the level: built once, queried every frame, edited by obstacles.

Extends

NavQuery

Properties

agentRadius

readonly agentRadius: number;

Agent radius the walkable space was shrunk by.

Inherited from

NavQuery.agentRadius

cellSize

readonly cellSize: number;

cols

readonly cols: number;

revision

readonly revision: number;

Topology/area revision; edits invalidate cached paths and integration fields.

rows

readonly rows: number;

Methods

addCostArea()

addCostArea(
   x, 
   z, 
   halfX, 
   halfZ, 
   cost
): number;

Add a rectangular cell-centre area. Entry costs multiply by cost (finite, >= 1). Overlapping areas take the maximum multiplier. Returns -1 at capacity/invalid input.

Parameters

Parameter	Type
`x`	`number`
`z`	`number`
`halfX`	`number`
`halfZ`	`number`
`cost`	`number`

Returns

number

Example

const mud = grid.addCostArea(3, 4, 2, 1, 3);

addLink()

addLink(
   ax, 
   az, 
   bx, 
   bz, 
   options?
): number;

Add an extra edge only when both endpoint cells are walkable. Exact XZ endpoints appear consecutively in findPath. Endpoint heights default to their cells; optional startY/endY override the sampled heights for authored jump/ladder points. radius limits endpoint-to-cell-centre distance (default cellSize); cost is an absolute traversal cost in metres (default endpoint distance, minimum 0). Flow fields integrate areas only; link traversal requires a flagged path follower.

Parameters

Parameter	Type
`ax`	`number`
`az`	`number`
`bx`	`number`
`bz`	`number`
`options?`	{ `bidirectional?`: `boolean`; `cost?`: `number`; `endY?`: `number`; `radius?`: `number`; `startY?`: `number`; }
`options.bidirectional?`	`boolean`
`options.cost?`	`number`
`options.endY?`	`number`
`options.radius?`	`number`
`options.startY?`	`number`

Returns

number

Example

const jump = grid.addLink(1, 2, 5, 2, { bidirectional: false });

addObstacle()

addObstacle(
   x, 
   z, 
   halfX, 
   halfZ
): number;

Block a rectangle (inflated by the agent radius) until removed.

Parameters

Parameter	Type
`x`	`number`
`z`	`number`
`halfX`	`number`
`halfZ`	`number`

Returns

number

An obstacle id, or -1 when maxObstacles are alive.

buildFlat()

buildFlat(y?): void;

Make every cell walkable floor at height y (default 0). For 2D, tests and box-built levels.

Parameters

Parameter	Type
`y?`	`number`

Returns

void

buildFromPhysics()

buildFromPhysics(mask?): number;

Build from the level's static colliders: one downward ray per cell, one raycastBatch per row. Call from init, never per frame.

Parameters

Parameter	Type	Description
`mask?`	`CollisionLayers`	Layers that count as floor and walls. Default `{ staticGeometry: true }`.

Returns

number

How many cells an agent may stand on. 0 means no floor was found: the level's colliders are not loaded yet, or a headless test's mock host has no physics.

createFlowField()

createFlowField(): FlowField;

A flow field over this grid. Allocates: make it in init.

Returns

FlowField

findPath()

findPath(
   fromX, 
   fromZ, 
   toX, 
   toZ, 
   out, 
   linkFlags?
): number;

Cheapest walkable path. Uniform grids are string-pulled; weighted routes retain turning cell waypoints so smoothing cannot shortcut through expensive areas.

Parameters

Parameter	Type	Description
`fromX`	`number`	Start x; snapped to the nearest walkable cell when blocked.
`fromZ`	`number`	Start z.
`toX`	`number`	Goal x; snapped likewise.
`toZ`	`number`	Goal z.
`out`	`Float32Array`	Receives `x, y, z` per point, start first, goal last.
`linkFlags?`	`Uint8Array`<`ArrayBufferLike`>	Optional caller-owned flags, cleared and filled per query: 1 at a link start, followed by its exact end point. Copy flags with the path before another query. A truncated path never ends with an unmatched link start.

Returns

number

How many points were written; 0 when there is no path.

Inherited from

NavQuery.findPath

hasPath()

hasPath(
   fromX, 
   fromZ, 
   toX, 
   toZ
): boolean;

Parameters

Parameter	Type
`fromX`	`number`
`fromZ`	`number`
`toX`	`number`
`toZ`	`number`

Returns

boolean

Whether a walkable path joins the two points (snapped like findPath).

Inherited from

NavQuery.hasPath

heightAt()

heightAt(x, z): number;

Parameters

Parameter	Type	Description
`x`	`number`	World x.
`z`	`number`	World z.

Returns

number

Floor height there, or NaN outside the grid or where there is no floor.

Inherited from

NavQuery.heightAt

isWalkable()

isWalkable(x, z): boolean;

Parameters

Parameter	Type	Description
`x`	`number`	World x.
`z`	`number`	World z.

Returns

boolean

Whether an agent centre may stand there.

Inherited from

NavQuery.isWalkable

lineOfSight()

lineOfSight(
   ax, 
   az, 
   bx, 
   bz
): boolean;

Parameters

Parameter	Type
`ax`	`number`
`az`	`number`
`bx`	`number`
`bz`	`number`

Returns

boolean

Whether a straight walk from a to b stays on walkable, connected cells.

Inherited from

NavQuery.lineOfSight

nearestWalkable()

nearestWalkable(
   x, 
   z, 
   out
): boolean;

Parameters

Parameter	Type	Description
`x`	`number`	World x.
`z`	`number`	World z.
`out`	`NavPoint`	Receives the nearest walkable cell centre.

Returns

boolean

false when nothing walkable is within the search radius.

Inherited from

NavQuery.nearestWalkable

removeCostArea()

removeCostArea(id): void;

Remove an area; unknown ids are ignored.

Parameters

Parameter	Type
`id`	`number`

Returns

void

Example

grid.removeCostArea(mud);

removeLink()

removeLink(id): void;

Remove a link; unknown ids are ignored.

Parameters

Parameter	Type
`id`	`number`

Returns

void

Example

grid.removeLink(jump);

removeObstacle()

removeObstacle(id): void;

Unblock what addObstacle blocked. Unknown ids are ignored.

Parameters

Parameter	Type
`id`	`number`

Returns

void

NavGridOptions

How a nav grid covers the level. Every field but min and max has a default.

Properties

agentRadius?

readonly optional agentRadius?: number;

Radius of the agents the grid is for; walkable space is shrunk by it. Default 0.4.

cellSize?

readonly optional cellSize?: number;

Cell edge in metres. Default 0.5.

height?

readonly optional height?: readonly [number, number];

Vertical range [minY, maxY] probed by NavGrid.buildFromPhysics. Default [-10, 50].

max

readonly max: readonly [number, number];

Opposite corner, [x, z].

maxClimb?

readonly optional maxClimb?: number;

Highest step between neighbouring cells an agent can walk up or down. Default 0.4.

maxCostAreas?

readonly optional maxCostAreas?: number;

Most cost areas alive at once. Default 64.

maxLinks?

readonly optional maxLinks?: number;

Most links alive at once. Default 32.

maxObstacles?

readonly optional maxObstacles?: number;

Most obstacles alive at once. Default 256.

maxPathPoints?

readonly optional maxPathPoints?: number;

Most points one path can hold; longer paths are cut. Default 256.

maxSlope?

readonly optional maxSlope?: number;

Steepest walkable floor, in degrees. Default 45.

min

readonly min: readonly [number, number];

World-space corner of the covered area, [x, z].

NavigationBoundsProps

Grid bounds and agent tuning, in metres and degrees.

Example

const props: Partial<NavigationBoundsProps> = { build: 'flat', cellSize: 0.5 };

Properties

agentRadius

agentRadius: number;

build

build: "flat" | "physics";

cellSize

cellSize: number;

halfExtents

halfExtents: [number, number, number];

maxClimb

maxClimb: number;

maxSlope

maxSlope: number;

NavigationLinkProps

A connection from the actor position to a relative endpoint. The path and teleport preserve both authored endpoint heights.

Example

const props: NavigationLinkProps = { end: [4, 0, 0], bidirectional: false, cost: 4 };

Properties

bidirectional

bidirectional: boolean;

cost

cost: number;

end

end: [number, number, number];

NavigationModifierProps

Axis-aligned blocking or weighted area dimensions.

Example

const props: NavigationModifierProps = { halfExtents: [1, 2, 3], areaClass: 'null', cost: 3 };

Properties

areaClass

areaClass: "null" | "costly";

cost

cost: number;

halfExtents

halfExtents: [number, number, number];

NavPoint

A point on the ground plane, written in place by queries.

Properties

x

x: number;

z

z: number;

NavQuery

The query side every navigation user needs. A nav grid implements it; a baked navmesh may later implement it too.

Extended by

NavGrid

Properties

agentRadius

readonly agentRadius: number;

Agent radius the walkable space was shrunk by.

Methods

findPath()

findPath(
   fromX, 
   fromZ, 
   toX, 
   toZ, 
   out, 
   linkFlags?
): number;

Cheapest walkable path. Uniform grids are string-pulled; weighted routes retain turning cell waypoints so smoothing cannot shortcut through expensive areas.

Parameters

Parameter	Type	Description
`fromX`	`number`	Start x; snapped to the nearest walkable cell when blocked.
`fromZ`	`number`	Start z.
`toX`	`number`	Goal x; snapped likewise.
`toZ`	`number`	Goal z.
`out`	`Float32Array`	Receives `x, y, z` per point, start first, goal last.
`linkFlags?`	`Uint8Array`<`ArrayBufferLike`>	Optional caller-owned flags, cleared and filled per query: 1 at a link start, followed by its exact end point. Copy flags with the path before another query. A truncated path never ends with an unmatched link start.

Returns

number

How many points were written; 0 when there is no path.

hasPath()

hasPath(
   fromX, 
   fromZ, 
   toX, 
   toZ
): boolean;

Parameters

Parameter	Type
`fromX`	`number`
`fromZ`	`number`
`toX`	`number`
`toZ`	`number`

Returns

boolean

Whether a walkable path joins the two points (snapped like findPath).

heightAt()

heightAt(x, z): number;

Parameters

Parameter	Type	Description
`x`	`number`	World x.
`z`	`number`	World z.

Returns

number

Floor height there, or NaN outside the grid or where there is no floor.

isWalkable()

isWalkable(x, z): boolean;

Parameters

Parameter	Type	Description
`x`	`number`	World x.
`z`	`number`	World z.

Returns

boolean

Whether an agent centre may stand there.

lineOfSight()

lineOfSight(
   ax, 
   az, 
   bx, 
   bz
): boolean;

Parameters

Parameter	Type
`ax`	`number`
`az`	`number`
`bx`	`number`
`bz`	`number`

Returns

boolean

Whether a straight walk from a to b stays on walkable, connected cells.

nearestWalkable()

nearestWalkable(
   x, 
   z, 
   out
): boolean;

Parameters

Parameter	Type	Description
`x`	`number`	World x.
`z`	`number`	World z.
`out`	`NavPoint`	Receives the nearest walkable cell centre.

Returns

boolean

false when nothing walkable is within the search radius.

NetFacade

The ctx.net facade, one per guest.

Example

function votes(ctx: GameContext): void {
  if (!ctx.net.isAuthority) return;
  for (const vote of ctx.net.messages(Vote)) {
    ctx.net.send('voted', { by: vote.player, for: vote.payload.for });
  }
  ctx.net.local(() => ctx.audio.play('tick')); // never sent to a player
}

Properties

stats

readonly stats: NetStats;

Counters since init.

Accessors

isAuthority

Get Signature

get isAuthority(): boolean;

Returns

boolean

True on the authority and in a single-player game.

localPlayer

Get Signature

get localPlayer(): number;

Returns

number

The player this page belongs to on a client; 0 elsewhere.

predicts

Get Signature

get predicts(): boolean;

Returns

boolean

True on a client page that actually predicts its own character body (the client loop's own predict option, not merely the game's declared features.multiplayer.predict). False on the authority and in solo.

role

Get Signature

get role(): NetRole;

Returns

NetRole

Where this guest runs.

soloRoom

Get Signature

get soloRoom(): boolean;

Identify the authority that Play Solo runs in this page.

Example

if (ctx.net.soloRoom) ctx.net.setPhase('loading');

Returns

boolean

True for Play Solo’s in-page authority.

Methods

beginTick()

beginTick(): void;

Start a tick: this tick's messages are read afresh. Runtime only.

Returns

void

local()

local(fn): void;

Run fn with every command it queues routed to frame-output.local-commands: applied where this guest runs, never sent to a player. Nested calls stay local; a throw still restores the network buffer. Allocates nothing.

Parameters

Parameter	Type	Description
`fn`	() => `void`	The code whose commands stay local.

Returns

void

messages()

messages<T>(message): readonly NetMessage<T>[];

This tick's validated messages for one definition, in arrival order.

A payload over the definition's maxBytes, not JSON, or failing its check is dropped and counted in stats.dropped, never thrown at a system; the rest count in stats.received. The list and its entries are pooled and refilled each tick: read them inside the tick, never retain them. Reading the same name twice in a tick counts nothing twice.

A bare name (deprecated) reads the same list without a check, unless the name's definition has been read before in this run; it caps at 2,048 bytes.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`message`	`string` \| `MessageDef`<`T`>	The definition, or a bare message name.

Returns

readonly NetMessage<T>[]

The messages, { player, payload }.

reset()

reset(): void;

Forget the counters and every cached message list. init only.

Returns

void

send()

Call Signature

send<T>(
   message, 
   payload, 
   options?
): void;

Send a game message: from the authority to one player or all of them, from a client up to the authority (to is ignored there).

Pass a defineMessage definition to check the payload with its guard and cap it at its maxBytes before it leaves; a bare name (deprecated) checks only the 2,048-byte wire cap.

The payload is serialised with JSON.stringify, so a tick that sends allocates that one string; a tick that sends nothing allocates nothing. undefined sends null.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`message`	`MessageDef`<`T`>	The definition, or a bare message name.
`payload`	`T`	Anything JSON-serialisable; at most `maxBytes` (2,048) as UTF-8 JSON.
`options?`	`SendOptions`	`to` one player, and `reliable` (default true). A payload that does not serialise (a function or a symbol), fails the definition's check, or whose JSON is over the cap sends nothing and counts in `stats.unsent`; it never throws, since a throwing system fails the tick.

Returns

void

Call Signature

send(
   name, 
   payload, 
   options?
): void;

Send a game message: from the authority to one player or all of them, from a client up to the authority (to is ignored there).

Pass a defineMessage definition to check the payload with its guard and cap it at its maxBytes before it leaves; a bare name (deprecated) checks only the 2,048-byte wire cap.

The payload is serialised with JSON.stringify, so a tick that sends allocates that one string; a tick that sends nothing allocates nothing. undefined sends null.

Parameters

Parameter	Type	Description
`name`	`string`	-
`payload`	`unknown`	Anything JSON-serialisable; at most `maxBytes` (2,048) as UTF-8 JSON.
`options?`	`SendOptions`	`to` one player, and `reliable` (default true). A payload that does not serialise (a function or a symbol), fails the definition's check, or whose JSON is over the cap sends nothing and counts in `stats.unsent`; it never throws, since a throwing system fails the tick.

Returns

void

setPhase()

setPhase(word): void;

Say what the room is doing, in a word (lobby, playing, voting), for the public room list beside its code and seats. Authority only: on a client, and in a game with no room, it does nothing. The same word again sends nothing and allocates nothing; a new one sends the reserved message aos:phase, which the room server reads and never forwards to a player.

Parameters

Parameter	Type	Description
`word`	`string`	1 to 32 ASCII letters, digits or dashes. Anything else sends nothing, counts in `stats.unsent` and is logged once; it never throws.

Returns

void

Example

function lobby(ctx: GameContext): void {
  ctx.net.setPhase(started ? 'playing' : 'lobby');
}

NetMessage

What messages hands back: one player's message, its payload parsed.

Example

for (const m of ctx.net.messages(Vote)) tally(m.player, m.payload.for);

Type Parameters

Type Parameter
`T`

Properties

payload

readonly payload: T;

The JSON payload, parsed.

player

readonly player: number;

The sender.

NetMessageEvent

A game message a player sent, delivered to the authority on its next tick.

Named NetMessageEvent rather than the WIT's message-event so it never shadows the DOM's MessageEvent in a page that imports both.

Properties

name

name: string;

payload

payload: string;

JSON.

player

player: number;

The sender.

NetStats

Counters a game or the debug overlay can read.

Example

ctx.hud.set({ dropped: ctx.net.stats.dropped, received: ctx.net.stats.received });

Properties

dropped

dropped: number;

Messages read and dropped: over their maxBytes, not JSON, or failing their defineMessage check. A payload over 2,048 bytes is dropped by the room before it reaches the guest, and is not counted here.

received

received: number;

Messages read and handed to a system.

unsent

unsent: number;

ctx.net.send calls since init that sent nothing: the payload failed its check, did not serialise, or was over the cap. Never thrown, because a throw fails the tick and enough of them kill the guest for the room.

OverlapHit

One body overlapping a query volume.

Properties

body

body: number;

depth

depth: number;

entity

entity: number;

point

point: Vec3;

Deepest contact point on the other body for shape overlaps; bounds centre if unavailable.

PathPreview

Caller-owned path preview, with world-space endpoint and budget marker.

Example

const result: PathPreview = { count: 0, length: 0, reachable: false, endX: 0, endZ: 0, budgetX: 0, budgetZ: 0, withinBudget: false };

Properties

budgetX

budgetX: number;

budgetZ

budgetZ: number;

count

count: number;

endX

endX: number;

endZ

endZ: number;

length

length: number;

reachable

reachable: boolean;

withinBudget

withinBudget: boolean;

Penetration

Minimum translation out of an obstacle.

Example

const overlap: Penetration = { normal: {x:1,y:0,z:0}, depth: 0.1, entity: 2 };

Properties

depth

depth: number;

entity

entity: number;

isPawn?

optional isPawn?: boolean;

normal

normal: Vec3;

PhysicsJointOptions

Joint settings in degrees and metres.

Example

const opts: PhysicsJointOptions = { kind: 'hinge' };

Extends

ComponentOptions

Properties

actorA?

optional actorA?: string;

actorB?

optional actorB?: string;

attach?

optional attach?: string;

Parent component name; defaults to root for non-root components.

Inherited from

axis?

optional axis?: readonly [number, number, number];

kind

kind: ConstraintKind;

max?

optional max?: number;

min?

optional min?: number;

motor?

optional motor?: object;

maxForce

maxForce: number;

mode

mode: MotorMode;

target

target: number;

offset?

optional offset?: readonly [number, number, number];

Translation in the parent's space.

Inherited from

rotation?

optional rotation?: Quat;

Local quaternion, default identity.

Inherited from

scale?

optional scale?: readonly [number, number, number];

Local per-axis scale, default one.

Inherited from

spring?

optional spring?: JointSpring;

PhysicsJointProps

Level-friendly joint settings; null limits leave the joint free.

Example

const props: Partial<PhysicsJointProps> = { actorA: 'door' };

Properties

actorA

actorA: string;

actorB

actorB: string;

axis

axis: readonly [number, number, number];

kind

kind: ConstraintKind;

max

max: number | null;

min

min: number | null;

motorMaxForce

motorMaxForce: number;

motorMode

motorMode: MotorMode;

motorTarget

motorTarget: number;

PickupProps

Pickup tuning in level data.

Example

const props: PickupProps = { give: {heal: 25}, respawnSeconds: 10, spin: 90, bob: 0.1, asset: '' };

Properties

asset

asset: string;

bob

bob: number;

give

give: PickupGive;

respawnSeconds

respawnSeconds: number;

spin

spin: number;

PlaceholderSpec

A shape the host draws for a prefab with no body and no asset, such as a collision: 'none' actor box. It makes no physics body. Kept out of PrefabSpec: actors set it, script authors never need to.

Properties

placeholder?

optional placeholder?: Pick<BodySpec, "shape" | "dims">;

Shape and dimensions to draw.

PlacingModuleOptions

Bounded finish plane, with ascending-seat ties.

Example

import type { PlacingModuleOptions } from 'gameable';
const options: PlacingModuleOptions = { axis: 'z', direction: 'decreasing', at: -68, maxAbsX: 5, minY: 2, maxY: 6, tieBreak: 'seat', requiresAllCheckpoints: false, freezeFinishers: true };
console.log(options.at);

Properties

at

at: number;

axis

axis: "z";

direction

direction: "decreasing";

freezeFinishers

freezeFinishers: boolean;

maxAbsX

maxAbsX: number;

maxY

maxY: number;

minY

minY: number;

requiresAllCheckpoints

requiresAllCheckpoints: false;

tieBreak

tieBreak: "seat";

PlatformingOptions

Platforming tuning in metres and seconds. Requires a physics character body.

Example

const abilities: PlatformingOptions = { coyoteSeconds: 0.12, dashSpeed: 14 };

Properties

coyoteSeconds?

optional coyoteSeconds?: number;

dashAction?

optional dashAction?: string;

dashCooldown?

optional dashCooldown?: number;

dashSeconds?

optional dashSeconds?: number;

dashSpeed?

optional dashSpeed?: number;

jumpAction?

optional jumpAction?: string;

jumpBufferSeconds?

optional jumpBufferSeconds?: number;

wallJumpSpeed?

optional wallJumpSpeed?: number;

wallProbeDistance?

optional wallProbeDistance?: number;

wallSlideSpeed?

optional wallSlideSpeed?: number;

PlayerHandle

One player: who they are, the entity definition.player spawned for them, and facades that read their input and write their own camera and HUD.

Example

for (const [id, p] of ctx.players) {
  if (p.input.pressed('Space')) jump(p.entity);
  p.hud.set({ name: p.name, id });
}

Properties

camera

readonly camera: object;

This player's camera: every write queues one set-player-camera per tick.

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;

Returns

CameraState

fight()

fight(shot): void;

Parameters

Parameter	Type	Description
`shot`	`FightShotOptions`	The two fighters and the moment.

Returns

void

Nothing.

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.

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(point): void;

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

Parameters

Parameter	Type	Description
`point`	`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.

hud

readonly hud: object;

This player's HUD: a changed model queues a set-player-hud.

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.

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.

id

readonly id: number;

The player id this slot belongs to.

input

readonly input: object;

This player's keys, mouse and gamepads, read like input.

touch

touch: object;

Fingers on a touch screen, as the host's touch layer packs them: the first finger is the pointer (mouse), a tap is pressed('Tap'), and the thumb sticks, the pinch and the turn are here.

touch.active

Get Signature

get active(): boolean;

Is a finger on the screen? (The touch pad is connected.)

Returns

boolean

True while any finger is down.

touch.pinch

Get Signature

get pinch(): number;

Two fingers' pinch this step, as a scale factor: over 1 the fingers moved apart (zoom in), under 1 together, exactly 1 with no pinch.

Returns

number

The scale factor.

touch.turn

Get Signature

get turn(): number;

Two fingers' turn this step, in radians, counter-clockwise on the screen positive.

Returns

number

The turn.

touch.stick()

stick(side): Axis2;

A thumb stick's push.

Parameters

Parameter	Type	Description
`side`	`"left"` \| `"right"`	The left stick (movement) or the right one (the camera).

Returns

A pooled { x, y }, -1..1, y up the screen positive. Never retain it.

control

Get Signature

get control(): Readonly<NonNullable<InputState["control"]>>;

Received page control for this frame. Owned by the SDK; read during the tick.

Returns

Readonly<NonNullable<InputState["control"]>>

The control state received with this input sequence.

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

The modifiers for this frame.

mouse

Get Signature

get mouse(): MouseState;

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

Returns

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

action()

action(name): ActionState;

Read a declared button into pooled storage. Unknown names throw.

Parameters

Parameter	Type	Description
`name`	`string`	Declared button action name.

Returns

Pooled button state; read immediately.

axis2()

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

Parameters

Parameter	Type	Default value	Description
`negX`	`string`	`undefined`	Declared axis name, or key driving x negative, e.g. `'A'`.
`posX?`	`string`	`undefined`	Key that drives x positive, for example `'D'`.
`negY?`	`string`	`undefined`	Key that drives y negative, for example `'S'`.
`posY?`	`string`	`undefined`	Key that drives y positive, for example `'W'`.
`stick?`	`StickSide`	`'left'`	Which thumb stick to add, `'left'` by default.

Returns

PrefabSpec.components

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.

lanes

readonly lanes: InputLanes;

The decoded input this handle's input reads. Internal.

present

present: boolean = false;

In this step's frame-input.players. Internal.

seq

seq: number = 0;

The input sequence number this step consumed.

spawn

spawn: number = 0;

The current authoritative camera reset generation (u16).

Accessors

connected

Get Signature

get connected(): boolean;

Returns

boolean

True between this player's player-joined and player-left.

data

Get Signature

get data(): unknown;

Returns

unknown

The player's document: the one the room loaded at join, then whatever ctx.data.save or a finished exchange made it; null for none.

entity

Get Signature

get entity(): number;

Returns

number

The entity this player controls: the one definition.player spawned at join, or the last one possessed; 0 for none (also after that entity is despawned).

isHost

Get Signature

get isHost(): boolean;

Returns

boolean

True for the host (ctx.players.host): the first joiner, until they leave; then the lowest seat still joined.

joinedAt

Get Signature

get joinedAt(): number | null;

Returns

number | null

The server's clock when the room loaded this player's document, in ms since the epoch, or null when the room has no store. The guest has no clock of its own (now-ms counts from engine start), so this is the one wall time it gets: add ctx.elapsed since the join to it.

name

Get Signature

get name(): string;

Returns

string

The display name the room gave at join, or ''.

savedAt

Get Signature

get savedAt(): number | null;

Returns

number | null

When the store last wrote the document handed over at join, in ms since the epoch by the server's clock, or null when there was none. Offline time is joinedAt - savedAt.

Methods

forgetEntity()

forgetEntity(entity): void;

The possessed entity was despawned: the player controls none. The host clears its own mapping on the despawn, so nothing is sent.

Parameters

Parameter	Type	Description
`entity`	`number`	A despawned entity.

Returns

void

integrateLook()

integrateLook(): void;

Apply received absolute look in the room, or integrate pointer movement on the page and for inputs without control. Allocates nothing.

Returns

void

join()

join(name, data): void;

The player took this seat. Parses the saved document: a join-tick allocation.

Parameters

Parameter	Type	Description
`name`	`string`	The display name.
`data`	`string` \| `null` \| `undefined`	The room's `{ doc, savedAt, now }` as JSON, when it has a store (a bare document is taken as the doc).

Returns

void

leave()

leave(): void;

The player left; the caller has already despawned PlayerHandle.entity.

Returns

void

possess()

possess(entity): void;

Make this player control another entity: a respawn, a vehicle, a class swap. On the authority it queues a set-player-entity, so the room follows the player there (relevancy) and their client learns which entity is theirs. Despawning the entity later leaves the player with none until the next possess. A different nonzero entity advances the camera reset generation; possessing the same entity keeps the look. Use resetView() when a same-entity respawn should also reset the camera.

Parameters

Parameter	Type	Description
`entity`	`number`	The entity, or 0 to control none.

Returns

void

Example

const body = ctx.spawn(Avatar, spawnPoint);
ctx.players.get(id)?.possess(body);

resetView()

resetView(): void;

Request an authoritative camera reset, including for a respawn that reuses the same entity. Client-role calls do nothing; the page resets when it observes the generation. The page acknowledges the new generation before its look is accepted.

Returns

void

Example

ctx.players.get(id)?.resetView();

restoreSeat()

restoreSeat(
   connected, 
   name, 
   entity, 
   data
): void;

Overwrite who holds this seat from a snapshot. The caller rebuilds the map.

Parameters

Parameter	Type	Description
`connected`	`boolean`	Joined and not left.
`name`	`string`	The display name.
`entity`	`number`	The player's entity in the restored world, or 0.
`data`	`unknown`	The saved document, already parsed.

Returns

void

setEntity()

setEntity(entity): void;

The authority spawned this player's entity at join: possess it (which tells the host). Nothing is sent for 0 (a game with no player prefab).

Parameters

Parameter	Type	Description
`entity`	`number`	The entity spawned for this player, or 0.

Returns

void

PlayerInput

One player's input for a step, as frame-input.players carries it.

Properties

input

input: InputState;

That player's keys, mouse and gamepads.

player

player: number;

The player id. 0 is the single-player player, which travels as frame-input.input.

seq

seq: number;

The client's input sequence number this step consumed; 0 when unknown.

PlayerJoinedEvent

A player entered the room.

Properties

data?

optional data?: string;

The player's saved document as JSON, when the room has a store. Absent otherwise (null in a wasm guest, as every incoming option is).

name

name: string;

player

player: number;

PlayerLeftEvent

A player left the room.

Properties

player

player: number;

reason

reason: string;

Why: "left", "timeout", "kicked", ...

Players

The room's players: a read-only Map from id to PlayerHandle, plus who the host is and a list to walk without allocating.

A for...of over the map (or keys(), values(), entries()) makes an iterator, and an entry pair per player, every call: fine in a join handler, not in a system that runs every tick. Walk list with an index there.

Example

const players = ctx.players;
for (let i = 0; i < players.list.length; i += 1) {
  const p = players.list[i];
  if (p.isHost && p.input.pressed('Enter')) startRound();
}
const host = players.host === undefined ? undefined : players.get(players.host);

Extends

ReadonlyMap<number, PlayerHandle>

Properties

host

readonly host: number | undefined;

The host's seat id, or undefined while nobody is joined. The first joiner is the host and stays host until they leave (player-left); only then does it pass to the lowest seat still joined. A newcomer who takes a lower, freed seat does not become host. Snapshots keep it.

A host who drops counts as gone for this alone: while the room holds their seat (they are still joined, but out of the frame's players list), the role passes to the lowest seat in that list, and it stays there when they come back. If nobody else is in the list, the held host keeps it.

list

readonly list: readonly PlayerHandle[];

The same players as the map, in id order. The same array for the whole run, updated in place on a join or a leave; never per tick. Read it, do not keep a copy of its contents across ticks.

PlayerSpec

The declarative player block.

Properties

camera?

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

Which built-in camera rig to drive.

character?

optional character?: (seat) => string;

Character asset id for a seat, overriding the prefab's character.

Parameters

Parameter	Type
`seat`	`number`

Returns

string

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?: PlayerSpawn | MarkerSpawn;

Where each seat spawns; see PlayerSpawn. Default [0, 0, 0].

PlayerStateProps

Persistent seat statistics.

Example

const stats: Partial<PlayerStateProps> = { team: 1 };

Properties

deaths

deaths: number;

kills

kills: number;

playerName

playerName: string;

score

score: number;

seat

seat: number;

team

team: number;

PlayMusicCmd

play-music payload.

Example

`const value: PlayMusicCmd = {tracks: [], stems: [], stemGains: [], bpm: 0, beatsPerBar: 4, firstBeat: 0, fadeMs: 0, start: 'now', looping: false, volume: 1};`

Properties

beatsPerBar

beatsPerBar: number;

Beats per bar; 0 means 4.

bpm

bpm: number;

Beats per minute; 0 disables the clock.

fadeMs

fadeMs: number;

Crossfade duration in milliseconds.

firstBeat

firstBeat: number;

Seconds from file start to beat zero.

looping

looping: boolean;

Loop tracks or stems.

start

start: BeatQuantize;

Start relative to the current grid.

stemGains

stemGains: number[];

Initial gains; missing entries mean 1.

stems

stems: number[];

Sample-locked layers; ignores tracks when non-empty.

tracks

tracks: number[];

Streamed playlist in order.

volume

volume: number;

Linear gain.

PlayOnBeatOptions

Grid-scheduled sound options.

Example

`audio.playOnBeat('kick', { quantize: 'bar' });`

Properties

bus?

optional bus?: AudioBus;

Mixer bus.

quantize?

optional quantize?: BeatQuantize;

Grid; defaults to beat.

subdivision?

optional subdivision?: number;

Points per beat; defaults to one.

volume?

optional volume?: number;

Linear gain.

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;

PlaySoundOnBeatCmd

play-sound-on-beat payload.

Example

`const value: PlaySoundOnBeatCmd = {sound: 0, asset: 0, quantize: 'beat', subdivision: 1, volume: 1, bus: 'sfx'};`

Properties

asset

asset: number;

Manifest asset handle.

bus

bus: AudioBus;

Mixer bus.

quantize

quantize: BeatQuantize;

Grid to schedule on.

sound

sound: number;

Guest-minted sound handle.

subdivision

subdivision: number;

Grid points per beat; ignored for bars.

volume

volume: number;

Linear gain.

PlaytestCmd

A playtest mark (playtest facade): something a playtest should know happened. It changes nothing in the game; the page's recorder, its agent and the playtest reports read it.

Properties

entity

entity: number;

The entity it concerns (the player, the goal), or 0.

kind

kind: string;

What happened: death, win, checkpoint, damage, reward, goal, player, restart, or a word of the game's own.

note

note: string;

Why, in a few words: a death's cause. May be empty.

position

position: Vec3 | undefined;

Where, in world space, or undefined.

value

value: number;

How much: damage taken, a reward; 0 when it has no amount.

PostCmd

Partial post command; absent fields preserve the current look.

Example

import type { PostCmd } from 'gameable';
const command: PostCmd = { reset: true, bloom: 0.5 };

Properties

bloom?

optional bloom?: number;

bloomRadius?

optional bloomRadius?: number;

bloomThreshold?

optional bloomThreshold?: number;

contrast?

optional contrast?: number;

exposure?

optional exposure?: number;

fogColor?

optional fogColor?: Vec3;

fogDensity?

optional fogDensity?: number;

reset

reset: boolean;

Back to neutral before this command's fields apply.

saturation?

optional saturation?: number;

tint?

optional tint?: Vec3;

toneMapping?

optional toneMapping?: ToneMapping;

vignette?

optional vignette?: number;

PostSettings

Partial post settings. Omitted fields retain the host's current values.

Example

import { vfx, type PostSettings } from 'gameable';
const settings: PostSettings = { reset: true, bloom: 0.4, toneMapping: 'aces' };
vfx.post(settings);

Properties

bloom?

optional bloom?: number;

Bloom strength; neutral 0.

bloomRadius?

optional bloomRadius?: number;

Bloom radius; neutral 0.4.

bloomThreshold?

optional bloomThreshold?: number;

Bloom threshold in linear light; neutral 1.

contrast?

optional contrast?: number;

Contrast multiplier; neutral 1.

exposure?

optional exposure?: number;

Exposure multiplier; neutral 1.

fogColor?

optional fogColor?: Vec3;

Fog linear RGB colour; neutral (0.5, 0.55, 0.6).

fogDensity?

optional fogDensity?: number;

Exponential fog density; neutral 0.

reset?

optional reset?: boolean;

Return to neutral before applying the supplied fields.

saturation?

optional saturation?: number;

Saturation multiplier; neutral 1.

tint?

optional tint?: Vec3;

Linear RGB grade; neutral (1, 1, 1).

toneMapping?

optional toneMapping?: ToneMapping;

Tone mapping; neutral 'none'.

vignette?

optional vignette?: number;

Vignette strength; neutral 0.

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

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].

PressurePlateProps

Floor-level pressure plate tuning. Occupants are tested by their actor/player origin.

Example

const props: Partial<PressurePlateProps> = { weight: 2, pressedBy: ['crate'] };

Properties

colour

colour: [number, number, number];

depth

depth: number;

holdSeconds

holdSeconds: number;

once

once: boolean;

pressedBy

pressedBy: string[];

pressSound

pressSound: string;

releaseSound

releaseSound: string;

weight

weight: number;

width

width: number;

ProjectileOptions

Guest projectile integration; homing target is an ECS entity id, resolved each step.

Example

const options: ProjectileOptions = { speed: 20, gravityScale: 1, bounces: 2, bounciness: 0.7 };

Properties

bounces?

optional bounces?: number;

bounciness?

optional bounciness?: number;

gravityScale?

optional gravityScale?: number;

homingTarget?

optional homingTarget?: number;

onHit?

optional onHit?: (self, hit, ctx, stopped) => void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`hit`	`RayHit`
`ctx`	`GameContext`
`stopped`	`boolean`

Returns

void

speed

speed: number;

ProjectileProps

Projectile level data. Launch is along local +Z; lifeSpan zero means forever.

Example

const props: Partial<ProjectileProps> = {speed: 30, damage: 20, gravityScale: 0, lifeSpan: 3};

Properties

asset

asset: string;

bounces

bounces: number;

bounciness

bounciness: number;

damage

damage: number;

gravityScale

gravityScale: number;

hitResponse

hitResponse: "effect" | "both" | "damage";

homingTarget

homingTarget: number;

Target ECS entity id, resolved each step; zero disables homing.

lifeSpan

lifeSpan: number;

speed

speed: number;

PropMeta

Authoring hints and constraints for one property; omitted type is inferred from its default.

Example

const meta: PropMeta = { description: 'Reach.', min: 0, unit: 'metres' };

Extended by

CatalogProp

Properties

const?

optional const?: boolean;

Restrict a boolean branch to one literal value.

description

description: string;

fields?

optional fields?: Record<string, PropMeta>;

group?

optional group?: string;

Shared reference table; actor-specific differences remain documented on the actor.

items?

optional items?: PropMeta;

max?

optional max?: number;

min?

optional min?: number;

nullable?

optional nullable?: boolean;

Accept null in addition to the described shape.

oneOf?

optional oneOf?: readonly PropMeta[];

optional?

optional optional?: boolean;

Allow this field to be omitted from a fixed-shape object.

type?

optional type?: 
  | "string"
  | "number"
  | "boolean"
  | "object"
  | "color"
  | "vec3"
  | "array"
  | "enum";

unit?

optional unit?: string;

values?

optional values?: readonly string[];

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;

QueryShape

QueryShape: radians and metres at the host boundary.

Example

import type { QueryShape } from 'gameable';
const value: QueryShape = { kind: 'sphere', halfExtents: { x: 1, y: 1, z: 1 } };

Properties

halfExtents

halfExtents: Vec3;

Box uses xyz; sphere radius is x; capsule/cylinder radius is x and half-height is y.

kind

kind: "box" | "sphere" | "capsule" | "cylinder";

Quests

An owner's quest log. Callbacks run synchronously: progress, objective-done, then complete. Forced completion visits objectives in ascending index order. Empty quests complete immediately when started. Values clamp to [0, target].

Example

import { createQuests, type Quests } from 'gameable';
const log: Quests = createQuests({ owners: 1, quests: [{ id: 'visit', objectives: [{ id: 'gate' }] }] });
log.start(0, 'visit');
log.progress(0, 'visit', 'gate');

Extends

GameplayPart

Methods

abandon()

abandon(owner, quest): boolean;

Abandon an active quest and clear its values.

Parameters

Parameter	Type
`owner`	`number`
`quest`	`string` \| `number`

Returns

boolean

complete()

complete(owner, quest): boolean;

Force completion from available or active; false otherwise.

Parameters

Parameter	Type
`owner`	`number`
`quest`	`string` \| `number`

Returns

boolean

done()

done(
   owner, 
   quest, 
   objective
): boolean;

Whether the objective reached its target.

Parameters

Parameter	Type
`owner`	`number`
`quest`	`string` \| `number`
`objective`	`string` \| `number`

Returns

boolean

objective()

objective(quest, id): number;

Resolve an objective within a quest.

Parameters

Parameter	Type
`quest`	`string` \| `number`
`id`	`string` \| `number`

Returns

number

progress()

progress(
   owner, 
   quest, 
   objective, 
   amount?
): number;

Add progress while active; return the clamped value.

Parameters

Parameter	Type
`owner`	`number`
`quest`	`string` \| `number`
`objective`	`string` \| `number`
`amount?`	`number`

Returns

number

quest()

quest(id): number;

Resolve a quest id or validate its index.

Parameters

Parameter	Type
`id`	`string` \| `number`

Returns

number

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

Inherited from

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

set()

set(
   owner, 
   quest, 
   objective, 
   value
): number;

Set progress while active; return the clamped value.

Parameters

Parameter	Type
`owner`	`number`
`quest`	`string` \| `number`
`objective`	`string` \| `number`
`value`	`number`

Returns

number

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

DriveOptions.acceptanceRadius

start()

start(owner, quest): boolean;

Start an available quest.

Parameters

Parameter	Type
`owner`	`number`
`quest`	`string` \| `number`

Returns

boolean

status()

status(owner, quest): "locked" | "available" | "active" | "complete";

Prerequisites are checked immediately for this owner.

Parameters

Parameter	Type
`owner`	`number`
`quest`	`string` \| `number`

Returns

"locked" | "available" | "active" | "complete"

value()

value(
   owner, 
   quest, 
   objective
): number;

Read progress.

Parameters

Parameter	Type
`owner`	`number`
`quest`	`string` \| `number`
`objective`	`string` \| `number`

Returns

number

RaceProgress

Borrowed live progress; immutable to callers. FinishedAt uses the swept substep time.

Example

const show = (p: RaceProgress) => console.log(p.place, p.completedLaps);

Extends

CircuitRacer

Properties

completedLaps

completedLaps: number;

entity

entity: number;

Inherited from

CircuitRacer.entity

finishedAt

finishedAt: number | null;

finishPlace

finishPlace: number;

lastGate

lastGate: number;

nextGate

nextGate: number;

place

place: number;

racer

racer: number;

Inherited from

CircuitRacer.racer

respawnPose

respawnPose: object;

position

position: [number, number, number];

yaw

yaw: number;

seat

seat: number | null;

Inherited from

CircuitRacer.seat

segmentDistance

segmentDistance: number;

status

status: "active" | "finished" | "disconnected" | "spectating";

RacingLineOptions

Racing line controls. cornerSpeed is the minimum preview corner speed in m/s.

Example

followRacingLine(ctx, ai, ['start', 'bend', 'finish'], { speed: 15, loop: true });

Extends

DriveOptions

Properties

acceptanceRadius?

optional acceptanceRadius?: number;

Inherited from

cornerSpeed?

optional cornerSpeed?: number;

lateralOffset?

optional lateralOffset?: number;

lookAhead?

optional lookAhead?: number;

loop?

optional loop?: boolean;

speed?

optional speed?: number;

Inherited from

DriveOptions.speed

stopAtTarget?

optional stopAtTarget?: boolean;

Inherited from

DriveOptions.stopAtTarget

tuning?

optional tuning?: Partial<DriveTuning>;

Inherited from

DriveOptions.tuning

RadialForceOptions

Radial impulses and continuous force, in metres and SI physics units.

Example

const options: RadialForceOptions = { radius: 8, falloff: 'linear' };

Properties

active?

optional active?: boolean;

falloff?

optional falloff?: "linear" | "constant";

forceStrength?

optional forceStrength?: number;

impulseStrength?

optional impulseStrength?: number;

radius?

optional radius?: number;

velocityChange?

optional velocityChange?: 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.

ResetVehicleCmd

Reset pose in world coordinates.

Example

const command = { body: 1, position: {x:0,y:1,z:0}, rotation: {x:0,y:0,z:0,w:1} };

Properties

body

body: number;

position

position: Vec3;

rotation

rotation: Quat;

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;

RuleEvent

Borrowed lifecycle payload; winner is a team id or player seat, null for a draw.

Example

const result: RuleEvent = { phase: 'round', round: 1, winner: null };

Properties

phase

phase: string;

round

round: number;

winner

winner: number | null;

SaveGameDataCmd

Persist the room's game-wide document (JSON). Authority only.

Properties

data

data: string;

SavePlayerDataCmd

Persist one player's document (JSON). Authority only.

Properties

data

data: string;

player

player: number;

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;

ScreenPoint

Screen position and distance along the view axis, in metres.

Example

const point: ScreenPoint = { x: 0, y: 0, depth: 0, visible: false };

Properties

depth

depth: number;

visible

visible: boolean;

x

x: number;

y

y: number;

ScreenRay

World ray with a normalised direction; allocate once and reuse.

Example

const ray: ScreenRay = { origin: { x: 0, y: 0, z: 0 }, direction: { x: 0, y: 0, z: -1 } };

Properties

direction

direction: Vec3;

origin

origin: Vec3;

Selection

Stable, duplicate-free selection in insertion order. Full sets ignore new entries.

Example

const selection = createSelection(32); selection.add(unit);

Properties

entities

readonly entities: readonly number[];

Methods

add()

add(entity): void;

Parameters

Parameter	Type
`entity`	`number`

Returns

void

box()

box(
   candidates, 
   x0, 
   y0, 
   x1, 
   y1, 
   project, 
   additive?
): void;

Parameters

Parameter	Type
`candidates`	readonly `number`[]
`x0`	`number`
`y0`	`number`
`x1`	`number`
`y1`	`number`
`project`	(`entity`, `out`) => `boolean`
`additive?`	`boolean`

Returns

void

clear()

clear(): void;

Returns

void

has()

has(entity): boolean;

Parameters

Parameter	Type
`entity`	`number`

Returns

boolean

prune()

prune(isAlive): void;

Parameters

Parameter	Type
`isAlive`	(`entity`) => `boolean`

Returns

void

set()

set(entity): void;

Parameters

Parameter	Type
`entity`	`number`

Returns

void

toggle()

toggle(entity): void;

Parameters

Parameter	Type
`entity`	`number`

Returns

void

SendCmd

Send a game message to one player, every player, or up to the authority.

Properties

name

name: string;

payload

payload: string;

JSON, at most 2,048 bytes.

reliable

reliable: boolean;

to?

optional to?: number;

One player; absent sends to every player (authority) or to the authority (client).

SendOptions

Options for NetFacade.send.

Example

ctx.net.send('role', { role: 'murderer' }, { to: 3 });
ctx.net.send('aim', { x: 1 }, { reliable: false }); // every player, may drop

Properties

reliable?

optional reliable?: boolean;

Ordered and guaranteed. Default true.

to?

optional to?: number;

One player; absent sends to every player. Ignored on a client.

SensesOptions

Sensing settings and callbacks retained by derived actor specs.

Example

const options: SensesOptions = { sightRadius: 20, onSeePawn(self, pawn, ctx) {} };

Extends

ComponentOptions

Properties

attach?

optional attach?: string;

Parent component name; defaults to root for non-root components.

Inherited from

hearingThreshold?

optional hearingThreshold?: number;

interval?

optional interval?: number;

losHearingThreshold?

optional losHearingThreshold?: number;

offset?

optional offset?: readonly [number, number, number];

Translation in the parent's space.

Inherited from

onlySensePlayers?

optional onlySensePlayers?: boolean;

peripheralAngle?

optional peripheralAngle?: number;

rotation?

optional rotation?: Quat;

Local quaternion, default identity.

Inherited from

scale?

optional scale?: readonly [number, number, number];

Local per-axis scale, default one.

Inherited from

sightRadius?

optional sightRadius?: number;

Methods

onHearNoise()?

optional onHearNoise(
   self, 
   instigator, 
   location, 
   loudness, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`instigator`	`number`
`location`	`Readonly`<`Vec3`>
`loudness`	`number`
`ctx`	`GameContext`

Returns

void

onSeePawn()?

optional onSeePawn(
   self, 
   pawn, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`
`pawn`	`number`
`ctx`	`GameContext`

Returns

void

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;

SetBusFxCmd

set-bus-fx payload.

Example

`const value: SetBusFxCmd = {bus: 'sfx', preset: 'dry', reverb: undefined, lowpassHz: undefined, highpassHz: undefined, compressor: undefined, fadeMs: 0};`

Properties

bus

bus: AudioBus;

Mixer bus.

compressor?

optional compressor?: boolean;

Optional compression switch.

fadeMs

fadeMs: number;

Ramp duration in milliseconds.

highpassHz?

optional highpassHz?: number;

Optional high-pass cutoff in Hz.

lowpassHz?

optional lowpassHz?: number;

Optional low-pass cutoff in Hz.

preset

preset: FxPreset;

Base effect preset.

reverb?

optional reverb?: number;

Optional wet level.

SetCharacterMotionCmd

How the movement system moves a character (see character.motion).

Properties

carry

carry: boolean;

Whether the take carries the walker.

entity

entity: number;

naturalness

naturalness: number;

on

on: boolean;

Whether the movement system moves this character at all.

responsiveness

responsiveness: number;

0..1; negative keeps what it has.

set?

optional set?: string;

'own', 'shared' or a name the page gave its bridge; absent keeps the set it has.

stop?

optional stop?: StopStyle;

Which kind of stop it makes when it runs and is asked to stand: 'gradual' (it slows and stands upright) or 'hard' (it brakes). Absent keeps what it has.

SetCharacterStateCmd

Drive a character's locomotion state machine.

Properties

entity

entity: number;

facing?

optional facing?: number;

Optional held world yaw in radians.

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[];

SetJointMotorCmd

SetJointMotorCmd: radians and metres at the host boundary.

Example

import type { SetJointMotorCmd } from 'gameable';
const value: SetJointMotorCmd = { joint: 1, axis: 0, mode: 'position', target: 1, maxForce: 10 };

Properties

axis

axis: number;

joint

joint: number;

maxForce

maxForce: number;

mode

mode: MotorMode;

target

target: 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;

SetMusicLayerCmd

set-music-layer payload.

Example

`const value: SetMusicLayerCmd = {layer: 0, gain: 1, fadeMs: 0};`

Properties

fadeMs

fadeMs: number;

Ramp duration in milliseconds.

gain

gain: number;

Linear gain.

layer

layer: number;

Stem index.

SetParentCmd

Reparent an entity in the scene graph.

Properties

entity

entity: number;

keepWorldTransform

keepWorldTransform: boolean;

parent?

optional parent?: number;

SetPlayerCameraCmd

The camera one player renders from.

Properties

camera

camera: CameraState;

player

player: number;

SetPlayerEntityCmd

Which entity a player controls. The authority sends it when it spawns definition.player for a join and on every PlayerHandle.possess; the host keeps the mapping (relevancy, "which entity is mine" on the client).

Properties

entity

entity: number;

player

player: number;

spawn?

optional spawn?: number;

Acknowledged camera reset generation; absent for legacy host commands.

SetPlayerHudCmd

One player's HUD model as JSON.

Properties

hud

hud: string;

player

player: number;

SetSoundOcclusionCmd

set-sound-occlusion payload.

Example

`const value: SetSoundOcclusionCmd = {sound: 0, amount: 0, fadeMs: 0};`

Properties

amount

amount: number;

Occlusion from 0 to 1.

fadeMs

fadeMs: number;

Ramp duration in milliseconds.

sound

sound: number;

Sound handle.

SetVehicleInputCmd

Normalized transient controls.

Example

const command = { body: 1, controls, gripScale: 1 };

Properties

body

body: number;

controls

controls: VehicleInput;

gripScale

gripScale: number;

Shape

Collision shape description carried by add-body.

Properties

asset?

optional asset?: number;

halfExtents

halfExtents: Vec3;

kind

kind: ShapeKind;

ShapeOptions

Collision and rigid body settings.

Example

const options: ShapeOptions = { collision: 'block', body: 'dynamic' };

Extends

ComponentOptions

Extended by

ActorComponent

Properties

attach?

optional attach?: string;

Parent component name; defaults to root for non-root components.

Inherited from

body?

optional body?: "kinematic" | "dynamic" | "static";

Blocking body motion; defaults to static.

ccd?

optional ccd?: boolean;

Continuous collision detection for fast dynamic bodies.

collision?

optional collision?: 
  | "none"
  | "overlap"
  | "block"
  | CollisionSetup
  | "NoCollision"
  | "BlockAll"
  | "OverlapAll"
  | "BlockAllDynamic"
  | "OverlapAllDynamic"
  | "IgnoreOnlyPawn"
  | "OverlapOnlyPawn"
  | "Pawn"
  | "Spectator"
  | "CharacterMesh"
  | "PhysicsActor"
  | "Destructible"
  | "InvisibleWall"
  | "InvisibleWallDynamic"
  | "Trigger"
  | "Ragdoll"
  | "Vehicle"
  | "UI";

Collision response; defaults to block.

dimensions?

optional dimensions?: readonly string[];

Spawn-time prop names supplying dimensions: ['halfExtents'] or ['radius', 'halfHeight'].

fit?

optional fit?: "box" | "convex-hull" | "mesh";

layer?

optional layer?: CollisionLayers;

Physics collision layer.

mask?

optional mask?: CollisionLayers;

Raw physics mask; cannot accompany a named/custom collision policy.

mass?

optional mass?: number;

Dynamic mass in kilograms.

offset?

optional offset?: readonly [number, number, number];

Translation in the parent's space.

Inherited from

reportHits?

optional reportHits?: boolean;

Request blocking contact callbacks.

rotation?

optional rotation?: Quat;

Local quaternion, default identity.

Inherited from

scale?

optional scale?: readonly [number, number, number];

Local per-axis scale, default one.

Inherited from

SidedSystem

A system that says where it runs.

'authority' runs on the room's authority and in a single-player (solo) game; 'client' runs on a player's page and in solo; 'both' runs everywhere. solo is its own authority and its own client, so it runs all three. A bare function is 'authority' once the game declares features.multiplayer, and 'both' otherwise, so a single-player game reads the same as it always did.

Example

import { defineGame } from 'gameable';

export default defineGame({
  features: { multiplayer: true },
  systems: [
    (ctx) => { ctx.net.send('tick', ctx.frame); }, // bare: the authority's
    { on: 'client', run: (ctx) => { ctx.hud.set({ ping: ctx.frame }); } },
  ],
});

Properties

on

on: "authority" | "client" | "both";

Where it runs.

run

run: Run;

The system.

SideScrollCameraOptions

Side view bounds refer to camera centre, in metres.

Example

const options: SideScrollCameraOptions = { minX: 0, maxX: 40 };

Properties

deadZone?

optional deadZone?: number;

distance?

optional distance?: number;

height?

optional height?: number;

lead?

optional lead?: number;

maxX

maxX: number;

maxY?

optional maxY?: number;

minX

minX: number;

minY?

optional minY?: number;

smoothing?

optional smoothing?: number;

SlidingDoorProps

Local panel slide tuning. Zero travel selects panel width.

Example

const props: Partial<SlidingDoorProps> = { panels: 2 };

Extends

DoorCoreProps

Extended by

AutomaticDoorProps

Properties

action

action: string;

Inherited from

asset?

optional asset?: string;

Inherited from

autoCloseSeconds

autoCloseSeconds: number;

Inherited from

closePrompt

closePrompt: string;

Inherited from

closeSound

closeSound: string;

Inherited from

colour

colour: [number, number, number];

Inherited from

consumeKey

consumeKey: boolean;

Inherited from

enabled

enabled: boolean;

Inherited from

facingDegrees

facingDegrees: number;

Inherited from

height

height: number;

Closed doorway height in metres.

Inherited from

lockedBy

lockedBy: string;

Inherited from

lockedMessage

lockedMessage: string;

Inherited from

lockedPrompt

lockedPrompt: string;

Inherited from

lockedSound

lockedSound: string;

Inherited from

look

look: "none" | "wood" | "metal";

Inherited from

once

once: boolean;

Inherited from

openPrompt

openPrompt: string;

Inherited from

openSound

openSound: string;

Inherited from

opensWhen

opensWhen: string[];

Inherited from

panels

panels: 1 | 2;

prompt

prompt: string;

Inherited from

range

range: number;

Inherited from

seconds

seconds: number;

Inherited from

slide

slide: "left" | "right" | "up";

startOpen

startOpen: boolean;

Inherited from

stayOpen

stayOpen: boolean;

Inherited from

thickness

thickness: number;

Leaf thickness in metres.

Inherited from

toggledBy

toggledBy: "proximity" | "interact" | "signal";

Inherited from

travel

travel: number;

width

width: number;

Closed doorway width in metres.

Inherited from

SnapshotPeek

What peekSnapshotHeader returns: the header's frame counter and the game's folded state (defineGame's parts, the actor rows among them), read without a runtime.

Properties

elapsed

elapsed: number;

Simulated seconds since init.

frame

frame: number;

The fixed-step counter when the snapshot was taken.

player

player: number;

The player entity, or 0.

user

user: unknown;

What defineGame({ snapshot }) folded in: { __gameableActors: 1, actors: { rows }, ... } or the game's own.

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;

SpawnerProps

Wave spawner level data. Points selects TargetPoint actors by tag; an empty tag uses the spawner transform.

Example

const props: Partial<SpawnerProps> = {actorClass: 'Enemy', waves: [{count: 3,every: 1}],maxAlive: 2};

Properties

actorClass

actorClass: string;

autoStart

autoStart: boolean;

maxAlive

maxAlive: number;

points

points: string;

waves

waves: object[];

count

count: number;

delay?

optional delay?: number;

every

every: number;

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.

SplinePath

World-space distance queries over an authored local path.

Example

const path: SplinePath = splineOf(actor, 'path');

Properties

length

readonly length: number;

Methods

closestDistance()

closestDistance(point): number;

Parameters

Parameter	Type
`point`	`Readonly`<`Vec3`>

Returns

number

directionAt()

directionAt(distance, out): Vec3;

Parameters

Parameter	Type
`distance`	`number`
`out`	`Vec3`

Returns

pointAt()

pointAt(distance, out): Vec3;

Parameters

Parameter	Type
`distance`	`number`
`out`	`Vec3`

Returns

BurstOptions.direction

SpotLightCmd

Guest spotlight settings. Local forward is -Z; camera attachment uses the active view.

Example

const light: SpotLightCmd = { entity: 1, color: { x: 1, y: 1, z: 1 }, intensity: 20, radius: 12, angle: 30, penumbra: 0.4, cameraAttached: true, enabled: true };

Properties

angle

angle: number;

cameraAttached

cameraAttached: boolean;

color

color: object;

x

x: number;

y

y: number;

z

z: number;

enabled

enabled: boolean;

entity

entity: number;

intensity

intensity: number;

penumbra

penumbra: number;

radius

radius: number;

StaminaOptions

Sprint energy tuning, in units and seconds.

Example

const tuning: StaminaOptions = { maximum: 5, drain: 1, regen: 0.5 };

Properties

drain?

optional drain?: number;

maximum?

optional maximum?: number;

recoveryDelay?

optional recoveryDelay?: number;

regen?

optional regen?: number;

StaminaState

Serializable component state; set requested while moving.

Example

const energy: StaminaState = { value: 5, maximum: 5, requested: false, active: false, exhausted: false, delay: 0 };

Properties

active

active: boolean;

delay

delay: number;

exhausted

exhausted: boolean;

maximum

maximum: number;

requested

requested: boolean;

value

value: number;

StartOptions

A persistent emitter's position or entity attachment, plus burst overrides.

Example

import { vfx, type StartOptions } from 'gameable';
const options: StartOptions = { at: { x: 0, y: 1, z: 0 } };
const id = vfx.start('fire', options);
vfx.stop(id);

Extends

BurstOptions

Properties

at?

optional at?: Vec3;

World position, or offset when attached to an entity; defaults to zero.

direction?

optional direction?: Vec3;

Emission direction; absent uses the preset's own direction.

Inherited from

entity?

optional entity?: number;

Follow this entity.

intensity?

optional intensity?: number;

Count and brightness multiplier, default 1.

Inherited from

BurstOptions.intensity

scale?

optional scale?: number;

Size multiplier, default 1.

Inherited from

BurstOptions.scale

tint?

optional tint?: Vec3;

Linear RGB override; values over 1 glow under bloom.

Inherited from

BurstOptions.tint

StemOptions

Stem playback options.

Example

`music.stems(['drums', 'bass'], { gains: [1, 0] });`

Extends

MusicOptions

Properties

beatsPerBar?

optional beatsPerBar?: number;

Beats in each bar; defaults to four.

Inherited from

MusicOptions.beatsPerBar

bpm?

optional bpm?: number;

Beats per minute; zero disables the clock.

Inherited from

MusicOptions.bpm

fadeMs?

optional fadeMs?: number;

Crossfade duration.

Inherited from

MusicOptions.fadeMs

firstBeat?

optional firstBeat?: number;

Seconds to beat zero.

Inherited from

MusicOptions.firstBeat

gains?

optional gains?: readonly number[];

Initial gains; missing entries mean one.

loop?

optional loop?: boolean;

Loop playback.

Inherited from

MusicOptions.loop

start?

optional start?: BeatQuantize;

Starting grid; defaults to now.

Inherited from

MusicOptions.start

volume?

optional volume?: number;

Linear gain.

Inherited from

MusicOptions.volume

StopSoundCmd

Stop a playing sound.

Properties

fadeMs

fadeMs: number;

sound

sound: number;

SweepHit

Blocking contact. Optional metadata preserves surface policy and distinct edge normals.

Example

const hit: SweepHit = { time: 1, distance: 1, normal: {x:0,y:1,z:0}, point: {x:0,y:0,z:0}, entity: 1, startPenetrating: false, depth: 0 };

Properties

canStepUp?

optional canStepUp?: boolean;

depth

depth: number;

distance

distance: number;

entity

entity: number;

impactNormal?

optional impactNormal?: Vec3;

isPawn?

optional isPawn?: boolean;

normal

normal: Vec3;

point

point: Vec3;

startPenetrating

startPenetrating: boolean;

time

time: number;

walkableFloorZ?

optional walkableFloorZ?: number;

ThingCmd

Something a game asks of a loose thing in a made world (gameable/world): push an impulse at its middle (newton-seconds), move the middle of its base to a point (at rest), reset it to where the package had it, or reset-all for every loose thing. Of a thing with moving parts: joint and drive. Of a thing with rider spots: ride sits a character on it, or takes whoever sits on it off. Of a thing in pieces: break lets its pieces go (named for one piece, that piece alone). The thing is named by its place in the world's list.

Properties

action

action: 
  | "push"
  | "move"
  | "reset"
  | "reset-all"
  | "joint"
  | "drive"
  | "ride"
  | "break";

thing

thing: number;

The thing's place in the world's list; ignored by reset-all.

vector

vector: Vec3;

push: the impulse. move: the point. joint: x the joint's place in the thing's list of joints, y its value. drive: x steering to the right (-1 to 1), y the brakes (0 to 1), z the throttle (-1 to 1). ride: x the character's entity, 0 for getting off. Zero otherwise.

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;

TileColliderOptions

Tile collider spawning configuration.

Example

const options: TileColliderOptions = { collision: 'BlockAll', cellSize: 2 };

Properties

cellSize?

optional cellSize?: number;

collision?

optional collision?: 
  | CollisionSetup
  | "NoCollision"
  | "BlockAll"
  | "OverlapAll"
  | "BlockAllDynamic"
  | "OverlapAllDynamic"
  | "IgnoreOnlyPawn"
  | "OverlapOnlyPawn"
  | "Pawn"
  | "Spectator"
  | "CharacterMesh"
  | "PhysicsActor"
  | "Destructible"
  | "InvisibleWall"
  | "InvisibleWallDynamic"
  | "Trigger"
  | "Ragdoll"
  | "Vehicle"
  | "UI";

TileCollisionBox

Merged tile collision box in world metres.

Example

const boxes: TileCollisionBox[] = mergeTileColliders([{ x: 0, z: 0, height: 1 }]);

Properties

center

center: Vec3;

halfExtents

halfExtents: readonly [number, number, number];

Timers

Fixed-step timer slots. Call reset from game init.

Example

import { createTimers, type Timers } from 'gameable';
const timers: Timers = createTimers({ capacity: 4 });
timers.reset();

Extends

GameplayPart

Methods

active()

active(timer): boolean;

Whether the slot is counting down.

Parameters

Parameter	Type
`timer`	`number`

Returns

boolean

cancel()

cancel(timer): void;

Cancel a slot and clear its progress.

Parameters

Parameter	Type
`timer`	`number`

Returns

void

fired()

fired(timer): boolean;

True from firing until the next step, including after restart or cancel.

Parameters

Parameter	Type
`timer`	`number`

Returns

boolean

progress()

progress(timer): number;

Elapsed fraction; completed one-shots retain one until cancelled.

Parameters

Parameter	Type
`timer`	`number`

Returns

number

remaining()

remaining(timer): number;

Remaining seconds using the timestep captured at start.

Parameters

Parameter	Type
`timer`	`number`

Returns

number

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

Inherited from

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

start()

start(
   ctx, 
   timer, 
   seconds, 
   repeat?
): void;

Start or restart a slot; duration is converted once using ctx.dt.

Parameters

Parameter	Type
`ctx`	`GameContext`
`timer`	`number`
`seconds`	`number`
`repeat?`	`boolean`

Returns

void

step()

step(ctx): void;

Advance all slots, then call onFire synchronously in ascending slot order.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

TopDownCamera

A deterministic camera rig. Do not also declare player.camera in defineGame.

Example

const rig: TopDownCamera = createTopDownCamera(); rig.pan(2, 0);

Properties

state

readonly state: TopDownCameraState;

Plain JSON pose, including saved follow bookkeeping.

Methods

focusOn()

focusOn(point): void;

Jump to a world point and stop following.

Parameters

Parameter	Type
`point`	`Vec3`

Returns

void

follow()

follow(entity): void;

Track a Transform; zero stops. Pan input breaks follow.

Parameters

Parameter	Type
`entity`	`number`

Returns

void

pan()

pan(dx, dz): void;

Camera-relative metres; +dx is right, +dz is forward.

Parameters

Parameter	Type
`dx`	`number`
`dz`	`number`

Returns

void

rotate()

rotate(dYaw): void;

Add radians about +Y.

Parameters

Parameter	Type
`dYaw`	`number`

Returns

void

update()

update(ctx, dt): void;

Read controls, clamp, and write the frame camera; call once per tick.

Parameters

Parameter	Type
`ctx`	`GameContext`
`dt`	`number`

Returns

void

zoom()

zoom(factor): void;

Multiply distance by a positive factor, clamped to limits.

Parameters

Parameter	Type
`factor`	`number`

Returns

void

TopDownCameraOptions

Controls and limits for a perspective top-down rig.

Example

const options: TopDownCameraOptions = { distance: 20, edgePan: true };

Properties

bounds?

optional bounds?: object;

Focus limits in world x/z.

max

max: [number, number];

min

min: [number, number];

distance?

optional distance?: number;

Initial boom length, metres; default 14.

edgeMarginPx?

optional edgeMarginPx?: number;

Edge band width in pixels; default 24.

edgePan?

optional edgePan?: boolean;

Enable viewport edge panning; default false.

fovYDeg?

optional fovYDeg?: number;

Vertical field of view, degrees; default 45.

keys?

optional keys?: object;

Pan keys (arrows also work with defaults), and rotation keys.

down?

optional down?: string;

left?

optional left?: string;

right?

optional right?: string;

rotateLeft?

optional rotateLeft?: string;

rotateRight?

optional rotateRight?: string;

up?

optional up?: string;

maxDistance?

optional maxDistance?: number;

Maximum boom length, metres; default 40.

minDistance?

optional minDistance?: number;

Minimum boom length, metres; default 6.

panSpeed?

optional panSpeed?: number;

Metres/second at distance 10, scaled by distance; default 10.

pitch?

optional pitch?: number;

Tilt below the horizon, radians; default 55 degrees.

rotateStep?

optional rotateStep?: number;

Q/E rotation speed in radians/second; default PI/2.

zoomStep?

optional zoomStep?: number;

Fractional wheel zoom per line/notch; default 0.1.

TopDownCameraState

JSON camera pose; save this object and restore it with Object.assign(rig.state, saved).

Example

const state: TopDownCameraState = createTopDownCamera().state;

Properties

distance

distance: number;

Metres from focus to eye.

focus

focus: Vec3;

Ground point to look at.

fovYDeg

fovYDeg: number;

Vertical field of view, degrees.

pitch

pitch: number;

Radians below the horizon, in (0, PI/2].

yaw

yaw: number;

Radians about +Y; zero puts the eye on the +Z side.

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;

TrapDoorProps

Floor hatch dimensions: height is depth along local Z, thickness along local Y.

Example

const props: Partial<TrapDoorProps> = { swingDegrees: 90 };

Extends

DoorCoreProps

Properties

action

action: string;

Inherited from

asset?

optional asset?: string;

Inherited from

autoCloseSeconds

autoCloseSeconds: number;

Inherited from

closePrompt

closePrompt: string;

Inherited from

closeSound

closeSound: string;

Inherited from

colour

colour: [number, number, number];

Inherited from

consumeKey

consumeKey: boolean;

Inherited from

enabled

enabled: boolean;

Inherited from

facingDegrees

facingDegrees: number;

Inherited from

height

height: number;

Closed doorway height in metres.

Inherited from

lockedBy

lockedBy: string;

Inherited from

lockedMessage

lockedMessage: string;

Inherited from

lockedPrompt

lockedPrompt: string;

Inherited from

lockedSound

lockedSound: string;

Inherited from

look

look: "none" | "wood" | "metal";

Inherited from

once

once: boolean;

Inherited from

openPrompt

openPrompt: string;

Inherited from

openSound

openSound: string;

Inherited from

opensWhen

opensWhen: string[];

Inherited from

prompt

prompt: string;

Inherited from

range

range: number;

Inherited from

seconds

seconds: number;

Inherited from

startOpen

startOpen: boolean;

Inherited from

stayOpen

stayOpen: boolean;

Inherited from

swingDegrees

swingDegrees: number;

thickness

thickness: number;

Leaf thickness in metres.

Inherited from

toggledBy

toggledBy: "proximity" | "interact" | "signal";

Inherited from

width

width: number;

Closed doorway width in metres.

Inherited from

TriggerHandlers

Named trigger transitions, dispatched by the actor runtime's overlap events.

Example

const handlers: TriggerHandlers = { enter: (other, ctx) => ctx.hud.set({ entered: true }) };

Properties

enter?

optional enter?: (other, ctx) => void;

Runs once on entry; actors need overlaps:true, players are watched automatically.

Parameters

Parameter	Type
`other`	`ActorOther`
`ctx`	`GameContext`

Returns

void

exit?

optional exit?: (other, ctx) => void;

Runs once on exit, including watched entity removal.

Parameters

Parameter	Type
`other`	`ActorOther`
`ctx`	`GameContext`

Returns

void

Triggers

Guest-side point zones, independent of physics. Inside queries reflect the last step. All exits precede all enters, volume ascending then watch insertion order. Removing/unwatching fires exits in watch/volume order only when ctx is supplied.

Example

import { createTriggers, type Triggers } from 'gameable';
const zones: Triggers = createTriggers({ capacity: 4, watchCapacity: 8 });
zones.addSphere(0, 0, 0, 2);

Extends

GameplayPart

Methods

addBox()

addBox(
   minX, 
   minY, 
   minZ, 
   maxX, 
   maxY, 
   maxZ
): number;

Add inclusive bounds, returning the first free volume index.

Parameters

Parameter	Type
`minX`	`number`
`minY`	`number`
`minZ`	`number`
`maxX`	`number`
`maxY`	`number`
`maxZ`	`number`

Returns

number

addSphere()

addSphere(
   x, 
   y, 
   z, 
   radius
): number;

Add an inclusive sphere; radius must be nonnegative.

Parameters

Parameter	Type
`x`	`number`
`y`	`number`
`z`	`number`
`radius`	`number`

Returns

number

count()

count(volume): number;

Number of watched entities last observed inside.

Parameters

Parameter	Type
`volume`	`number`

Returns

number

enable()

enable(volume, on): void;

Disable/enable; exits from disabling are reported next step.

Parameters

Parameter	Type
`volume`	`number`
`on`	`boolean`

Returns

void

inside()

inside(volume, entity): boolean;

Last observed containment, including pending disabled-volume exits.

Parameters

Parameter	Type
`volume`	`number`
`entity`	`number`

Returns

boolean

moveTo()

moveTo(
   volume, 
   x, 
   y, 
   z
): void;

Recenter a volume, preserving its size.

Parameters

Parameter	Type
`volume`	`number`
`x`	`number`
`y`	`number`
`z`	`number`

Returns

void

remove()

remove(volume, ctx?): void;

Free a volume, optionally reporting its exits in watch order.

Parameters

Parameter	Type
`volume`	`number`
`ctx?`	`GameContext`

Returns

void

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

Inherited from

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

step()

step(ctx): void;

Test geometry, emit all exits then enters, and auto-unwatch deleted entities.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

unwatch()

unwatch(entity, ctx?): void;

Remove a watch, preserving the other watches' order.

Parameters

Parameter	Type
`entity`	`number`
`ctx?`	`GameContext`

Returns

void

watch()

watch(entity): void;

Watch once, in insertion order. Throws if full.

Parameters

Parameter	Type
`entity`	`number`

Returns

void

Turns

Ascending seat order with phases and a fixed-step turn clock. A sole active seat passes back to itself and increments the round; no active seats leaves current() at -1. Reviving a seat does not start a stopped game: call start. Events are synchronous: round (when crossed), turn, phase; timeout precedes these. Skips are consumed once, in ascending traversal order. Eliminating the current seat ends its turn immediately using the ctx supplied to eliminate. No game context is retained between calls.

Example

import { createTurns, type Turns } from 'gameable';
const turns: Turns = createTurns({ seats: 2, phases: ['draw', 'act'] });
turns.reset();

Extends

GameplayPart

Methods

active()

active(seat): boolean;

Whether this seat has not been eliminated.

Parameters

Parameter	Type
`seat`	`number`

Returns

boolean

current()

current(): number;

Current seat, or -1 when none is taking a turn.

Returns

number

elapse()

elapse(ctx, seconds): number;

Consume sleeping wall time as steps; at most seats * 1000 timeouts, then restart the clock in full.

Parameters

Parameter	Type
`ctx`	`GameContext`
`seconds`	`number`

Returns

number

eliminate()

eliminate(ctx, seat): void;

Eliminate a seat, immediately ending its current turn with callbacks using ctx.

Parameters

Parameter	Type
`ctx`	`GameContext`
`seat`	`number`

Returns

void

endTurn()

endTurn(ctx): void;

Pass to the next eligible seat.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

isTurn()

isTurn(seat): boolean;

True if this active seat owns the current turn.

Parameters

Parameter	Type
`seat`	`number`

Returns

boolean

nextPhase()

nextPhase(ctx): void;

Advance phase, ending the turn after the final phase.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

phase()

phase(): number;

Current phase index, or -1 when no turn is active.

Returns

number

phaseId()

phaseId(): string;

Current phase id, or the empty string when no turn is active.

Returns

string

remainingSeconds()

remainingSeconds(): number;

Remaining whole steps multiplied by the dt captured when this turn began.

Returns

number

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

Inherited from

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

revive()

revive(seat): void;

Make a seat eligible again.

Parameters

Parameter	Type
`seat`	`number`

Returns

void

round()

round(): number;

Round number; zero before start.

Returns

number

skipNext()

skipNext(seat): void;

Skip the seat's next turn; repeated calls do not stack.

Parameters

Parameter	Type
`seat`	`number`

Returns

void

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

start()

start(ctx, firstSeat?): void;

Begin round one, preserving eliminated seats and pending skips.

Parameters

Parameter	Type
`ctx`	`GameContext`
`firstSeat?`	`number`

Returns

void

step()

step(ctx): void;

Count one step; timeout, then endTurn when the clock reaches zero.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

Tweens

Preallocated numeric lane animations. Reset clears animations, leaving lanes intact.

Example

import { createTweens, type Tweens } from 'gameable';
const tweens: Tweens = createTweens({ capacity: 8 });
tweens.reset();

Extends

GameplayPart

Methods

active()

active(tween): boolean;

Whether a slot is running. Invalid slots throw RangeError.

Parameters

Parameter	Type
`tween`	`number`

Returns

boolean

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

Inherited from

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

start()

start(
   ctx, 
   lane, 
   index, 
   to, 
   seconds, 
   easing?, 
   options?
): number;

Start at the current value or explicit from; replace the same target without onDone. A Transform-lane tween must be stepped inside a game system.

Parameters

Parameter	Type
`ctx`	`GameContext`
`lane`	`Float32Array`
`index`	`number`
`to`	`number`
`seconds`	`number`
`easing?`	\| `"linear"` \| `"quadIn"` \| `"quadOut"` \| `"quadInOut"` \| `"cubicIn"` \| `"cubicOut"` \| `"cubicInOut"` \| `"sineIn"` \| `"sineOut"` \| `"sineInOut"` \| `"backOut"` \| `"elasticOut"` \| `"bounceOut"`
`options?`	{ `from?`: `number`; `loop?`: `"none"` \| `"repeat"` \| `"yoyo"`; }
`options.from?`	`number`
`options.loop?`	`"none"` \| `"repeat"` \| `"yoyo"`

Returns

number

step()

step(ctx): void;

Advance all slots, then call onDone synchronously in ascending slot order. Transform-lane tweens must be stepped inside a game system with a running guest.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

stop()

stop(tween): void;

Free one slot without onDone. Invalid slots throw RangeError.

Parameters

Parameter	Type
`tween`	`number`

Returns

void

stopAll()

stopAll(lane?, index?): void;

Stop all, all on a lane, or one index on a lane.

Parameters

Parameter	Type
`lane?`	`Float32Array`<`ArrayBufferLike`>
`index?`	`number`

Returns

void

UiBar

A progress meter: health, a timer, loading.

Example

import type { UiBar } from 'gameable';
const example: UiBar = { type: 'bar', value: 80, max: 100 };
console.log(example);

Extends

UiNodeBase

Properties

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id?

optional id?: string;

The node's name. Required for anything that sends events (a button, a clickable card, a draggable, a drop target, an input), and it keeps a node's DOM (focus, scroll, a drag in progress) across ui.set calls. Unique within one model.

Inherited from

label?

optional label?: string;

A label above the track.

max

max: number;

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

tone?

optional tone?: "accent" | "danger";

Defaults to accent; turns pink at or below a third unless tone is set.

type

type: "bar";

value

value: number;

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

UiButton

A pressable button. Sends click, focus and blur.

Example

import type { UiButton } from 'gameable';
const example: UiButton = { type: 'button', id: 'play', text: 'Play' };
console.log(example);

Extends

UiNodeBase

Properties

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

disabled?

optional disabled?: boolean;

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id

id: string;

Overrides

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

selected?

optional selected?: boolean;

Drawn as chosen (mint ring), e.g. the picked answer.

text

text: string;

type

type: "button";

variant?

optional variant?: "danger" | "primary" | "secondary" | "ghost";

Defaults to secondary. primary is the mint call to action.

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

UiCard

A card: a surface with an optional title and body, or children. With an id it is clickable; with draggable it can be picked up.

Example

import type { UiCard } from 'gameable';
const example: UiCard = { type: 'card', title: 'Ace', draggable: true, id: 'ace' };
console.log(example);

Extends

UiNodeBase.UiLayout

Properties

align?

optional align?: "center" | "start" | "end" | "stretch";

Cross-axis alignment. Defaults to stretch.

Inherited from

UiLayout.align

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

body?

optional body?: string;

children?

optional children?: readonly UiNode[];

direction?

optional direction?: "column" | "row";

Main axis. Defaults to column.

Inherited from

UiLayout.direction

disabled?

optional disabled?: boolean;

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

gap?

optional gap?: number;

Space between children, CSS px. Defaults to the theme's gap.

Inherited from

UiLayout.gap

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id?

optional id?: string;

Inherited from

justify?

optional justify?: "center" | "start" | "end" | "between";

Main-axis distribution. Defaults to start.

Inherited from

UiLayout.justify

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

selected?

optional selected?: boolean;

title?

optional title?: string;

tone?

optional tone?: "default" | "accent" | "danger";

Tint the card: accent mint, danger pink.

type

type: "card";

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

wrap?

optional wrap?: boolean;

Wrap onto more lines when the row is full.

Inherited from

UiLayout.wrap

UiEvent

One UI event, as the guest receives it. Mirrors WIT ui-event.

Example

import type { UiEvent } from 'gameable';
const example: UiEvent = { kind: 'click', id: 'play', target: '', value: '', x: 0, y: 0 };
console.log(example);

Properties

id

id: string;

The node's id: the button clicked, the card dragged, the input edited.

kind

kind: UiEventKind;

target

target: string;

For drop: the drop target's id. Empty otherwise.

value

value: string;

For change and submit: the field's text. Empty otherwise.

x

x: number;

Pointer position, CSS px from the game view's top-left; 0 for keyboard.

y

y: number;

Pointer position, CSS px from the game view's top-left; 0 for keyboard.

UiGrid

A grid of equal columns, filled row by row.

Example

import type { UiGrid } from 'gameable';
const example: UiGrid = { type: 'grid', columns: 2, children: [] };
console.log(example);

Extends

UiNodeBase

Properties

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

children

children: readonly UiNode[];

columns

columns: number;

Number of columns.

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

gap?

optional gap?: number;

Space between cells, CSS px.

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id?

optional id?: string;

Inherited from

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

type

type: "grid";

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

UiInput

A one-line text field. Sends change on every edit and submit on Enter.

Example

import type { UiInput } from 'gameable';
const example: UiInput = { type: 'input', id: 'name', placeholder: 'Your name' };
console.log(example);

Extends

UiNodeBase

Properties

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id

id: string;

Overrides

maxLength?

optional maxLength?: number;

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

placeholder?

optional placeholder?: string;

Shown until the player types; the field keeps what they type.

type

type: "input";

value?

optional value?: string;

Replace what is in the field. Leave it unset to keep what the player typed.

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

UiLayout

How children of a container are laid out.

Example

import type { UiLayout } from 'gameable';
const example: UiLayout = { direction: 'row', gap: 8 };
console.log(example);

Extended by

UiStack
UiPanel
UiCard

Properties

align?

optional align?: "center" | "start" | "end" | "stretch";

Cross-axis alignment. Defaults to stretch.

direction?

optional direction?: "column" | "row";

Main axis. Defaults to column.

gap?

optional gap?: number;

Space between children, CSS px. Defaults to the theme's gap.

justify?

optional justify?: "center" | "start" | "end" | "between";

Main-axis distribution. Defaults to start.

wrap?

optional wrap?: boolean;

Wrap onto more lines when the row is full.

UiList

A vertical scrolling list.

Example

import type { UiList } from 'gameable';
const example: UiList = { type: 'list', children: [], maxHeight: 300 };
console.log(example);

Extends

UiNodeBase

Properties

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

children

children: readonly UiNode[];

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

gap?

optional gap?: number;

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id?

optional id?: string;

Inherited from

maxHeight?

optional maxHeight?: number;

Scroll past this height, CSS px.

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

type

type: "list";

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

UiModel

What frame-output.ui carries, as JSON.

Example

import type { UiModel } from 'gameable';
const example: UiModel = { nodes: [{ type: 'text', text: 'Ready' }] };
console.log(example);

Properties

nodes

nodes: readonly UiNode[];

Top-level nodes, drawn in order (later on top).

theme?

optional theme?: UiTheme;

UiNodeBase

Fields every node may carry.

Example

import type { UiNodeBase } from 'gameable';
const example: UiNodeBase = { id: 'menu', anchor: 'center' };
console.log(example);

Extended by

UiStack
UiGrid
UiPanel
UiText
UiButton
UiCard
UiList
UiBar
UiInput

Properties

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

height?

optional height?: number;

Fixed height, CSS px.

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

id?

optional id?: string;

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

padding?

optional padding?: number;

Inner padding, CSS px.

width?

optional width?: number;

Fixed width, CSS px.

UiPanel

A surface (glass card) holding a stack: menus, dialogs, side panels.

Example

import type { UiPanel } from 'gameable';
const example: UiPanel = { type: 'panel', title: 'Menu', children: [] };
console.log(example);

Extends

UiNodeBase.UiLayout

Properties

align?

optional align?: "center" | "start" | "end" | "stretch";

Cross-axis alignment. Defaults to stretch.

Inherited from

UiLayout.align

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

children?

optional children?: readonly UiNode[];

direction?

optional direction?: "column" | "row";

Main axis. Defaults to column.

Inherited from

UiLayout.direction

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

gap?

optional gap?: number;

Space between children, CSS px. Defaults to the theme's gap.

Inherited from

UiLayout.gap

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id?

optional id?: string;

Inherited from

justify?

optional justify?: "center" | "start" | "end" | "between";

Main-axis distribution. Defaults to start.

Inherited from

UiLayout.justify

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

title?

optional title?: string;

A title line at the top.

type

type: "panel";

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

wrap?

optional wrap?: boolean;

Wrap onto more lines when the row is full.

Inherited from

UiLayout.wrap

UiStack

A transparent stack of children: the basic layout box.

Example

import type { UiStack } from 'gameable';
const example: UiStack = { type: 'stack', children: [] };
console.log(example);

Extends

UiNodeBase.UiLayout

Properties

align?

optional align?: "center" | "start" | "end" | "stretch";

Cross-axis alignment. Defaults to stretch.

Inherited from

UiLayout.align

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

children

children: readonly UiNode[];

direction?

optional direction?: "column" | "row";

Main axis. Defaults to column.

Inherited from

UiLayout.direction

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

gap?

optional gap?: number;

Space between children, CSS px. Defaults to the theme's gap.

Inherited from

UiLayout.gap

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id?

optional id?: string;

Inherited from

justify?

optional justify?: "center" | "start" | "end" | "between";

Main-axis distribution. Defaults to start.

Inherited from

UiLayout.justify

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

type

type: "stack";

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

wrap?

optional wrap?: boolean;

Wrap onto more lines when the row is full.

Inherited from

UiLayout.wrap

UiText

A line or paragraph of text.

Example

import type { UiText } from 'gameable';
const example: UiText = { type: 'text', text: 'Ready' };
console.log(example);

Extends

UiNodeBase

Properties

align?

optional align?: "center" | "start" | "end";

anchor?

optional anchor?: UiScreenAnchor | UiWorldAnchor;

Top-level nodes only: where it sits. Defaults to center.

Inherited from

draggable?

optional draggable?: boolean;

This node can be picked up and dropped on a dropTarget. Needs an id.

Inherited from

dropTarget?

optional dropTarget?: boolean;

Draggables can be dropped here. Needs an id.

Inherited from

grow?

optional grow?: boolean;

Take the remaining space in the parent stack.

Inherited from

height?

optional height?: number;

Fixed height, CSS px.

Inherited from

hidden?

optional hidden?: boolean;

Leave the node out without removing it from the tree.

Inherited from

id?

optional id?: string;

Inherited from

optional modal?: boolean;

Top-level nodes only: dim the game behind it and take every pointer event.

Inherited from

offset?

optional offset?: readonly [number, number];

Top-level nodes only: extra shift from the anchor, CSS px [x, y].

Inherited from

padding?

optional padding?: number;

Inner padding, CSS px.

Inherited from

size?

optional size?: "sm" | "md" | "lg" | "xl" | "display";

Defaults to md. display is the big centred "You win" size.

text

text: string | number;

tone?

optional tone?: "default" | "muted" | "accent" | "danger";

Defaults to default. accent is mint, danger is pink.

type

type: "text";

width?

optional width?: number;

Fixed width, CSS px.

Inherited from

GameplayModule.system

UiTheme

Theme tokens. Every field is optional; what is left out is the Gameable look (STYLE.md). Colours are CSS colour strings.

Example

import type { UiTheme } from 'gameable';
const example: UiTheme = { scale: 1.2, gap: 8 };
console.log(example);

Properties

accent?

optional accent?: string;

The accent: primary buttons, selection, progress.

backdrop?

optional backdrop?: string;

Behind a modal.

border?

optional border?: string;

Hairlines and borders.

danger?

optional danger?: string;

Errors, danger buttons, low bars, the focus ring.

font?

optional font?: string;

CSS font-family.

gap?

optional gap?: number;

Default gap between children, CSS px.

muted?

optional muted?: string;

Secondary text, labels.

onAccent?

optional onAccent?: string;

Text on an accent background.

radius?

optional radius?: number;

Card and panel corner radius, CSS px.

scale?

optional scale?: number;

Multiplies every size; 1 is the default.

surface?

optional surface?: string;

Panels and cards.

surfaceRaised?

optional surfaceRaised?: string;

Secondary buttons, tracks, inputs.

text?

optional text?: string;

Primary text.

UiWorldAnchor

Pin a top-level node to a point in the 3D world: over an entity, or at a fixed position. The node's bottom-centre sits on the projected point, and it hides while the point is behind the camera.

Example

import type { UiWorldAnchor } from 'gameable';
const example: UiWorldAnchor = { entity: 1, offset: [0, 2, 0] };
console.log(example);

Properties

entity?

optional entity?: number;

Follow this entity's position.

offset?

optional offset?: readonly [number, number, number];

Added to the point before projecting, world metres (e.g. [0, 2, 0] above a head).

position?

optional position?: readonly [number, number, number];

A fixed world position, metres. Ignored when entity is set.

ValidateLevelOptions

What validateLevel takes besides the document.

Extended by

ApplyLevelEditsOptions

Properties

catalog?

optional catalog?: ReadonlyMap<string, ActorClass<object>>;

Detached declarations for static tools; bypasses the live registry and deprecation logging.

classes?

optional classes?: readonly string[] | "any";

Vec3

A 3-component vector.

Extended by

WorldStand

Properties

x

x: number;

y

y: number;

z

z: number;

VehicleBindings

Key bindings saved with the controller. Set controller.state.frozen or pawn.state.frozen to park.

Example

bindVehicleInput(controller, { brake: 'Control' });

Properties

brake?

optional brake?: string;

forward?

optional forward?: string;

handbrake?

optional handbrake?: string;

left?

optional left?: string;

reverse?

optional reverse?: string;

right?

optional right?: string;

VehicleGripVolumeProps

Spherical oil area lifetime and tyre recovery, in seconds.

Example

const props: VehicleGripVolumeProps = { radius: 3, duration: 8, gripScale: 0.15, recovery: 1 };

Properties

duration

duration: number;

gripScale

gripScale: number;

radius

radius: number;

recovery

recovery: number;

VehicleInput

Normalized control intent; throttle/steer [-1,1], brakes [0,1].

Example

const input: VehicleInput = { throttle: 1, steer: 0, brake: 0, handbrake: 0 };

Properties

brake

brake: number;

handbrake

handbrake: number;

steer

steer: number;

throttle

throttle: number;

VehicleSettings

SI settings; steerAngle is degrees and steerRate degrees/second. Curves map absolute speed (m/s) and dimensionless slip to multipliers. downforce is N/(m/s)^2; uprightAssist is maximum N m; airControl is [0,1]. antiRoll is the host axle load transfer stiffness in N/m.

Example

import { physics, type VehicleSettings } from 'gameable';
function attach(body: number, settings: VehicleSettings): void {
  physics.vehicle.create(body, settings);
}

Properties

acceleration

acceleration: number;

airControl

airControl: number;

antiRoll

antiRoll: number;

brakeDeceleration

brakeDeceleration: number;

downforce

downforce: number;

driftRecovery

driftRecovery: number;

gripBySlip

gripBySlip: VehicleCurve;

halfExtents

halfExtents: readonly [number, number, number];

mass

mass: number;

maxSpeed

maxSpeed: number;

rearHandbrakeGrip

rearHandbrakeGrip: number;

reverseAsBrake

reverseAsBrake: boolean;

reverseSpeed

reverseSpeed: number;

rollingDrag

rollingDrag: number;

steerAngle

steerAngle: number;

steeringBySpeed

steeringBySpeed: VehicleCurve;

steerRate

steerRate: number;

uprightAssist

uprightAssist: number;

wheels

wheels: readonly [VehicleWheel, VehicleWheel, VehicleWheel, VehicleWheel];

VehicleState

Borrowed mutable state; speed is signed m/s, steer is radians. supportBits uses bits 0..3 in settings wheel order.

Example

const state: VehicleState = { speed: 0, supportBits: 0, steer: 0,
  reversing: false, braking: false, wheels: Array.from({ length: 4 },
    () => ({ compression: 0, spin: 0, slip: 0, grip: 1 })) };

Properties

braking

braking: boolean;

reversing

reversing: boolean;

speed

speed: number;

steer

steer: number;

supportBits

supportBits: number;

wheels

wheels: VehicleWheelState[];

VehicleWheel

Wheel geometry in metres, frequency in Hz, and dimensionless damping. Mount coordinates use chassis-local axes; handbrake marks the rear axle.

Example

const wheel: VehicleWheel = { mount: [-0.8, 0, 1.3], radius: 0.34,
  restLength: 0.4, travel: 0.3, springHz: 2, dampingRatio: 0.8,
  steer: true, driven: true, handbrake: false };

Properties

dampingRatio

dampingRatio: number;

driven

driven: boolean;

handbrake

handbrake: boolean;

mount

mount: readonly [number, number, number];

radius

radius: number;

restLength

restLength: number;

springHz

springHz: number;

steer

steer: boolean;

travel

travel: number;

VehicleWheelState

Persistent wheel telemetry and grip recovery history; spin is radians.

Example

const wheel: VehicleWheelState = { compression: 0, spin: 0, slip: 0, grip: 1 };

Properties

compression

compression: number;

grip

grip: number;

slip

slip: number;

spin

spin: 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;

VfxOptions

Options for particle effects and the page's base look.

Example

import type { VfxOptions } from 'gameable';
const options: VfxOptions = { post: { bloom: 0.5 } };

Properties

post?

optional post?: PostSettings;

Base look applied before the guest runs, also received by late joiners.

Viewport

View dimensions in the screen point's units.

Example

const view: Viewport = { width: 800, height: 600 };

Properties

height

height: number;

width

width: number;

WalkCharacterToCmd

Walk a character to a spot (see character.walkTo).

Properties

entity

entity: number;

facing?

optional facing?: number;

The facing to arrive with, radians about +Y (0 faces +Z); absent: as it arrives.

pace

pace: number;

Metres a second; 0 is the set's own walk.

quick

quick: boolean;

The shortest stops and turns the set has, instead of unhurried ones.

start?

optional start?: "moving";

How it is begun: 'moving', the game says the body is under way already. Absent: as the character's takes have the body, as ever.

stop?

optional stop?: StopStyle;

Which kind of stop this one walk ends with: 'gradual' (it slows and stands upright) or 'hard' (it brakes). Absent: the character's own; a quick walk that states none stops as a quick walk always did.

target

target: Vec3;

The spot, world space, on the floor.

WalkJumpModule

Walking system and declarative player configuration.

Example

import type { WalkJumpModule } from 'gameable';
const inspect = (walk: WalkJumpModule) => walk.player.camera;
console.log(inspect);

Extends

GameplayModule

Properties

init

init: (ctx) => void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

Inherited from

GameplayModule.init

player

readonly player: PlayerSpec;

system

system: (ctx) => void;

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

Inherited from

WalkJumpModuleOptions

Existing third-person controls with an invisible prediction capsule.

Example

import type { WalkJumpModuleOptions } from 'gameable';
const inspect = (options: WalkJumpModuleOptions) => options.walkSpeed;
console.log(inspect);

Properties

body

body: BodySpec;

camera

camera: object;

camera

camera: "thirdPerson";

distance

distance: number;

height

height: number;

sensitivity

sensitivity: number;

cameraMaxPitch

cameraMaxPitch: number;

cameraMinPitch

cameraMinPitch: number;

cameraPitch

cameraPitch: number;

characters

characters: readonly string[];

jumpSpeed

jumpSpeed: number;

prediction

prediction: "own-body";

runSpeed

runSpeed: number;

scheme

scheme: "third-person";

spawns

spawns: readonly readonly number[][];

walkSpeed

walkSpeed: number;

Waves

Timed waves. A zero delay spawns on the first step; positive delays and intervals count whole steps. Capacity holds the clock, including the delay. Clear fires on the step observing no survivors after all attempts; the next wave starts on the following step. Spawn indices ascend from zero, including failed spawns. stop discards tracking without despawning entities or events.

Example

import { createWaves, type Waves } from 'gameable';
const waves: Waves = createWaves({ waves: [{ count: 3, every: 1 }], onSpawn: () => 0 });
waves.reset();

Extends

GameplayPart

Methods

alive()

alive(): number;

Number of tracked surviving entities.

Returns

number

finished()

finished(): boolean;

True only after the final clear, until reset/start/stop.

Returns

boolean

killed()

killed(entity): boolean;

Remove a tracked nonzero entity; returns whether found.

Parameters

Parameter	Type
`entity`	`number`

Returns

boolean

reset()

reset(): void;

Back to the state right after creation. Call from init.

Returns

void

Inherited from

restore()

restore(state, options?): void;

Read back what snapshot returned. Throws on a malformed state.

Parameters

Parameter	Type
`state`	`unknown`
`options?`	{ `crossBuild?`: `boolean`; }
`options.crossBuild?`	`boolean`

Returns

void

Inherited from

snapshot()

snapshot(): unknown;

Plain JSON-safe data for defineGame({ snapshot }).

Returns

unknown

Inherited from

ActorComponent.attach

spawned()

spawned(): number;

Attempts in this wave.

Returns

number

start()

start(ctx): void;

Restart at wave zero, discarding previous tracking. Empty lists finish immediately.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

step()

step(ctx): void;

Advance one fixed step.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

stop()

stop(): void;

Halt and discard tracking without callbacks.

Returns

void

wave()

wave(): number;

Current index, or -1 before start and after stop.

Returns

number

WaypointMovementComponent

Reusable path component with per-actor controls.

Example

const movement: WaypointMovementComponent = waypointMovement({ points: [{x: 2,y: 0,z: 0}], speed: 1, mode: 'once' });

Extends

ActorComponent

Properties

asset?

optional asset?: string;

Manifest asset id for a mesh.

Inherited from

ActorComponent.asset

attach?

optional attach?: string;

Parent component name; defaults to root for non-root components.

Inherited from

body?

optional body?: "kinematic" | "dynamic" | "static";

Blocking body motion; defaults to static.

Inherited from

ActorComponent.body

ccd?

optional ccd?: boolean;

Continuous collision detection for fast dynamic bodies.

Inherited from

ActorComponent.ccd

collision?

optional collision?: 
  | "none"
  | "overlap"
  | "block"
  | CollisionSetup
  | "NoCollision"
  | "BlockAll"
  | "OverlapAll"
  | "BlockAllDynamic"
  | "OverlapAllDynamic"
  | "IgnoreOnlyPawn"
  | "OverlapOnlyPawn"
  | "Pawn"
  | "Spectator"
  | "CharacterMesh"
  | "PhysicsActor"
  | "Destructible"
  | "InvisibleWall"
  | "InvisibleWallDynamic"
  | "Trigger"
  | "Ragdoll"
  | "Vehicle"
  | "UI";

Collision response; defaults to block.

Inherited from

ActorComponent.collision

dimensions?

optional dimensions?: readonly string[];

Spawn-time prop names supplying dimensions: ['halfExtents'] or ['radius', 'halfHeight'].

Inherited from

ActorComponent.dimensions

dims?

optional dims?: readonly number[];

Primitive dimensions in metres.

Inherited from

ActorComponent.dims

fit?

optional fit?: "box" | "convex-hull" | "mesh";

Inherited from

ActorComponent.fit

kind

kind: "character" | "box" | "sphere" | "capsule" | "mesh" | "scene";

Component family.

Inherited from

ActorComponent.kind

layer?

optional layer?: CollisionLayers;

Physics collision layer.

Inherited from

ActorComponent.layer

mask?

optional mask?: CollisionLayers;

Raw physics mask; cannot accompany a named/custom collision policy.

Inherited from

ActorComponent.mask

mass?

optional mass?: number;

Dynamic mass in kilograms.

Inherited from

ActorComponent.mass

offset?

optional offset?: readonly [number, number, number];

Translation in the parent's space.

Inherited from

ActorComponent.offset

reportHits?

optional reportHits?: boolean;

Request blocking contact callbacks.

Inherited from

ActorComponent.reportHits

rotation?

optional rotation?: Quat;

Local quaternion, default identity.

Inherited from

ActorComponent.rotation

scale?

optional scale?: readonly [number, number, number];

Local per-axis scale, default one.

Inherited from

ActorComponent.scale

Methods

create()?

optional create(
   self, 
   ctx, 
   name
): void;

Initialize JSON-safe component state during authority spawn.

Parameters

Parameter	Type
`self`	`ActorHandle`
`ctx`	`GameContext`
`name`	`string`

Returns

void

Inherited from

ActorComponent.create

destroy()?

optional destroy(
   self, 
   ctx, 
   name
): void;

Release component bookkeeping on authority destruction, before entities are despawned.

Parameters

Parameter	Type
`self`	`ActorHandle`
`ctx`	`GameContext`
`name`	`string`

Returns

void

Inherited from

ActorComponent.destroy

handle()

handle(actor): WaypointMovementHandle;

Parameters

Parameter	Type
`actor`	`ActorHandle`

Returns

WaypointMovementHandle

step()?

optional step(
   self, 
   ctx, 
   name
): void;

Advance on each authority fixed step, before the actor tick.

Parameters

Parameter	Type
`self`	`ActorHandle`
`ctx`	`GameContext`
`name`	`string`

Returns

void

Inherited from

ActorComponent.step

WaypointMovementHandle

Controls one actor's interpolation, including after snapshot restore.

Example

movement.handle(platform).pause();

Methods

pause()

pause(): void;

Returns

void

play()

play(): void;

Returns

void

reverse()

reverse(): void;

Returns

void

WaypointMovementOptions

Relative path configuration. Seconds covers the complete path, including spawn to point zero.

Example

const path: WaypointMovementOptions = { points: [{ x: 0, y: 2, z: 0 }], seconds: 2, mode: 'pingPong' };

Extended by

MovingPlatformProps

Properties

mode

mode: "loop" | "once" | "pingPong";

points

points: readonly (readonly [number, number, number] | Vec3)[];

seconds?

optional seconds?: number;

speed?

optional speed?: number;

startPaused?

optional startPaused?: boolean;

waitSeconds?

optional waitSeconds?: number;

WheeledVehicleProps

Handling overrides and manifest visual ids; empty ids use chassis debug geometry.

Example

const props: WheeledVehicleProps = { handling: 'drift', asset: 'car', wheelAsset: 'wheel' };

Extends

VehicleOptions

Properties

acceleration?

optional acceleration?: number | null;

Inherited from

VehicleSettings.acceleration

airControl?

optional airControl?: number | null;

Inherited from

VehicleSettings.airControl

antiRoll?

optional antiRoll?: number | null;

Inherited from

VehicleSettings.antiRoll

asset?

optional asset?: string;

brakeDeceleration?

optional brakeDeceleration?: number | null;

Inherited from

VehicleSettings.brakeDeceleration

collision?

optional collision?: "Vehicle" | null;

Inherited from

VehicleOptions.collision

downforce?

optional downforce?: number | null;

Inherited from

VehicleSettings.downforce

driftRecovery?

optional driftRecovery?: number | null;

Inherited from

VehicleSettings.driftRecovery

gripBySlip?

optional gripBySlip?: VehicleCurve | null;

Inherited from

VehicleSettings.gripBySlip

halfExtents?

optional halfExtents?: readonly [number, number, number] | null;

Inherited from

VehicleSettings.halfExtents

handling?

optional handling?: "arcade" | "grippy" | "drift";

Inherited from

VehicleOptions.handling

mass?

optional mass?: number | null;

Inherited from

VehicleSettings.mass

maxSpeed?

optional maxSpeed?: number | null;

Inherited from

VehicleSettings.maxSpeed

rearHandbrakeGrip?

optional rearHandbrakeGrip?: number | null;

Inherited from

VehicleSettings.rearHandbrakeGrip

reverseAsBrake?

optional reverseAsBrake?: boolean | null;

Inherited from

VehicleSettings.reverseAsBrake

reverseSpeed?

optional reverseSpeed?: number | null;

Inherited from

VehicleSettings.reverseSpeed

rollingDrag?

optional rollingDrag?: number | null;

Inherited from

VehicleSettings.rollingDrag

steerAngle?

optional steerAngle?: number | null;

Inherited from

VehicleSettings.steerAngle

steeringBySpeed?

optional steeringBySpeed?: VehicleCurve | null;

Inherited from

VehicleSettings.steeringBySpeed

steerRate?

optional steerRate?: number | null;

Inherited from

VehicleSettings.steerRate

uprightAssist?

optional uprightAssist?: number | null;

Inherited from

VehicleSettings.uprightAssist

wheelAsset?

optional wheelAsset?: string;

wheels?

optional wheels?: 
  | readonly [VehicleWheel, VehicleWheel, VehicleWheel, VehicleWheel]
  | null;

Inherited from

VehicleSettings.wheels

WorldEvent

What a made world tells the game: loaded (the list of things, as JSON in text), hit (a loose thing took a real knock: where, and how hard from 0 to 1), moved (a loose thing is somewhere new: the middle of its base and its turn), unloaded, and joint (a joint of a thing with moving parts stands somewhere new: position.x its place in the thing's list of joints, strength its value).

Properties

kind

kind: "joint" | "loaded" | "hit" | "moved" | "unloaded" | "broken" | "mended";

As above, and for a thing in pieces: broken (text the places in the list of the pieces that came off, with commas; strength 1 when nothing of it holds together) and mended.

position

position: Vec3;

hit: where the thing was when knocked. moved: the middle of its base now. joint: x is which joint.

rotation

rotation: Quat;

moved: how the thing is turned now.

strength

strength: number;

hit: how hard, 0 to 1. joint: the joint's value.

text

text: string;

loaded: the world's list as JSON (readWorldList). Empty otherwise.

thing

thing: number;

The thing's place in the world's list; 0 for loaded and unloaded.

WorldJoint

One joint of a thing with moving parts, as a game sees it.

Properties

at

at: Vec3;

A point on its axis, in the thing's own frame at rest.

axis

axis: Vec3;

Its axis, of length 1: a positive value turns right-handed about it, or slides along it.

free

free: boolean;

True for a joint with no limits (a wheel on its axle).

id

id: string;

The joint's name in the package, for example steering.

kind

kind: "hinge" | "break" | "slide";

A hinge turns (degrees); a slide moves (metres); a break holds two pieces until the thing breaks.

max

max: number;

The most its value may be; 0 for a joint that turns freely.

min

min: number;

The least its value may be; 0 for a joint that turns freely.

rest

rest: number;

The value the thing is drawn at when nothing is asked.

value

value: number;

Where it stands now (kept up to date by the joint event for a joint with limits).

WorldList

A world as a game sees it: the list handed over by the loaded event.

Properties

about

about: string;

One or two plain sentences about it.

bounds

bounds: 
  | {
  max: Vec3;
  min: Vec3;
}
  | null;

The place's box, when the package gives one.

eyeHeight

eyeHeight: number;

The height of a standing person's eyes above the ground, metres.

id

id: string;

The package's id.

kind

kind: "object" | "room" | "open";

room: walls all round. open: a field, a street. object: no place, a thing by itself on a level floor.

name

name: string;

The world's name, for a page.

spawn

spawn: WorldStand;

Where the player starts, on the ground.

things

things: WorldThing[];

Every thing, loose or fixed, in the package's order.

version

version: 1;

The list's own format; 1 today.

walk

walk: WorldWalk;

How far the player may walk.

WorldSpec

World-level settings.

Properties

gravity?

optional gravity?: number | readonly number[];

Gravity (m/s²) for entities with Velocity but no RigidBody; bodies take the physics world's.

maxEntities?

optional maxEntities?: number;

Entity ceiling. Sizes the built-in arrays. Default 4096.

WorldSpot

A named place where a rider meets a thing (seat, gripLeft, gripRight, footLeft, footRight), in the thing's own frame at rest (metres, the origin at the middle of its base, its front along +z, its left +x). It moves with the part it is on: spotOf says where it is now.

Properties

forward

forward: Vec3;

The way a character there faces (a grip: the way the knuckles point).

joints

joints: number[];

The joints that move it, by their place in the thing's list of joints, the nearest to the spot first.

name

name: string;

The spot's name in the package.

position

position: Vec3;

Where, at rest.

up

up: Vec3;

Up at the spot.

WorldSpotNow

Where a rider's spot is now, in the world: what spotOf fills.

Properties

forward

forward: Vec3;

The way a character there faces.

position

position: Vec3;

Where.

up

up: Vec3;

Up at the spot.

WorldStand

A place to stand: a point on the ground and which way to face.

Extends

Vec3

Properties

facing

facing: number;

Degrees about y, as a turn of a figure whose front is +z: 0 looks along +z, 90 along +x.

x

x: number;

Inherited from

Vec3.x

y

y: number;

Inherited from

Vec3.y

z

z: number;

Inherited from

Vec3.z

WorldThing

One thing in a world: its own object (loose) or part of the place (fixed).

Properties

about

about: string;

One sentence about it.

away?

optional away?: boolean;

True while it is not in the world: a piece that has not come off its thing, and a thing all of whose pieces have. find and near pass over it.

body

body: number;

The host's physics body for it, or 0 when it has none.

drives

drives: boolean;

True for a thing that can be driven (things.drive).

id

id: string;

The package's id for it, for example steamer-trunk.

index

index: number;

Its place in the list; what world-event and the world command name it by.

joints

joints: WorldJoint[];

Its joints, when it has moving parts; a joint's place here is what the joint command names.

kind

kind: string;

One plain noun, for example chest.

label

label: string;

What a person calls it, for example steamer trunk.

max

max: Vec3;

The high corner of its box, now.

min

min: Vec3;

The low corner of its box, now, along the world's axes.

moved

moved: boolean;

True once it has moved from where the package put it.

pieceOf?

optional pieceOf?: number;

For one piece of a thing in pieces: that thing's place in the list. Left out otherwise.

pieces?

optional pieces?: number[];

For a thing in pieces: its pieces' places in the list (things.breakApart). Left out otherwise.

position

position: Vec3;

The middle of its base, now, in metres.

rests

rests: string;

What it rests on: floor, on:<thing id>, hanging or wall.

rider

rider: WorldSpot[];

Where a rider meets it (things.getOn), when the package names such spots; else empty.

rotation

rotation: Quat;

How it is turned, now.

size

size: Vec3;

Width (x), height (y) and depth (z), in metres.

stand

stand: WorldStand | null;

Where the package says to stand to use it, or null when it says nothing.

state

state: "fixed" | "loose";

loose: its own object, which may move. fixed: part of the place.

WorldWalk

How far the player may walk.

Properties

centre

centre: Vec3;

The circle's middle (radius only).

fadeFrom

fadeFrom: number;

From here outward the player slows (radius only).

radius

radius: number;

Past this the player goes no further (radius only).

shape

shape: "inside-collision" | "radius";

inside-collision: the walls stop the player. radius: a circle with a soft edge.

Type Aliases

ActionDecl

type ActionDecl = 
  | {
  devices?: readonly ("keyboard" | "gamepad" | "touch")[];
  gamepad?: readonly number[];
  keys?: readonly string[];
  touch?: "tap" | "hold" | "doubleTap" | `button:${string}`;
}
  | {
  axis2: readonly [string, string, string, string];
  gamepadAxes?: readonly [number, number];
  stick?: "left" | "right";
};

A button or two-axis action, using the host action map's axis order and standard pad indices.

Union Members

Type Literal

{
  devices?: readonly ("keyboard" | "gamepad" | "touch")[];
  gamepad?: readonly number[];
  keys?: readonly string[];
  touch?: "tap" | "hold" | "doubleTap" | `button:${string}`;
}

Type Literal

{
  axis2: readonly [string, string, string, string];
  gamepadAxes?: readonly [number, number];
  stick?: "left" | "right";
}

axis2

axis2: readonly [string, string, string, string];

Keys for [-X, +X, -Y, +Y], matching the host action map.

gamepadAxes?

optional gamepadAxes?: readonly [number, number];

stick?

optional stick?: "left" | "right";

Example

import type { ActionDecl } from 'gameable';
const fire: ActionDecl = { keys: ['LMB'], gamepad: [7], touch: 'tap' };

ActorOther

type ActorOther = ActorHandle | number;

The other participant in an overlap or blocking contact; players use entity ids.

Example

const other: ActorOther = 1;

AgentState

type AgentState = typeof AgentState[keyof typeof AgentState];

One of AgentState.

AIControllerSpec

type AIControllerSpec<P> = Omit<ActorSpec<AIControllerProps & P>, "components"> & object;

Typed extension callback independent of the controller's movement component.

Type Declaration

components?

optional components?: ActorSpec<AIControllerProps & P>["components"];

Optional: a controller that declares none gets a plain scene() root.

onMoveCompleted()?

optional onMoveCompleted(
   self, 
   result, 
   ctx
): void;

Parameters

Parameter	Type
`self`	`ActorHandle`<`AIControllerProps` & `P`>
`result`	`"success"` \| `"aborted"`
`ctx`	`GameContext`

Returns

void

Type Parameters

Type Parameter	Default type
`P` extends `object`	`object`

Example

const spec: AIControllerSpec = { components: { root: scene() }, onMoveCompleted(self, result) {} };

AssetId

type AssetId = number;

Manifest asset handle, resolved from a string id.

AssetKind

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

Manifest asset family.

AudioBus

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

Audio mixer bus.

BeatQuantize

type BeatQuantize = "now" | "beat" | "bar";

Scheduling grid.

Example

`audio.playOnBeat('kick', { quantize: 'beat' });`

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.

BtCheck

type BtCheck<C> = (ctx, entity) => boolean;

A guard supplied by the game; keep it allocation-free.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
`ctx`	`C`	The game's context.
`entity`	`number`	The entity being checked.

Returns

boolean

Whether the guard passes.

Example

import { type BtCheck } from 'gameable';
const awake: BtCheck<{ awake: boolean }> = (ctx) => ctx.awake;

BtLeaf

type BtLeaf<C> = (ctx, entity, dt) => BtStatus;

An action supplied by the game; keep it allocation-free.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
`ctx`	`C`	The game's context.
`entity`	`number`	The entity being ticked.
`dt`	`number`	Fixed-step seconds.

Returns

BtStatus

The action's current status.

Example

import { BtStatus, type BtLeaf } from 'gameable';
const idle: BtLeaf<null> = () => BtStatus.Running;

BtStatus

type BtStatus = typeof BtStatus[keyof typeof BtStatus];

A node's result.

Example

import { BtStatus } from 'gameable';
const result: BtStatus = BtStatus.Success;

CameraMode

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

Camera rig family.

CircuitPoint

type CircuitPoint = readonly [number, number, number];

A world-space point.

Example

const p: CircuitPoint = [0, 0, 0];

CircuitStanding

type CircuitStanding = Readonly<Omit<RaceProgress, "respawnPose">>;

Public circuit row, ordered by place; no authority crossing or respawn internals.

Example

const show = (row: CircuitStanding) => console.log(row.place, row.completedLaps);

CollisionChannel

type CollisionChannel = 
  | "worldStatic"
  | "worldDynamic"
  | "pawn"
  | "visibility"
  | "camera"
  | "physicsBody"
  | "vehicle"
  | "destructible"
  | "game0"
  | "game1"
  | "game2"
  | "game3";

Object and trace channels supported by the SDK.

Example

const channel: CollisionChannel = 'pawn';

CollisionEnabled

type CollisionEnabled = "none" | "query" | "physics" | "queryAndPhysics";

Query and simulation participation, independent of body mobility.

Example

const enabled: CollisionEnabled = 'query';

CollisionResponse

type CollisionResponse = "ignore" | "overlap" | "block";

Pair response, ordered ignore < overlap < block.

Example

const response: CollisionResponse = 'block';

CollisionResponses

type CollisionResponses = Partial<Record<CollisionChannel, CollisionResponse>> & object;

Sparse channel overrides with a required fallback.

Type Declaration

default

readonly default: CollisionResponse;

Example

const responses: CollisionResponses = { default: 'block', pawn: 'overlap' };

CollisionTraceFlag

type CollisionTraceFlag = 
  | "useDefault"
  | "simpleAndComplex"
  | "simpleAsComplex"
  | "complexAsSimple";

Simple/complex collision routing modes.

Example

const flag: CollisionTraceFlag = 'simpleAsComplex';

Command

type Command = 
  | {
  tag: "add-vehicle";
  val: AddVehicleCmd;
}
  | {
  tag: "set-vehicle-input";
  val: SetVehicleInputCmd;
}
  | {
  tag: "reset-vehicle";
  val: ResetVehicleCmd;
}
  | {
  tag: "remove-vehicle";
  val: number;
}
  | {
  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: "add-joint";
  val: AddJointCmd;
}
  | {
  tag: "remove-joint";
  val: JointId;
}
  | {
  tag: "set-joint-motor";
  val: SetJointMotorCmd;
}
  | {
  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: "hit-character";
  val: HitCharacterCmd;
}
  | {
  tag: "recover-character";
  val: Entity;
}
  | {
  tag: "set-character-motion";
  val: SetCharacterMotionCmd;
}
  | {
  tag: "walk-character-to";
  val: WalkCharacterToCmd;
}
  | {
  tag: "face-character";
  val: FaceCharacterCmd;
}
  | {
  tag: "stop-character-walk";
  val: Entity;
}
  | {
  tag: "do-character-action";
  val: DoCharacterActionCmd;
}
  | {
  tag: "cancel-character-action";
  val: Entity;
}
  | {
  tag: "play-sound";
  val: PlaySoundCmd;
}
  | {
  tag: "stop-sound";
  val: StopSoundCmd;
}
  | {
  tag: "play-music";
  val: PlayMusicCmd;
}
  | {
  tag: "stop-music";
  val: number;
}
  | {
  tag: "set-music-layer";
  val: SetMusicLayerCmd;
}
  | {
  tag: "play-sound-on-beat";
  val: PlaySoundOnBeatCmd;
}
  | {
  tag: "set-bus-fx";
  val: SetBusFxCmd;
}
  | {
  tag: "set-sound-occlusion";
  val: SetSoundOcclusionCmd;
}
  | {
  tag: "set-listener";
  val: SetListenerCmd;
}
  | {
  tag: "load-asset";
  val: LoadAssetCmd;
}
  | {
  tag: "set-pointer-lock";
  val: boolean;
}
  | {
  tag: "set-time-scale";
  val: number;
}
  | {
  tag: "pause-push";
  val: string;
}
  | {
  tag: "pause-pop";
  val: string;
}
  | {
  tag: "cutscene";
  val: CutsceneCmd;
}
  | {
  tag: "thing";
  val: ThingCmd;
}
  | {
  tag: "playtest";
  val: PlaytestCmd;
}
  | {
  tag: "effect";
  val: EffectCmd;
}
  | {
  tag: "set-post";
  val: PostCmd;
}
  | {
  tag: "set-spot-light";
  val: SpotLightCmd;
}
  | {
  tag: "fight-state";
  val: FightStateCmd;
}
  | {
  tag: "fight-hit";
  val: FightHitCmd;
}
  | {
  tag: "fight-fall";
  val: FightFallCmd;
}
  | {
  tag: "fight-get-up";
  val: FightGetUpCmd;
}
  | {
  tag: "fight-camera";
  val: FightCameraCmd;
}
  | NetCommand;

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.

ConstraintKind

type ConstraintKind = "hinge" | "slider" | "point" | "fixed" | "distance";

Supported joint families.

Example

const kind: ConstraintKind = 'hinge';

ContactPhase

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

Lifecycle phase of a contact.

CrowdMove

type CrowdMove = "character" | "velocity";

How Crowd.update hands each agent's velocity to the world.

DataSchema

type DataSchema = Record<string, DataFieldSchema>;

Required fields to validate; fields absent from the schema are allowed.

Example

const schema: DataSchema = { hp: { type: 'number', description: 'Health.' } };

DriveRequest

type DriveRequest = Common & 
  | {
  kind: "target";
  target: AITarget;
}
  | {
  cornerSpeed: number;
  distance: number;
  kind: "line";
  lateralOffset: number;
  loop: boolean;
  names: number[];
  points: number[];
  segment: number;
  source: number;
}
  | {
  cooldown: number;
  kind: "chase";
  leadTime: number;
  maxLead: number;
  ram: number;
  ramCooldown: number;
  ramDistance: number;
  target: AITarget;
};

JSON-safe discriminated driving intent, including recovery and line progress.

Example

const kind: DriveRequest['kind'] = 'line';

EaseName

type EaseName = keyof typeof ease;

A built-in easing curve's name.

Example

import { ease, type EaseName } from 'gameable';
const name: EaseName = 'sineIn';
console.log(ease[name](0.5));

EffectAction

type EffectAction = "play" | "move" | "stop";

An emitter operation.

Example

import type { EffectAction } from 'gameable';
const action: EffectAction = 'play';

EffectId

type EffectId = number;

Guest-minted effect handle; 0 is a one-shot.

Example

import type { EffectId } from 'gameable';
const effect: EffectId = 1;

EndPlayReason

type EndPlayReason = "destroyed" | "lifeSpan" | "killZ" | "levelUnload";

Why an actor left play.

Example

const reason: EndPlayReason = 'destroyed';

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.

FeatureOptions

type FeatureOptions = Readonly<Record<string, Readonly<Record<string, unknown>>>>;

Declared features, normalised: every present feature has an options object.

FxPreset

type FxPreset = 
  | "dry"
  | "room"
  | "hall"
  | "cave"
  | "underwater"
  | "radio"
  | "muffled"
  | "arena";

Bus effect preset.

Example

`audio.fx('sfx', 'cave');`

GameDefinition

type GameDefinition = Readonly<GameSpec>;

A validated game declaration.

GameEvent

type GameEvent = 
  | {
  tag: "pause-reasons";
  val: string[];
}
  | {
  tag: "start";
  val: {
     reason: "player" | "capture" | "playtest";
  };
}
  | {
  tag: "conversation-event";
  val: ConversationEvent;
}
  | {
  tag: "asset-loaded";
  val: AssetLoadedEvent;
}
  | {
  tag: "character-ready";
  val: CharacterReadyEvent;
}
  | {
  tag: "sound-ended";
  val: SoundEndedEvent;
}
  | {
  tag: "beat";
  val: BeatEvent;
}
  | {
  tag: "music-track";
  val: MusicTrackEvent;
}
  | {
  tag: "anim-event";
  val: AnimEventData;
}
  | {
  tag: "resized";
  val: ResizedEvent;
}
  | {
  tag: "cutscene-event";
  val: CutsceneEvent;
}
  | {
  tag: "world-event";
  val: WorldEvent;
}
  | {
  tag: "motion-event";
  val: MotionEvent;
}
  | NetEvent
  | {
  tag: "ui";
  val: UiEvent;
}
  | {
  tag: "fight-set";
  val: FightSetEvent;
}
  | {
  tag: "fight-contact";
  val: FightContactEvent;
}
  | {
  tag: "fight-body";
  val: FightBodyEvent;
};

A host-side occurrence since the previous tick.

GridDirection

type GridDirection = 
  | "north"
  | "south"
  | "east"
  | "west"
  | "northeast"
  | "northwest"
  | "southeast"
  | "southwest";

Compass direction; north is world -Z.

Example

const dir: GridDirection = 'north';

HitStrength

type HitStrength = 
  | {
  tag: "small";
}
  | {
  tag: "big";
}
  | {
  tag: "shot";
}
  | {
  tag: "big-shot";
}
  | {
  tag: "push";
  val: number;
};

How hard a blow lands on a character's physics body: small (a flinch and a recovery over about a second), big (a fall that stays down until recover-character), shot (a sharp blow with a flinch), big-shot (a sharp blow that floors), or a push of so many newton-seconds (40 staggers, 90 and over floors).

JointAxisMode

type JointAxisMode = "free" | "locked" | "limited";

JointAxisMode in the physics boundary.

Example

import type { JointAxisMode } from 'gameable';
const value: JointAxisMode = 'limited';

JointId

type JointId = number;

JointId in the physics boundary.

Example

import type { JointId } from 'gameable';
const value: JointId = 1;

JointKind

type JointKind = "fixed" | "point" | "hinge" | "slider" | "distance" | "six-dof";

JointKind in the physics boundary.

Example

import type { JointKind } from 'gameable';
const value: JointKind = 'hinge';

KeyName

type KeyName = string;

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

LevelEdit

type LevelEdit = 
  | {
  entry?: number;
  name: string;
  op: "set";
  position?: Vec3Tuple;
  props?: Record<string, unknown>;
  rotation?: QuatTuple;
  scale?: Vec3Tuple;
  yaw?: number;
}
  | {
  class: string;
  entry?: number;
  name: string;
  op: "reclass";
  props?: Record<string, unknown>;
}
  | {
  entry?: number;
  name: string;
  op: "tags";
  tags: readonly string[];
}
  | {
  entry?: number;
  name: string;
  op: "rename";
  to: string;
}
  | {
  entry?: number;
  name: string;
  op: "remove";
}
  | {
  actor: LevelActor;
  op: "add";
}
  | {
  op: "place";
  place?: string;
};

One change to a level, keyed by the actor's name (levelActorNames). entry is the index the editor saw; it is carried for a reader, never used to look the actor up, since the file may have changed under the editor.

Union Members

Type Literal

{
  entry?: number;
  name: string;
  op: "set";
  position?: Vec3Tuple;
  props?: Record<string, unknown>;
  rotation?: QuatTuple;
  scale?: Vec3Tuple;
  yaw?: number;
}

entry?

optional entry?: number;

name

name: string;

op

op: "set";

position?

optional position?: Vec3Tuple;

props?

optional props?: Record<string, unknown>;

Merged over the entry's props.

rotation?

optional rotation?: QuatTuple;

Writing it drops yaw.

scale?

optional scale?: Vec3Tuple;

yaw?

optional yaw?: number;

Degrees about +Y; writing it drops rotation.

Type Literal

{
  class: string;
  entry?: number;
  name: string;
  op: "reclass";
  props?: Record<string, unknown>;
}

class

class: string;

entry?

optional entry?: number;

name

name: string;

op

op: "reclass";

props?

optional props?: Record<string, unknown>;

Merged over the props the new class keeps.

Type Literal

{
  entry?: number;
  name: string;
  op: "tags";
  tags: readonly string[];
}

Type Literal

{
  entry?: number;
  name: string;
  op: "rename";
  to: string;
}

Type Literal

{
  entry?: number;
  name: string;
  op: "remove";
}

Type Literal

{
  actor: LevelActor;
  op: "add";
}

Type Literal

{
  op: "place";
  place?: string;
}

Example

const edit: LevelEdit = { op: 'set', name: 'exit', position: [3, 1.2, -10.5] };

LogLevel

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

Log severity accepted by env.log.

MatchState

type MatchState = "waitingToStart" | "inProgress" | "waitingPostMatch";

Match lifecycle.

Example

const state: MatchState = 'waitingToStart';

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.

MessageCheck

type MessageCheck<T> = (payload) => payload is T;

The game's own type guard for a payload, already parsed from JSON. It must be pure: no wall time, no Math.random, no state, so the authority and every replay agree on what it drops.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`payload`	`unknown`

Returns

payload is T

MotorMode

type MotorMode = "off" | "velocity" | "position";

MotorMode in the physics boundary.

Example

import type { MotorMode } from 'gameable';
const value: MotorMode = 'position';

NetCommand

type NetCommand = 
  | {
  tag: "send";
  val: SendCmd;
}
  | {
  tag: "set-player-camera";
  val: SetPlayerCameraCmd;
}
  | {
  tag: "set-player-hud";
  val: SetPlayerHudCmd;
}
  | {
  tag: "save-player-data";
  val: SavePlayerDataCmd;
}
  | {
  tag: "save-game-data";
  val: SaveGameDataCmd;
}
  | {
  tag: "set-player-entity";
  val: SetPlayerEntityCmd;
}
  | {
  tag: "exchange";
  val: ExchangeCmd;
};

The net and data members of the command variant.

NetEvent

type NetEvent = 
  | {
  tag: "player-joined";
  val: PlayerJoinedEvent;
}
  | {
  tag: "player-left";
  val: PlayerLeftEvent;
}
  | {
  tag: "message";
  val: NetMessageEvent;
}
  | {
  tag: "exchange-result";
  val: ExchangeResultEvent;
}
  | {
  tag: "game-data";
  val: GameDataEvent;
};

The net and data members of the event variant.

NetRole

type NetRole = "solo" | "authority" | "client";

Where a guest runs: alone (solo), as the room's authority, or as one player's client.

Example

const role: NetRole = ctx.net.role;
if (role === 'client') showLatency();

ParticleEffectOptions

type ParticleEffectOptions = Omit<ComponentOptions, "scale"> & object;

Emitter overrides; scale controls particles rather than the component transform.

Type Declaration

autoActivate?

optional autoActivate?: boolean;

intensity?

optional intensity?: number;

scale?

optional scale?: number;

tint?

optional tint?: readonly [number, number, number];

Example

const options: ParticleEffectOptions = { autoActivate: false };

PawnInput

type PawnInput = GameContext["input"];

A player's input, read like ctx.input.

PickupGive

type PickupGive = 
  | {
  heal: number;
}
  | {
  count: number;
  item: string;
}
  | {
  score: number;
}
  | "custom";

JSON pickup reward; inventory owners are player seats, with seat 0 in solo.

Example

const reward: PickupGive = { item: 'key', count: 1 };

PlayerSpawn

type PlayerSpawn = 
  | readonly number[]
  | readonly readonly number[][]
  | ((seat, ctx) => Vec3);

Where definition.player spawns each seat: one point [x, y, z] for everyone, a list of points (seat i takes list[i % list.length]), or a function of the seat. A single-player game spawns seat 0.

The function runs on the authority at the seat's join, inside the step, so it must be deterministic: read only the seat, ctx.rules, ctx.rng and the world, never the clock or Math.random. It runs before ctx.players is updated for the step, so read the seat: the map still holds the previous step's players.

Example

const corners: PlayerSpawn = [[-8, 0, -8], [8, 0, -8], [8, 0, 8], [-8, 0, 8]];
export default defineGame({ player: { prefab: Hero, spawn: corners } });

ProfileName

type ProfileName = keyof typeof profiles;

Built-in collision profile names (deprecated redirects excluded).

Example

const name: ProfileName = 'Pawn';

ProjectileSpec

type ProjectileSpec<P> = Omit<ActorSpec<ProjectileProps & P>, "components" | "props"> & object;

Projectile defaults and definition-only impact callback. Hit coordinates are borrowed.

Type Declaration

components?

optional components?: ActorSpec<ProjectileProps & P>["components"];

props?

optional props?: Partial<ProjectileProps> & P;

onProjectileHit()?

optional onProjectileHit(
   self, 
   hit, 
   ctx, 
   stopped
): void;

Runs once per accepted sweep hit, after damage and before terminal destruction.

Parameters

Parameter	Type
`self`	`ActorHandle`<`ProjectileProps` & `P`>
`hit`	`RayHit`
`ctx`	`GameContext`
`stopped`	`boolean`

Returns

void

Type Parameters

Type Parameter	Default type
`P` extends `object`	`object`

Example

const spec: ProjectileSpec = { props: { hitResponse: 'effect' }, onProjectileHit(self, hit, ctx, stopped) {} };

ProjectionKind

type ProjectionKind = "perspective" | "orthographic";

Camera projection family.

QuatTuple

type QuatTuple = readonly [number, number, number, number];

A quaternion, xyzw.

ShapeKind

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

Collision shape family.

SoundId

type SoundId = number;

Playing-sound handle.

StopStyle

type StopStyle = "gradual" | "hard";

Which kind of stop a running character asked to stand makes: 'gradual', it slows and stands upright; 'hard', it brakes. It says WHICH KIND of stop; arrive (see character.walkTo) says how soon it must be there. Read where the character's motion set has stops that state a kind (a run's, on the engine's shared set); a walk's stop and a sprint's stop are the same under both there.

System

type System = (ctx) => void;

A system: one plain function, run once per fixed step. In systems it may also be a SidedSystem, { run, on }, that says where it runs.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

ToneMapping

type ToneMapping = "none" | "aces" | "agx" | "neutral";

Supported post tone mapping operators.

Example

import type { ToneMapping } from 'gameable';
const toneMapping: ToneMapping = 'aces';

TransferDoc

type TransferDoc = Record<string, unknown>;

A player document as a transfer reads it: a plain object.

UiEventKind

type UiEventKind = 
  | "click"
  | "drag-start"
  | "drop"
  | "drag-cancel"
  | "focus"
  | "blur"
  | "change"
  | "submit";

What the player did. Mirrors WIT ui-event-kind.

Example

import type { UiEventKind } from 'gameable';
const example: UiEventKind = 'click';
console.log(example);

UiNode

type UiNode = 
  | UiStack
  | UiGrid
  | UiPanel
  | UiText
  | UiButton
  | UiCard
  | UiList
  | UiBar
  | UiInput;

Any node.

Example

import type { UiNode } from 'gameable';
const example: UiNode = { type: 'text', text: 'Ready' };
console.log(example);

UiScreenAnchor

type UiScreenAnchor = 
  | "center"
  | "top"
  | "bottom"
  | "left"
  | "right"
  | "top-left"
  | "top-right"
  | "bottom-left"
  | "bottom-right"
  | "fill";

Where a top-level node sits on the screen. fill covers the whole viewport.

Example

import type { UiScreenAnchor } from 'gameable';
const example: UiScreenAnchor = 'top-right';
console.log(example);

Vec3Tuple

type Vec3Tuple = readonly [number, number, number];

A position or a scale.

VehicleCurve

type VehicleCurve = readonly readonly [number, number][];

Piecewise linear [input, multiplier] points; x must strictly increase.

Example

const curve: VehicleCurve = [[0, 1], [30, 0.5]];

VehicleOptions

type VehicleOptions = { [K in keyof VehicleSettings]?: VehicleSettings[K] | null } & object;

Vehicle tuning with preset defaults.

Type Declaration

collision?

optional collision?: "Vehicle" | null;

handling?

optional handling?: "arcade" | "grippy" | "drift";

Example

const options: VehicleOptions = { handling: 'drift', maxSpeed: 30 };

VfxPreset

type VfxPreset = "hit-sparks" | "explosion" | "smoke" | "fire" | "magic" | "dust" | "trail";

Built-in particle presets.

Example

import type { VfxPreset } from 'gameable';
const preset: VfxPreset = 'hit-sparks';

WalkStart

type WalkStart = "moving";

How a walk to a spot is begun when the game knows more than the character's takes show: 'moving', the body is under way already (it comes out of a get-up, it was carried or thrown), so the walk is planned as of a body under way: no turn on the spot first, no one take from stand to stand, and a pace above the walk's needs room for its stop only, not for a start from standing. See character.walkTo.

Variables

Actor

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

Tag identifying actor roots.

Example

addComponent(ctx.world, entity, Actor);

actors

const actors: object;

Actor queries in spawn order. Returned arrays are borrowed runtime views.

Type Declaration

all()

all(): readonly ActorHandle<object>[];

All living actors, including pending beginPlay.

Returns

readonly ActorHandle<object>[]

A borrowed array in spawn order.

named()

named(name): ActorHandle<object> | null;

First living actor with this instance name, or null.

Parameters

Parameter	Type	Description
`name`	`string`	Instance name to match.

Returns

ActorHandle<object> | null

The first matching actor, or null.

of()

of(entity): ActorHandle<object> | null;

Owning actor for a root or component entity, or null.

Parameters

Parameter	Type	Description
`entity`	`number`	Root or component entity id.

Returns

ActorHandle<object> | null

The owning actor, or null.

ofClass()

ofClass<P>(cls): readonly ActorHandle<P>[];

Actors whose class is exactly cls.

Type Parameters

Type Parameter
`P` extends `object`

Parameters

Parameter	Type	Description
`cls`	`ActorClass`<`P`>	Registered actor class.

Returns

readonly ActorHandle<P>[]

A borrowed array of matching actors.

withTag()

withTag(tag): readonly ActorHandle<object>[];

Actors carrying a tag, with no duplicates.

Parameters

Parameter	Type	Description
`tag`	`string`	Instance tag to match.

Returns

readonly ActorHandle<object>[]

A borrowed array of matching actors.

Example

const crates = actors.withTag('breakable');

AgentState

const AgentState: object;

Where an agent is in its errand.

Type Declaration

Arrived

readonly Arrived: 2 = 2;

Idle

readonly Idle: 0 = 0;

Moving

readonly Moving: 1 = 1;

NoPath

readonly NoPath: 3 = 3;

AIController

const AIController: ActorClass<AIControllerProps & object>;

A controller with no player seat and a replaceable move-completion hook.

Example

const ai = spawnActor(ctx, AIController, { position: { x: 0, y: 0, z: 0 } });

AmbientSound

const AmbientSound: ActorClass<AmbientProps>;

A looping positional sound built on an audio component.

Example

spawnActor(ctx, AmbientSound, { position: { x: 0, y: 0, z: 0 }, props: { sound: 'wind' } });

audio

const audio: object;

The audio facade.

Type Declaration

fx()

fx(
   bus, 
   preset, 
   options?
): void;

Set bus effects.

Parameters

Parameter	Type	Description
`bus`	`AudioBus`	Mixer bus.
`preset`	`FxPreset`	Base preset.
`options?`	`FxOptions`	Overrides and fade.

Returns

void

Example

`audio.fx('sfx', 'cave');`

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.

occlude()

occlude(
   sound, 
   amount, 
   fadeMs?
): void;

Muffle a sound.

Parameters

Parameter	Type	Default value	Description
`sound`	`number`	`undefined`	Sound handle.
`amount`	`number`	`undefined`	Occlusion from zero to one.
`fadeMs`	`number`	`0`	Ramp duration.

Returns

void

Example

`audio.occlude(1, 0.8, 120);`

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.

playOnBeat()

playOnBeat(asset, options?): number;

Schedule a sound on the music grid.

Parameters

Parameter	Type	Description
`asset`	`string` \| `number`	Manifest id or handle.
`options?`	`PlayOnBeatOptions`	Grid and mixer options.

Returns

number

Sound handle or zero for an unknown asset.

Example

`audio.playOnBeat('kick', { subdivision: 2 });`

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 'gameable';

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

AudioVolume

const AudioVolume: ActorClass<AudioVolumeProps>;

A solo pawn's box reverb region; rooms skip it because authority has no single listener. This module exclusively owns audio.fx for every bus named by an AudioVolume: game code must leave those buses' effects to volumes. Priority wins; equal priority uses spawn order.

Example

spawnActor(ctx, AudioVolume, { position: { x: 0, y: 0, z: 0 }, props: { reverb: 'hall' } });

AUTHORITY_SENDER

const AUTHORITY_SENDER: 4294967295 = 0xffffffff;

The sender id of a message from the authority itself. Room seats start at 0, so the authority is not 0: this is past every player id and still a u32 (the WIT's message-event.player). Keep ids unsigned: in an Int32Array this reads back as -1.

Example

import { AUTHORITY_SENDER } from 'gameable';

const fromServer = (from: number): boolean => from === AUTHORITY_SENDER;

AutomaticDoor

const AutomaticDoor: ActorClass<AutomaticDoorProps>;

Two metal panels that split for nearby players and wait after they leave. Locked arrivals receive one notice and onLocked per entry, without an E prompt.

Example

spawnActor(ctx, AutomaticDoor, { position: { x: 0, y: 1.05, z: 0 } });

BlockingVolume

const BlockingVolume: ActorClass<{
  halfExtents: number[];
}>;

Invisible fixed box; dimensions are half extents in metres, read at spawn.

Example

spawnActor(ctx, BlockingVolume, { position: { x: 0, y: 1, z: 4 }, props: { halfExtents: [4, 1, 0.2] } });

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.

bt

const bt: object;

Pure builders: only descriptions are allocated; no runtime state or randomness.

Type Declaration

action()

action<C>(run): BtNode<C>;

Run a game action.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
`run`	`BtLeaf`<`C`>	The game's action.

Returns

BtNode<C>

An action description.

condition()

condition<C>(check): BtNode<C>;

Turn a boolean guard into success or failure.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
`check`	`BtCheck`<`C`>	The game's guard.

Returns

BtNode<C>

A condition description.

not()

not<C>(child): BtNode<C>;

Swap success and failure, leaving running unchanged.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
`child`	`BtNode`<`C`>	The node to invert.

Returns

BtNode<C>

An inversion description.

selector()

selector<C>(...children): BtNode<C>;

Recheck children from the start; the first non-failure wins.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
...`children`	`BtNode`<`C`>[]	Children in priority order.

Returns

BtNode<C>

A selector description.

sequence()

sequence<C>(...children): BtNode<C>;

Recheck children from the start; stop at the first non-success.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
...`children`	`BtNode`<`C`>[]	Children in execution order.

Returns

BtNode<C>

A sequence description.

sequenceWithMemory()

sequenceWithMemory<C>(...children): BtNode<C>;

Resume at the running child, skipping previously successful children.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
...`children`	`BtNode`<`C`>[]	Children in execution order.

Returns

BtNode<C>

A sequence with memory description.

wait()

wait<C>(seconds): BtNode<C>;

Accumulate this entity's dt until the duration is reached.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
`seconds`	`number`	The duration, in seconds.

Returns

BtNode<C>

A wait description, restarting after completion or interruption.

Returns

Stateless nodes for compiling with createBehaviorTree.

Example

import { bt, BtStatus, createBehaviorTree } from 'gameable';
const root = bt.sequence(bt.wait<null>(1), bt.action<null>(() => BtStatus.Success));
const tree = createBehaviorTree(root);
tree.tick(null, 0, 1 / 60);

BtStatus

const BtStatus: object;

Results returned by a behaviour tree node.

Type Declaration

Failure

readonly Failure: 2 = 2;

Running

readonly Running: 3 = 3;

Success

readonly Success: 1 = 1;

Returns

The success, failure and running status constants.

Example

import { BtStatus } from 'gameable';
const chase = () => BtStatus.Running;
chase();

BUILTIN_COMPONENT_NAMES

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

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>, Record<string, never>];

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

camera

const camera: object;

The camera facade: writes the frame's camera.

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;

Returns

CameraState

fight()

fight(shot): void;

Parameters

Parameter	Type	Description
`shot`	`FightShotOptions`	The two fighters and the moment.

Returns

void

Nothing.

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.

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(point): void;

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

Parameters

Parameter	Type	Description
`point`	`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 'gameable';

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

CameraActor

const CameraActor: ActorClass<{
  activateOnStart: boolean;
  fov: number;
}>;

A placeable camera. The active actor writes its transform every actor step, suppressing the built-in player camera through camera.set's cameraWritten flag. Later game systems can override that frame's view. Activation survives snapshots.

Example

const view = spawnActor(ctx, CameraActor, { position: { x: 0, y: 2, z: 5 },
  props: { fov: 55, activateOnStart: true } });
activateCamera(ctx, view);

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.

cancelAction()

cancelAction(entity): void;

Take an action's request back (it cannot be taken back between its gathering and its landing).

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.

Returns

void

Nothing.

do()

do(
   entity, 
   action, 
   object?, 
   plain?
): void;

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Entity with a `Character` component.
`action`	`string`	`undefined`	The action's name in the set.
`object?`	`Readonly`<`ActionObject`>	`undefined`	The thing it is done at, as the game has it; left out for an action without one.
`plain?`	`boolean`	`false`	The plain way, for a comparison: the take simply started, nothing fitted.

Returns

void

Nothing.

Example

character.do(hero, 'hurdle', { id: bar, position: barAt, yaw: 0, height: 0.6, width: 1.2, depth: 0.05 });

face()

face(
   entity, 
   facing, 
   arrive?
): void;

Turn a character on the spot to face a way, by its set's own turns. The motion-event arrived named 'face' says when it faces there.

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Entity with a `Character` component.
`facing`	`number`	`undefined`	Radians about +Y (0 faces +Z).
`arrive`	`"easy"` \| `"quick"`	`'easy'`	`'easy'` (the default: an unhurried turn) or `'quick'` (the quickest the set has).

Returns

void

Nothing.

Example

character.face(guide, Math.PI / 2);

fight()

fight(entity, state?): void;

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`state`	`FightStateOptions` \| `null`	What the body is doing; every field optional. `null` ends the fight on this body (a round's reset): the clips have it again, and the next call starts afresh, standing.

Returns

void

Nothing.

Example

character.fight(me, { base: { name: 'fight_idle_bounce', loop: true, fade: 10 }, facing: 1, bounce: 0.7 });
character.fight(me, { base: null, strike: { id: 'jab', frame, aim: theirHead } });

fightFall()

fightFall(
   entity, 
   velocity, 
   spin?, 
   turn?, 
   kick?
): void;

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Entity with a `Character` component.
`velocity`	`Vec3`	`undefined`	Metres a second, world.
`spin`	`number`	`2`	Radians a second about the axis across the blow's line (0.4 to 3 reads as a knockdown).
`turn`	`number`	`0`	The blow's line's angle on the floor (0 along x).
`kick`	`boolean`	`false`	The body is thrown already (a hit in the air): the blow is blended into its flight.

Returns

void

Nothing.

fightGetUp()

fightGetUp(entity, quick?): void;

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Entity with a `Character` component.
`quick`	`boolean`	`false`	The kip-up.

Returns

void

Nothing.

fightHit()

fightHit(entity, hit): void;

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`hit`	`FightHitOptions`	The blow.

Returns

void

Nothing.

hit()

hit(entity, blow): void;

What happened comes back as anim-events on the clip ragdoll: hit, fell (the body came to rest on the floor), recovered.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`blow`	{ `at`: `Vec3`; `direction?`: `Vec3`; `strength`: `number` \| `"small"` \| `"big"` \| `"shot"` \| `"big-shot"`; }	Where it lands (`at`, world), which way it travels (`direction`, world; omitted: from the character's front) and how hard (`strength`: `'small'`, `'big'`, `'shot'`, `'big-shot'`, or a push's newton-seconds: 40 staggers, 90 and over floors).
`blow.at`	`Vec3`	-
`blow.direction?`	`Vec3`	-
`blow.strength`	`number` \| `"small"` \| `"big"` \| `"shot"` \| `"big-shot"`	-

Returns

void

Nothing.

Example

character.hit(enemy, { at: swordTip, direction: swing, strength: 'small' });
character.hit(enemy, { at: swordTip, direction: swing, strength: 'big' }); // down

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.

motion()

motion(entity, options?): void;

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`options`	`CharacterMotionOptions`	What to change.

Returns

void

Nothing.

Example

character.motion(hero, { responsiveness: 0.9 }); // a snappier hero
character.motion(guard, { on: false }); // this one by the clips' blend, as before
character.motion(hero, { stop: 'hard' }); // from a run it brakes, instead of slowing to a stand

recover()

recover(entity): void;

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.

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?, 
   facing?
): 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.
`facing?`	`number`	`undefined`	Optional held world yaw in radians; permits backpedalling without turning.

Returns

void

Nothing.

stopWalk()

stopWalk(entity): void;

Give up a walk to a spot: the character stops where it is, as its takes stop.

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.

Returns

void

Nothing.

walkTo()

walkTo(
   entity, 
   target, 
   how?
): void;

Parameters

Parameter	Type	Description
`entity`	`number`	Entity with a `Character` component.
`target`	`Vec3`	The spot, world space, on the floor.
`how`	{ `arrive?`: `"easy"` \| `"quick"`; `facing?`: `number`; `pace?`: `number`; `start?`: `"moving"`; `stop?`: `StopStyle`; }	The facing to arrive with (`facing`, radians about +Y, 0 faces +Z; left out: as it arrives), the pace (`pace`, metres a second; left out: the set's own walk; above the speeds its walk covers it runs, when its set has a run and the spot is far enough to run to), how it stops (`arrive`: `'easy'`, the default, the takes' unhurried stops; `'quick'`, the shortest stops and turns the set has) and which kind of stop this one walk ends with (`stop`: `'gradual'`, it slows and stands upright; `'hard'`, it brakes; left out: the character's own, see `character.motion`). `arrive` says how soon it must be there, `stop` says which kind of stop; a `'quick'` walk that states no `stop` stops as a quick walk always did. A kind is read on a run's stops: a walk's stop and a sprint's stop are the same under both on the engine's shared set. And how it is begun (`start`: `'moving'`, the game says the body is under way already: it comes out of a get-up, it was carried or thrown; the walk is then planned as of a body under way: no turn on the spot first, no start from standing; left out: as its takes have the body).
`how.arrive?`	`"easy"` \| `"quick"`	-
`how.facing?`	`number`	-
`how.pace?`	`number`	-
`how.start?`	`"moving"`	-
`how.stop?`	`StopStyle`	-

Returns

void

Nothing.

Example

character.walkTo(guide, { x: 2, y: 0, z: -3 }, { facing: Math.PI });
character.walkTo(rider, bikeSide, { pace: 3.4 }); // a run's pace: it runs there
character.walkTo(rider, bikeSide, { pace: 3.4, stop: 'hard' }); // and brakes at the spot
character.walkTo(rider, bikeSide, { pace: 3.4, start: 'moving' }); // out of a get-up: no turn on the spot first

Example

import { character } from 'gameable';

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.

CharacterActor

const CharacterActor: ActorClass<{
  animation: string;
  character: string;
}>;

An NPC character controller and splat bundle that stands and animates. An empty animation keeps the bundle's idle; a named clip uses the body layer. Initial props select the bundle and clip. No movement is requested.

Example

spawnActor(ctx, CharacterActor, { position: { x: 0, y: 0, z: 0 },
  props: { character: 'guide', animation: 'idle' } });

CharacterPawn

const CharacterPawn: ActorClass<{
  character: string;
  jumpZVelocity: number;
  maxWalkSpeed: number;
  orientRotationToMovement: boolean;
  rotationRate: number;
}>;

A possessable character bundle rooted in the guest movement capsule. Controllers supply addMovementInput and jump; setDesiredRotation holds a facing.

Example

const fighter = spawnActor(ctx, CharacterPawn, {
  position: { x: 0, y: 1, z: 0 },
  props: { character: 'fighter', orientRotationToMovement: false },
});
setDesiredRotation(fighter.entity, Math.PI / 2);

CheckpointVolume

const CheckpointVolume: ActorClass<CheckpointProps>;

Player checkpoint box. The point goes to the world group's respawn store, which respawnPlayer and KillHeight read.

Example

spawnActor(ctx, CheckpointVolume, {position: {x: 3,y: 1,z: 0}, props: {order: 2}});

conversation

const conversation: object;

Guest interview controls.

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`	\| `"start"` \| `"end"` \| `"ask"` \| `"interrupt"` \| `"microphone-on"` \| `"microphone-off"`	`undefined`	Lifecycle or question action.
`character`	`string`	`''`	Host-configured id.
`text`	`string`	`''`	Question, if any.

Returns

void

story()

story(text): ConversationStory | null;

Read a story event's text (the snapshot JSON). Null for anything that is not a version-1 snapshot.

Parameters

Parameter	Type	Description
`text`	`string`	The event's text.

Returns

ConversationStory | null

The story, or null.

Example

import { conversation } from 'gameable';
const story = conversation.story('{"schemaVersion":1,"revision":2,"currentPhase":"gate","completedObjectives":["told-truth"],"playerState":{},"transitionCause":""}');
const believed = story?.completedObjectives.includes('told-truth') ?? false;

Example

import { conversation } from "gameable";
conversation.command(npc, "start", "steward");

cutscene

const cutscene: object;

The cutscene facade.

Type Declaration

play()

play(asset, options?): number;

Play a clip over the stage.

Parameters

Parameter	Type	Description
`asset`	`string` \| `number`	Manifest id of a `video` entry, or its handle.
`options?`	`CutscenePlayOptions`	Fades, skip, pause.

Returns

number

The asset handle (the one a cutscene-event will name), or 0 when the id is unknown.

preload()

preload(asset): number;

Fetch a clip ahead of time so play starts the moment it is called.

Parameters

Parameter	Type	Description
`asset`	`string` \| `number`	Manifest id of a `video` entry, or its handle.

Returns

number

The asset handle, or 0 when the id is unknown.

skip()

skip(): void;

End the clip playing now (it comes back as skipped).

Returns

void

Nothing.

Example

import { cutscene } from 'gameable';

cutscene.preload('kael-falls'); // when the fight starts
cutscene.play('kael-falls', { fadeIn: 300, skippable: true }); // when the boss falls
// later, in the events: { tag: 'cutscene-event', val: { asset, kind: 'ended' | 'skipped' | 'failed', seconds } }

DamageVolume

const DamageVolume: ActorClass<{
  damagePerSecond: number;
  enabled: boolean;
  halfExtents: number[];
  interval: number;
  type: string;
}>;

Interval damage: one interval's damage on entry, then every interval seconds. Disabled volumes pause damage; enabling starts a fresh interval with an immediate hit.

Example

spawnActor(ctx, DamageVolume, { position: { x: 0, y: 0, z: 0 }, props: { damagePerSecond: 10, type: 'fire' } });

DEFAULT_CHARACTER_MOVEMENT

const DEFAULT_CHARACTER_MOVEMENT: Readonly<CharacterMovementSettings>;

Movement defaults in metres; gravity=-9.81 and terminal=55 set acceleration and fall-speed limits. Capsule halfHeight measures half the cylinder, excluding its hemispherical caps (total half-height is 0.88).

Example

const speed = DEFAULT_CHARACTER_MOVEMENT.maxWalkSpeed; // 6 m/s

DEFAULT_MAX_ENTITIES

const DEFAULT_MAX_ENTITIES: 4096 = 4096;

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

DEFAULT_MAX_PLAYERS

const DEFAULT_MAX_PLAYERS: 16 = 16;

The highest player id a guest makes a slot for when net.maxPlayers is not in game-config.options.

Example

import { DEFAULT_MAX_PLAYERS } from 'gameable';

const options = JSON.stringify({ net: { maxPlayers: DEFAULT_MAX_PLAYERS * 2 } });

DEFAULT_ROOM_SEATS

const DEFAULT_ROOM_SEATS: 8 = 8;

Seats in a room when the game declares features.multiplayer without a maxPlayers.

Example

import { DEFAULT_ROOM_SEATS, defineGame, roomSeats } from 'gameable';

const game = defineGame({ features: { multiplayer: true } });
roomSeats(game) === DEFAULT_ROOM_SEATS; // true

defaultDriveTuning

const defaultDriveTuning: Readonly<DriveTuning>;

Default arcade pursuit tuning. Recovery stops after three reverse attempts.

Example

const tuning = { ...defaultDriveTuning, stuckSeconds: 4 };

DirectionalLight

const DirectionalLight: ActorClass<{
  color: number[];
  intensity: number;
}>;

Placeable light placeholder until the host accepts guest light commands. Emits one warning per instance at beginPlay and preserves authored props.

Example

spawnActor(ctx, DirectionalLight, { position: { x: 0, y: 2, z: 0 } });

Door

const Door: ActorClass<DoorProps>;

Interactable kinematic door. A successful unlock remains unlocked, including after auto-close.

Example

spawnActor(ctx, Door, {position: {x: 0,y: 1,z: 4}, props: {openYaw: 90, seconds: 1}});

DoubleDoor

const DoubleDoor: ActorClass<DoubleDoorProps>;

Two half-width wood leaves hinged on their outer edges, swinging away together.

Example

spawnActor(ctx, DoubleDoor, { position: { x: 0, y: 1.05, z: 0 } });

ease

const ease: object;

Standard easings.net curves. Inputs are clamped; back and elastic may overshoot. Every curve returns exactly zero and one at its endpoints.

Type Declaration

backOut()

readonly backOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

bounceOut()

readonly bounceOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

cubicIn()

readonly cubicIn(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

cubicInOut()

readonly cubicInOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

cubicOut()

readonly cubicOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

elasticOut()

readonly elasticOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

linear()

readonly linear(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

quadIn()

readonly quadIn(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

quadInOut()

readonly quadInOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

quadOut()

readonly quadOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

sineIn()

readonly sineIn(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

sineInOut()

readonly sineInOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

sineOut()

readonly sineOut(t): number;

Parameters

Parameter	Type
`t`	`number`

Returns

number

Example

import { ease } from 'gameable';
console.log(ease.quadIn(0.5)); // 0.25

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.

FlyingPawn

const FlyingPawn: ActorClass<{
  collision: boolean;
  maxSpeed: number;
}>;

A flying pawn with an optional blocking kinematic sphere.

Example

const pawn = spawnActor(ctx, FlyingPawn, { position: { x: 0, y: 1, z: 0 } });

ForceField

const ForceField: ActorClass<ForceFieldProps>;

World actor applying radial force, with an optional first-step impulse.

Example

spawnActor(ctx, ForceField, { position: { x: 0, y: 0, z: 0 }, props: { fireOnBeginPlay: true } });

GameMode

const GameMode: ActorClass<GameModeProps>;

Authority match rules, login, scoring and respawning for existing player bodies.

Example

spawnActor(ctx, GameMode, { position, props: { matchTime: 120 } });

GameState

const GameState: ActorClass<GameStateProps>;

Public match state maintained by GameMode.

Example

const remaining = gameState()?.props.remaining;

Gate

const Gate: ActorClass<GateProps>;

A barred portcullis on one kinematic body, rising into the ceiling on signals.

Example

spawnActor(ctx, Gate, { position: { x: 0, y: 1.5, z: 0 }, props: { opensWhen: ['switch'] } });

Health

const Health: HealthStore;

Hit points.

HeightFog

const HeightFog: ActorClass<{
  fogColor: readonly [number, number, number];
  fogDensity: number;
}>;

Exponential fog through the shared post composer; the host has no height falloff. Declare features: { vfx: true }. Do not also call ctx.vfx.post when using fog or volumes. Room authorities skip it.

Example

spawnActor(ctx, HeightFog, { position: { x: 0, y: 0, z: 0 } });

HingedDoor

const HingedDoor: ActorClass<HingedDoorProps>;

A painted kinematic leaf swinging around its edge.

Example

spawnActor(ctx, HingedDoor, { position: { x: 0, y: 1.05, z: 0 } });

hud

const hud: object;

The HUD facade: writes the frame's HUD.

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.

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 'gameable';

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: the local player's input. That is frame-input.input in a single-player game and on the authority, and the local player's slot of frame-input.players on a client.

Type Declaration

touch

touch: object;

Fingers on a touch screen, as the host's touch layer packs them: the first finger is the pointer (mouse), a tap is pressed('Tap'), and the thumb sticks, the pinch and the turn are here.

touch.active

Get Signature

get active(): boolean;

Is a finger on the screen? (The touch pad is connected.)

Returns

boolean

True while any finger is down.

touch.pinch

Get Signature

get pinch(): number;

Two fingers' pinch this step, as a scale factor: over 1 the fingers moved apart (zoom in), under 1 together, exactly 1 with no pinch.

Returns

number

The scale factor.

touch.turn

Get Signature

get turn(): number;

Two fingers' turn this step, in radians, counter-clockwise on the screen positive.

Returns

number

The turn.

touch.stick()

stick(side): Axis2;

A thumb stick's push.

Parameters

Parameter	Type	Description
`side`	`"left"` \| `"right"`	The left stick (movement) or the right one (the camera).

Returns

A pooled { x, y }, -1..1, y up the screen positive. Never retain it.

control

Get Signature

get control(): Readonly<NonNullable<InputState["control"]>>;

Received page control for this frame. Owned by the SDK; read during the tick.

Returns

Readonly<NonNullable<InputState["control"]>>

The control state received with this input sequence.

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

The modifiers for this frame.

mouse

Get Signature

get mouse(): MouseState;

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

Returns

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

action()

action(name): ActionState;

Read a declared button into pooled storage. Unknown names throw.

Parameters

Parameter	Type	Description
`name`	`string`	Declared button action name.

Returns

Pooled button state; read immediately.

axis2()

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

Parameters

Parameter	Type	Default value	Description
`negX`	`string`	`undefined`	Declared axis name, or key driving x negative, e.g. `'A'`.
`posX?`	`string`	`undefined`	Key that drives x positive, for example `'D'`.
`negY?`	`string`	`undefined`	Key that drives y negative, for example `'S'`.
`posY?`	`string`	`undefined`	Key that drives y positive, for example `'W'`.
`stick?`	`StickSide`	`'left'`	Which thumb stick to add, `'left'` by default.

Returns

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 'gameable';

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

Interactable

const Interactable: ActorClass<InteractableProps>;

Ready interaction point; derive a class with onInteract for game-specific behavior.

Example

const Switch = defineActor('Switch', {...Interactable.spec, onInteract(self, who, ctx) { self.props.enabled = false; }});

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.

JumpPad

const JumpPad: ActorClass<JumpPadProps>;

Launch an entering character body or entity carrying Velocity. Player movement systems must preserve external launches.

Example

spawnActor(ctx, JumpPad, {position: {x: 0,y: 0,z: 0}, props: {launch: [0,15,0]}});

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.

KillVolume

const KillVolume: ActorClass<{
  halfExtents: number[];
}>;

Recover vehicles through their circuit or spawn policy, respawn players, destroy other actors.

Example

spawnActor(ctx, KillVolume, { position: { x: 0, y: -10, z: 0 }, props: { halfExtents: [100, 1, 100] } });

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 'gameable';

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

LevelDoor

const LevelDoor: ActorClass<LevelDoorProps>;

A kit door that loads a level and places the party at its arrival marker. Travel runs after actor steps; onTravel can clear or redirect toLevel first.

Example

spawnActor(ctx, LevelDoor, { position: { x: 0, y: 1.05, z: 0 }, props: { toLevel: 'cave' } });

levels

const levels: LevelsFacade;

The levels facade, ctx.levels.

Example

import { defineGame, levels } from 'gameable';

export default defineGame({
  levels: { start: startLevel, cave: caveLevel },
  systems: [(ctx) => { if (ctx.input.pressed('KeyN')) levels.load(ctx, 'cave'); }],
});

LevelSettings

const LevelSettings: ActorClass<{
  killHeight: number | false | null;
}>;

Level-wide settings. Place at most one LevelSettings actor per level.

Example

spawnActor(ctx, LevelSettings, { position: { x: 0, y: 0, z: 0 }, props: { killHeight: -100 } });

Lever

const Lever: ActorClass<LeverProps>;

An interactable signal source with a moving, draw-only handle.

Example

spawnActor(ctx, Lever, { position: { x: 0, y: 1, z: 0 }, name: 'lever1' });

MAIN_LEVEL

const MAIN_LEVEL: "main" = 'main';

The name a bare defineGame({ level }) is declared under.

MeshActor

const MeshActor: ActorClass<{
  asset: string;
  collision: "none" | "block";
  halfExtents: [number, number, number];
  scale: [number, number, number];
  tint: [number, number, number];
}>;

A prop mesh with optional fixed box collision. Collider dimensions are authored half extents in world metres; the guest manifest exposes no collider geometry. Scale affects the mesh only. Props configure the initial components at spawn.

Example

spawnActor(ctx, MeshActor, { position: { x: 0, y: 0, z: 0 },
  props: { asset: 'crate', collision: 'block', halfExtents: [1, 1, 1] } });

MOUSE_BUTTONS

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

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

MovingPlatform

const MovingPlatform: ActorClass<MovingPlatformProps>;

Kinematic box moved by the reusable path component. Teleports supply no ground velocity; translation carries supported player feet explicitly, like race movers.

Example

spawnActor(ctx, MovingPlatform, {position: {x: 0,y: 0,z: 0}});

music

const music: object;

Music and the guest's beat clock.

Type Declaration

bar

Get Signature

get bar(): number;

Last heard bar number.

Returns

number

beat

Get Signature

get beat(): number;

Last heard beat number.

Returns

number

beatInBar

Get Signature

get beatInBar(): number;

Last heard beat within the bar.

Returns

number

beatsPerBar

Get Signature

get beatsPerBar(): number;

Beats per bar of the last playback request.

Returns

number

bpm

Get Signature

get bpm(): number;

Tempo of the last playback request.

Returns

number

layer()

layer(
   index, 
   gain, 
   fadeMs?
): void;

Change a stem gain.

Parameters

Parameter	Type	Default value	Description
`index`	`number`	`undefined`	Stem index.
`gain`	`number`	`undefined`	Linear gain.
`fadeMs`	`number`	`0`	Ramp duration.

Returns

void

nearestBeat()

nearestBeat(): number;

Returns

number

The beat number, or NaN before a beat or without a tempo.

Example

import { music } from 'gameable';

if (music.nearestBeat() === 12 && Math.abs(music.offsetMs()) <= 45) console.log('perfect');

offsetMs()

offsetMs(): number;

Signed milliseconds since the nearest beat; negative when it is still ahead.

Returns

number

Offset, or NaN before a beat or without a tempo.

play()

play(assets, options?): void;

Stream a track or playlist.

Parameters

Parameter	Type	Description
`assets`	`string` \| `number` \| readonly (`string` \| `number`)[]	Manifest ids or handles.
`options?`	`MusicOptions`	Playback options.

Returns

void

stems()

stems(assets, options?): void;

Play synchronized stems.

Parameters

Parameter	Type	Description
`assets`	readonly (`string` \| `number`)[]	Manifest ids or handles.
`options?`	`StemOptions`	Playback options and gains.

Returns

void

stop()

stop(fadeMs?): void;

Stop music.

Parameters

Parameter	Type	Default value	Description
`fadeMs`	`number`	`0`	Fade duration.

Returns

void

Example

import { music } from 'gameable';
music.play('theme', { bpm: 120 });
music.layer(1, 0.5, 200);

NavigationBounds

const NavigationBounds: ActorClass<NavigationBoundsProps>;

Axis-aligned navigation bounds. Multiple volumes build one grid over their union; the first volume supplies agent tuning and build mode. Physics baking retries for ten seconds before falling back to flat ground. Bounds are rebuilt on spawn/destruction.

Example

spawnActor(ctx, NavigationBounds, { position: { x: 0, y: 0, z: 0 }, props: { build: 'flat' } });

NavigationLink

const NavigationLink: ActorClass<NavigationLinkProps>;

Adds an off-grid connection while alive. Both endpoint cells must be walkable. Bounds rebuilds and save/restore re-register the link in the new shared grid.

Example

spawnActor(ctx, NavigationLink, { position: { x: -2, y: 0, z: 0 }, props: { end: [4, 0, 0] } });

NavigationModifier

const NavigationModifier: ActorClass<NavigationModifierProps>;

Blocks or weights its XZ footprint in the shared navigation grid while alive.

Example

spawnActor(ctx, NavigationModifier, { position: { x: 2, y: 0, z: 0 } });

NO_SEAT

const NO_SEAT: -1 = -1;

The seat of a controller that belongs to no player (an AI controller).

PACKAGE

const PACKAGE: "@gameable/sdk";

Package identity marker.

Example

import { PACKAGE } from 'gameable';

console.log(PACKAGE); // 'gameable'

ParticleEffect

const ParticleEffect: ActorClass<ParticleEffectProps>;

Persistent ParticleEffect preset; activate/deactivate with the component helpers. Declare features: { vfx: true }. Emitter handles live in snapshot-safe component state.

Example

spawnActor(ctx, ParticleEffect, { position: { x: 0, y: 0, z: 0 }, props: { preset: 'smoke' } });

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.

vehicle

vehicle: object;

Host arcade handling on guest body handles.

vehicle.create()

create(
   body, 
   settings, 
   initialState?
): Readonly<VehicleState>;

Attach once to an existing dynamic body. State is borrowed until removal.

Parameters

Parameter	Type
`body`	`number`
`settings`	`VehicleSettings`
`initialState?`	`Readonly`<`VehicleState`>

Returns

Readonly<VehicleState>

Example

physics.vehicle.create(body, settings);

vehicle.remove()

remove(body): void;

Remove handling; the chassis remains alive. Safe to repeat.

Parameters

Parameter	Type
`body`	`number`

Returns

void

Example

physics.vehicle.remove(body);

vehicle.reset()

reset(
   body, 
   position, 
   rotation
): void;

Teleport and clear motion, controls and handling history.

Parameters

Parameter	Type
`body`	`number`
`position`	`Vec3`
`rotation`	`Quat`

Returns

void

Example

physics.vehicle.reset(body, position, rotation);

vehicle.setInput()

setInput(
   body, 
   controls, 
   gripScale?
): void;

Submit transient controls; omitted steps use the host parking brake.

Parameters

Parameter	Type	Default value
`body`	`number`	`undefined`
`controls`	`Readonly`<`VehicleInput`>	`undefined`
`gripScale`	`number`	`1`

Returns

void

Example

physics.vehicle.setInput(body, controls, 0.5);

vehicle.state()

state(body): Readonly<VehicleState> | undefined;

Borrow the last post-step state without allocating.

Parameters

Parameter	Type
`body`	`number`

Returns

Readonly<VehicleState> | undefined

Example

const speed = physics.vehicle.state(body)?.speed;

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.

boxCast()

boxCast(
   position, 
   halfExtents, 
   rotation, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Cast a box with a quaternion orientation.

Parameters

Parameter	Type	Description
`position`	`Vec3`	World-space query centre.
`halfExtents`	`Vec3`	Box half-size in metres.
`rotation`	`Quat`	Unit quaternion orientation.
`direction`	`Vec3`	Sweep direction; need not be normalised.
`maxDistance`	`number`	Maximum travel in metres.
`mask?`	`CollisionLayers`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	Entity to skip.

Returns

RayHit | null

The closest hit, or null on a miss; hit.distance is the shape travel in metres.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const forward = { x: 0, y: 0, z: 1 };
    const halfExtents = { x: 0.5, y: 0.5, z: 0.5 };
    const hit = physics.boxCast(position, halfExtents, rotation, forward, 1);
    console.log('can the crate be pushed forward one metre?', hit === null);
  },
});

capsuleCast()

capsuleCast(
   position, 
   radius, 
   halfHeight, 
   rotation, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Cast a capsule; halfHeight is half its straight segment.

Parameters

Parameter	Type	Description
`position`	`Vec3`	World-space query centre.
`radius`	`number`	Radius in metres.
`halfHeight`	`number`	Half the straight capsule segment in metres.
`rotation`	`Quat`	Unit quaternion orientation.
`direction`	`Vec3`	Sweep direction; need not be normalised.
`maxDistance`	`number`	Maximum travel in metres.
`mask?`	`CollisionLayers`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	Entity to skip.

Returns

RayHit | null

The closest hit, or null on a miss; hit.distance is the shape travel in metres.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const forward = { x: 0, y: 0, z: 1 };
    const hit = physics.capsuleCast(position, 0.3, 0.6, rotation, forward, 0.4);
    console.log('can the character step here?', hit === null);
  },
});

distance()

distance(
   a, 
   b, 
   options
): number;

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; `anchorB?`: `Vec3`; `max?`: `number`; `min?`: `number`; `spring?`: `JointSpring`; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.
`options.anchorB?`	`Vec3`	World-space second distance-joint end.
`options.max?`	`number`	Upper linear limit in metres.
`options.min?`	`number`	Lower linear limit in metres.
`options.spring?`	`JointSpring`	Limit frequency in Hz and damping ratio.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Weight = prefab({ body: { shape: 'sphere', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const weight = ctx.spawn(Weight, { x: 0, y: 1, z: 0 });
    // No limits: a rigid rod that keeps its initial 3 metre length.
    physics.distance(weight, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      anchorB: { x: 0, y: 4, z: 0 },
    });
  },
});

fixed()

fixed(
   a, 
   b, 
   options?
): number;

Create a fixed joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Default value	Description
`a`	`number`	`undefined`	First entity, with a physics body.
`b`	`number`	`undefined`	Second entity, or 0 to join to the world.
`options`	{ `anchor?`: `Vec3`; }	`EMPTY_JOINT_OPTIONS`	Joint or motor settings.
`options.anchor?`	`Vec3`	`undefined`	World-space anchor at creation.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Crate = prefab({ body: { shape: 'box', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const crateA = ctx.spawn(Crate, { x: 0, y: 1, z: 0 });
    const crateB = ctx.spawn(Crate, { x: 1.1, y: 1, z: 0 });
    physics.fixed(crateA, crateB); // Weld the two crates together.
  },
});

hinge()

hinge(
   a, 
   b, 
   options
): number;

Create a hinge joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; `axis`: `Vec3`; `friction?`: `number`; `maxDeg?`: `number`; `minDeg?`: `number`; `spring?`: `JointSpring`; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.
`options.axis`	`Vec3`	World-space axis; positive motion follows +axis.
`options.friction?`	`number`	Maximum friction torque in N·m.
`options.maxDeg?`	`number`	Upper angular limit in degrees.
`options.minDeg?`	`number`	Lower angular limit in degrees.
`options.spring?`	`JointSpring`	Limit frequency in Hz and damping ratio.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Door = prefab({ body: { shape: 'box', dims: [0.5, 1, 0.05], kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const door = ctx.spawn(Door, { x: 0.5, y: 1, z: 0 });
    physics.hinge(door, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      axis: { x: 0, y: 1, z: 0 },
      minDeg: -90,
      maxDeg: 90,
    });
  },
});

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.

jointValue()

jointValue(id, axis?): number | null;

Read a joint coordinate, degrees for rotation, metres for translation or distance length. Distance returns the current unsigned length; unavailable coordinates return null.

Parameters

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	Guest-minted joint handle.
`axis`	`number`	`0`	Joint axis: 0 for one-axis joints, 0 through 5 for six-dof.

Returns

number | null

The coordinate in degrees for rotation or metres for translation/length, or null when unavailable.

Example

import { defineGame, physics, prefab } from 'gameable';

const Lever = prefab({ body: { shape: 'box', kind: 'dynamic' } });
let leverJoint = 0;
export default defineGame({
  init(ctx) {
    const lever = ctx.spawn(Lever, { x: 0, y: 1, z: 0 });
    leverJoint = physics.hinge(lever, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      axis: { x: 1, y: 0, z: 0 },
      minDeg: -90,
      maxDeg: 90,
    });
  },
  systems: [
    () => {
      const angle = physics.jointValue(leverJoint);
      const isLeverDown = angle !== null && angle < -80;
      if (isLeverDown) console.log('lever down');
    },
  ],
});

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.

overlapBox()

overlapBox(
   position, 
   halfExtents, 
   rotation, 
   maxResults?, 
   mask?, 
   ignoreEntity?
): readonly OverlapHit[];

Overlap a box.

Parameters

Parameter	Type	Default value	Description
`position`	`Vec3`	`undefined`	World-space query centre.
`halfExtents`	`Vec3`	`undefined`	Box half-size in metres.
`rotation`	`Quat`	`undefined`	Unit quaternion orientation.
`maxResults`	`number`	`16`	Maximum number of hits.
`mask?`	`CollisionLayers`	`undefined`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	`undefined`	Entity to skip.

Returns

readonly OverlapHit[]

The overlapping hits, nearest first; an empty list when nothing overlaps.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const halfExtents = { x: 2, y: 1, z: 2 };
    const hits = physics.overlapBox(position, halfExtents, rotation);
    console.log(
      'bodies in this area',
      hits.map((hit) => hit.entity),
    );
  },
});

overlapCapsule()

overlapCapsule(
   position, 
   radius, 
   halfHeight, 
   rotation, 
   maxResults?, 
   mask?, 
   ignoreEntity?
): readonly OverlapHit[];

Overlap a capsule.

Parameters

Parameter	Type	Default value	Description
`position`	`Vec3`	`undefined`	World-space query centre.
`radius`	`number`	`undefined`	Radius in metres.
`halfHeight`	`number`	`undefined`	Half the straight capsule segment in metres.
`rotation`	`Quat`	`undefined`	Unit quaternion orientation.
`maxResults`	`number`	`16`	Maximum number of hits.
`mask?`	`CollisionLayers`	`undefined`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	`undefined`	Entity to skip.

Returns

readonly OverlapHit[]

The overlapping hits, nearest first; an empty list when nothing overlaps.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const hits = physics.overlapCapsule(position, 2, 1, rotation);
    console.log(
      'bodies in this area',
      hits.map((hit) => hit.entity),
    );
  },
});

overlapShape()

overlapShape(
   shape, 
   position, 
   rotation, 
   maxResults?, 
   mask?, 
   ignoreEntity?
): readonly OverlapHit[];

Overlap a primitive shape.

Parameters

Parameter	Type	Default value	Description
`shape`	`QueryShape`	`undefined`	Primitive shape and its dimensions in metres.
`position`	`Vec3`	`undefined`	World-space query centre.
`rotation`	`Quat`	`undefined`	Unit quaternion orientation.
`maxResults`	`number`	`16`	Maximum number of hits.
`mask?`	`CollisionLayers`	`undefined`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	`undefined`	Entity to skip.

Returns

readonly OverlapHit[]

Hits nearest first, with the deepest contact point on each other body and real penetration depth (bounds centre and zero depth if no contact is available).

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const shape = { kind: 'cylinder', halfExtents: { x: 2, y: 1, z: 0 } } as const;
    const hits = physics.overlapShape(shape, position, rotation);
    console.log(
      'bodies in this area',
      hits.map((hit) => hit.entity),
    );
  },
});

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.

point()

point(
   a, 
   b, 
   options
): number;

Create a point joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Lamp = prefab({ body: { shape: 'sphere', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const lamp = ctx.spawn(Lamp, { x: 0, y: 3, z: 0 });
    physics.point(lamp, 0, { anchor: { x: 0, y: 4, z: 0 } });
  },
});

raycast()

raycast(
   origin, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?, 
   ignoreBody?
): 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.
`ignoreBody?`	`number`	Additional body to skip, such as a projectile while ignoring its owner entity.

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.

removeJoint()

removeJoint(id): void;

Remove a joint.

Parameters

Parameter	Type	Description
`id`	`number`	Guest-minted joint handle.

Returns

void

Nothing.

Example

import { defineGame, physics, prefab } from 'gameable';

const Crate = prefab({ body: { shape: 'box', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const crate = ctx.spawn(Crate, { x: 0, y: 1, z: 0 });
    const weld = physics.fixed(crate, 0);
    physics.removeJoint(weld);
  },
});

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.

setMotor()

setMotor(id, options): void;

Set a motor; rotational targets use degrees or degrees per second.

Parameters

Parameter	Type	Description
`id`	`number`	Guest-minted joint handle.
`options`	{ `axis?`: `number`; `maxForce?`: `number`; `mode`: `MotorMode`; `target`: `number`; }	Joint or motor settings.
`options.axis?`	`number`	Motor axis index: 0 for hinge/slider, 0..5 for six-dof.
`options.maxForce?`	`number`	Force limit in N or torque limit in N·m; omitted or 0 means 100, too weak to lift anything heavy (a 20 kg lift needs over 196 N).
`options.mode`	`MotorMode`	Off, velocity, or position control.
`options.target`	`number`	Metres or degrees; per second for velocity mode.

Returns

void

Nothing.

Example

import { defineGame, physics, prefab } from 'gameable';

const Body = prefab({ body: { shape: 'box', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const door = ctx.spawn(Body, { x: 0.5, y: 1, z: 0 });
    const doorJoint = physics.hinge(door, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      axis: { x: 0, y: 1, z: 0 },
      minDeg: -90,
      maxDeg: 90,
    });
    physics.setMotor(doorJoint, { mode: 'position', target: 90 });
    const lift = ctx.spawn(Body, { x: 3, y: 1, z: 0 });
    const liftJoint = physics.slider(lift, 0, {
      anchor: { x: 3, y: 1, z: 0 },
      axis: { x: 0, y: 1, z: 0 },
      min: 0,
      max: 5,
    });
    physics.setMotor(liftJoint, { mode: 'velocity', target: 1 }); // 1 m/s upward.
  },
});

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.

shapeCast()

shapeCast(
   shape, 
   position, 
   rotation, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Cast a primitive shape along a direction.

Parameters

Parameter	Type	Description
`shape`	`QueryShape`	Primitive shape and its dimensions in metres.
`position`	`Vec3`	World-space query centre.
`rotation`	`Quat`	Unit quaternion orientation.
`direction`	`Vec3`	Sweep direction; need not be normalised.
`maxDistance`	`number`	Maximum travel in metres.
`mask?`	`CollisionLayers`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	Entity to skip.

Returns

RayHit | null

The closest hit, or null on a miss; hit.distance is the shape travel in metres.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const rotation = { x: 0, y: 0, z: 0, w: 1 };
    const forward = { x: 0, y: 0, z: 1 };
    const shape = { kind: 'cylinder', halfExtents: { x: 0.4, y: 0.5, z: 0 } } as const;
    const hit = physics.shapeCast(shape, position, rotation, forward, 2);
    console.log('travel before contact', hit?.distance);
  },
});

sixDof()

sixDof(
   a, 
   b, 
   options
): number;

Create a sixDof joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; `axes`: readonly [`JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`]; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.
`options.axes`	readonly [`JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`, `JointAxis`]	Six axis settings: tx, ty, tz, rx, ry, rz; rotational limits in degrees.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Hook = prefab({ body: { shape: 'box', kind: 'dynamic' } });
const locked = { mode: 'locked', min: 0, max: 0 } as const;
const free = { mode: 'free', min: 0, max: 0 } as const;
export default defineGame({
  init(ctx) {
    const hook = ctx.spawn(Hook, { x: 0, y: 3, z: 0 });
    physics.sixDof(hook, 0, {
      anchor: { x: 0, y: 3, z: 0 },
      axes: [locked, locked, locked, free, free, free],
    });
  },
});

slider()

slider(
   a, 
   b, 
   options
): number;

Create a slider joint. Bodyless entities return 0; b=0 anchors to the world.

Parameters

Parameter	Type	Description
`a`	`number`	First entity, with a physics body.
`b`	`number`	Second entity, or 0 to join to the world.
`options`	{ `anchor`: `Vec3`; `axis`: `Vec3`; `friction?`: `number`; `max?`: `number`; `min?`: `number`; `spring?`: `JointSpring`; }	Joint or motor settings.
`options.anchor`	`Vec3`	World-space anchor at creation.
`options.axis`	`Vec3`	World-space axis; positive motion follows +axis.
`options.friction?`	`number`	Maximum friction force in N.
`options.max?`	`number`	Upper linear limit in metres.
`options.min?`	`number`	Lower linear limit in metres.
`options.spring?`	`JointSpring`	Limit frequency in Hz and damping ratio.

Returns

number

The joint id, or 0 when either entity has no body (b = 0 means the world).

Example

import { defineGame, physics, prefab } from 'gameable';

const Drawer = prefab({ body: { shape: 'box', kind: 'dynamic' } });
export default defineGame({
  init(ctx) {
    const drawer = ctx.spawn(Drawer, { x: 0, y: 1, z: 0 });
    physics.slider(drawer, 0, {
      anchor: { x: 0, y: 1, z: 0 },
      axis: { x: 0, y: 0, z: 1 },
      min: 0,
      max: 0.6,
    });
  },
});

sphereCast()

sphereCast(
   position, 
   radius, 
   direction, 
   maxDistance, 
   mask?, 
   ignoreEntity?
): RayHit | null;

Cast a sphere.

Parameters

Parameter	Type	Description
`position`	`Vec3`	World-space query centre.
`radius`	`number`	Radius in metres.
`direction`	`Vec3`	Sweep direction; need not be normalised.
`maxDistance`	`number`	Maximum travel in metres.
`mask?`	`CollisionLayers`	Layers to consider, or every layer when omitted.
`ignoreEntity?`	`number`	Entity to skip.

Returns

RayHit | null

The closest hit, or null on a miss; hit.distance is the shape travel in metres.

Example

import { defineGame, physics } from 'gameable';

export default defineGame({
  init() {
    const position = { x: 0, y: 1, z: 0 };
    const forward = { x: 0, y: 0, z: 1 };
    const hit = physics.sphereCast(position, 0.5, forward, 2);
    console.log('will the ball fit through this passage?', hit === null);
  },
});

teleport()

teleport(
   entity, 
   x, 
   y, 
   z, 
   rotation?
): 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.
`rotation?`	`Quat`	Optional facing; defaults to identity for existing callers.

Returns

void

Nothing.

Example

import { physics, Transform } from 'gameable';

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

PhysicsJoint

const PhysicsJoint: ActorClass<PhysicsJointProps>;

Level-placed joint joining named actor roots; empty B anchors to the world.

Example

spawnActor(ctx, PhysicsJoint, { position: { x: 1, y: 2, z: 0 }, props: { actorA: 'door' } });

PhysicsVolume

const PhysicsVolume: ActorClass<{
  gravityScale: number;
  halfExtents: number[];
  priority: number;
  terminalVelocity: number;
  water: boolean;
}>;

Highest-priority overlapping volume controls bodyless gravity and falling speed. Equal priorities use spawn order. Water halves requested character horizontal speed. Character gravity/buoyancy cannot be changed by the current guest-host protocol: Jolt owns airborne Y velocity and ignores requested Y until grounded. Gravity scale and terminal velocity therefore apply only to non-body Velocity entities.

Example

spawnActor(ctx, PhysicsVolume, { position: { x: 0, y: 0, z: 0 }, props: { gravityScale: 0.2, priority: 1 } });

Pickup

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

Tag: something the player can pick up. The actor is exported separately as PickupActor.

PickupActor

const PickupActor: ActorClass<PickupProps>;

Player reward volume with optional spinning/bobbing mesh. Customize by spreading its spec and overriding onPickedUp.

The ECS marker is exported separately as Pickup.

Example

spawnActor(ctx, PickupActor, { position: {x: 0,y: 1,z: 0}, props: {give: {score: 10}} });

Player

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

Tag: the entity the player controls.

PlayerController

const PlayerController: ActorClass;

A seated controller for an existing player body.

Example

const controller = playerControllerOf(0);

PlayerStart

const PlayerStart: ActorClass<{
  seat: number | null;
  tag: string;
}>;

Player spawn marker; yaw comes from its root transform. Seat null accepts any seat.

Example

spawnActor(ctx, PlayerStart, { position: { x: 2, y: 0, z: 0 }, yaw: 90, props: { tag: 'red', seat: 0 } });

PlayerState

const PlayerState: ActorClass<PlayerStateProps>;

A player's match statistics.

Example

spawnActor(ctx, PlayerState, { position, props: { seat: 0 } });

playtest

const playtest: object;

The playtest facade.

Call death where the game kills the player, win where it is won, goal with where the player is meant to go, checkpoint where they reach one, and hazard for what kills on touch (spikes, enemies). That is what lets the agent learn the game and the reports say where and why players die.

Type Declaration

checkpoint()

checkpoint(position?, note?): void;

The player reached a checkpoint. The playtest agent's next life, after a death, a fall or a timeout, starts at the last checkpoint rather than the run's start, facing as the player did.

Parameters

Parameter	Type	Default value	Description
`position`	`Vec3` \| `null`	`null`	Where it is, or null for where the player stands.
`note`	`string`	`''`	Which one, or `''`.

Returns

void

damage()

damage(amount, cause?): void;

The player took damage.

Parameters

Parameter	Type	Default value	Description
`amount`	`number`	`undefined`	How much.
`cause`	`string`	`''`	From what, or `''`.

Returns

void

death()

death(cause?, position?): void;

The player died.

Parameters

Parameter	Type	Default value	Description
`cause`	`string`	`''`	Why, in a few words: `lava`, `fell`, `enemy:slime`.
`position`	`Vec3` \| `null`	`null`	Where, when it is not where the player stands.

Returns

void

goal()

goal(position, entity?): void;

Where the player is meant to go next: the flag, the exit, the next checkpoint. Say it again when it moves on.

Parameters

Parameter	Type	Default value	Description
`position`	`Vec3` \| `null`	`undefined`	Where, or null when there is no goal.
`entity`	`number`	`0`	The goal's entity, when it is one, so its position is followed.

Returns

void

hazard()

hazard(
   entity, 
   radius?, 
   position?
): void;

Something that hurts or kills on any touch: spikes, lava, an enemy that cannot be stomped. The playtest's route goes around it, or jumps it when there is no way round, and the route pilot jumps one in its way. An enemy the player beats by landing on it is not one: the pilot stomps what is close ahead of its feet. Its body is followed, so a moving one is avoided where it is now; when the entity is gone, so is the hazard. Say it once, when it is spawned.

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	The hazard's entity.
`radius`	`number`	`0`	Metres around its middle to keep clear of; 0 for about its size (half a metre).
`position`	`Vec3` \| `null`	`null`	Where it is, for an entity with no body; null to follow its body.

Returns

void

mark()

mark(
   kind, 
   value?, 
   entity?, 
   position?, 
   note?
): void;

A mark of the game's own kind.

Parameters

Parameter	Type	Default value	Description
`kind`	`string`	`undefined`	A short word: `jump-pad`, `secret`.
`value`	`number`	`0`	An amount, or 0.
`entity`	`number`	`0`	The entity it concerns, or 0.
`position`	`Vec3` \| `null`	`null`	Where, or null.
`note`	`string`	`''`	A few words, or `''`.

Returns

void

player()

player(entity): void;

The entity the player controls. A game whose declarative player block spawns it has this said for it; call it when the game spawns its own, or swaps the player to another.

Parameters

Parameter	Type	Description
`entity`	`number`	The player's entity.

Returns

void

restart()

restart(): void;

The run starts over: the level reloaded, the round reset.

Returns

void

reward()

reward(amount, note?): void;

Something good happened: a coin, a kill, progress. The agent learns to seek it.

Parameters

Parameter	Type	Default value	Description
`amount`	`number`	`undefined`	How good; 1 is a typical pickup.
`note`	`string`	`''`	What, or `''`.

Returns

void

win()

win(note?): void;

The game is won: the level is done, the race finished, the boss beaten.

Parameters

Parameter	Type	Default value	Description
`note`	`string`	`''`	What was won, or `''`.

Returns

void

Example

import { defineGame, playtest } from 'gameable';

export default defineGame({
  init() {
    playtest.goal({ x: 0, y: 12, z: -40 });
  },
  systems: [
    (ctx) => {
      if (ctx.frame === 600) playtest.death('lava');
    },
  ],
});

PointLight

const PointLight: ActorClass<{
  color: number[];
  intensity: number;
  radius: number;
}>;

Placeable light placeholder until the host accepts guest light commands. Emits one warning per instance at beginPlay and preserves authored props.

Example

spawnActor(ctx, PointLight, { position: { x: 0, y: 2, z: 0 } });

PostProcessVolume

const PostProcessVolume: ActorClass<object & object>;

Local post overrides inside a rotated box, or everywhere when unbound. Declare features: { vfx: true }. Null settings do not override earlier settings. V1 supports blendRadius=0 only. Do not also call ctx.vfx.post when using volumes. Room authorities skip composition because they have no single local view.

Example

spawnActor(ctx, PostProcessVolume, { position: { x: 0, y: 0, z: 0 }, props: { bloom: 0.5 } });

PressurePlate

const PressurePlate: ActorClass<PressurePlateProps>;

A floor plate supplying a signal while enough occupants stand in its top footprint.

Example

spawnActor(ctx, PressurePlate, { position: { x: 0, y: 0, z: 0 }, name: 'plate1' });

Projectile

const Projectile: ActorClass<ProjectileProps & object>;

Swept projectile with owner-attributed damage and a finite bounce budget.

Example

spawnActor(ctx, Projectile, {position: muzzle, owner: shooter, props: {damage: 25}});

Renderable

const Renderable: RenderableStore;

Renderable asset attached to an entity.

RigidBody

const RigidBody: RigidBodyStore;

Physics body attached to an entity.

score

const score: object;

Per-player score counter; owner is a seat index, never an entity id.

Type Declaration

add()

add(seat, amount): void;

Parameters

Parameter	Type
`seat`	`number`
`amount`	`number`

Returns

void

get()

get(seat): number;

Parameters

Parameter	Type
`seat`	`number`

Returns

number

Example

console.log(score.get(0));

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.

SlidingDoor

const SlidingDoor: ActorClass<SlidingDoorProps>;

One or two painted panels sliding in the closed door's local frame.

Example

spawnActor(ctx, SlidingDoor, { position: { x: 0, y: 1.05, z: 0 }, props: { panels: 2 } });

SNAPSHOT_VERSION

const SNAPSHOT_VERSION: 3 = 3;

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

SoftPlatform

const SoftPlatform: ActorClass<{
  asset: string;
  scale: [number, number, number];
  tint: [number, number, number];
}>;

One-way surface for characterMovement capsules. Pass upward through the underside; downward movement lands on its top. Axis-aligned placement and scale only. Other body/controller types pass through it in either direction. Optional mesh scale affects only the look; the one-way surface keeps its authored dimensions.

Example

spawnActor(ctx, SoftPlatform, { position: { x: 3, y: 2, z: 0 }, props: { asset: 'platform' } });

Spawner

const Spawner: ActorClass<SpawnerProps>;

Spawn registered actor classes in gameplay waves; destruction counts as a kill on the next fixed step.

Example

spawnActor(ctx, Spawner, {position: {x: 0,y: 0,z: 0},props: {actorClass: 'Enemy'}});

Spectator

const Spectator: ActorClass<{
  maxSpeed: number;
}>;

A flying spectator without collision or health to damage.

Example

const pawn = spawnActor(ctx, Spectator, { position: { x: 0, y: 2, z: 0 } });

SpotLight

const SpotLight: ActorClass<{
  angle: number;
  cameraAttached: boolean;
  color: number[];
  enabled: boolean;
  intensity: number;
  penumbra: number;
  radius: number;
}>;

Rendered spotlight. Local forward is -Z; cameraAttached follows the active view. Toggle enabled or change props; settings are sent only when changed.

Example

spawnActor(ctx, SpotLight, { position: { x: 0, y: 0, z: 0 }, props: { cameraAttached: true } });

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 'gameable';

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

TargetPoint

const TargetPoint: ActorClass<{
  tag: string;
}>;

Named destination with no collision or behaviour.

Example

spawnActor(ctx, TargetPoint, { name: 'goal', position: { x: 0, y: 0, z: 4 }, props: { tag: 'route' } });

things

const things: object;

The things facade: the made world the host loaded, as game code sees it.

The list arrives once (world-event, kind loaded) and is kept up to date as loose things move (moved); the questions answer from it with no call to the host. push, move and reset are commands the host applies to a loose thing's body. A knock arrives in ctx.events as a world-event of kind hit, with the thing's index, where, and how hard (0 to 1).

Type Declaration

all

Get Signature

get all(): readonly WorldThing[];

Every thing, loose or fixed; empty before a world has loaded.

Returns

readonly WorldThing[]

world

Get Signature

get world(): WorldList | null;

The world the things are in (its name, the start, the walk limit), or null before one has loaded.

Returns

WorldList | null

breakApart()

breakApart(
   thing, 
   x?, 
   y?, 
   z?
): void;

Break a thing in pieces (thing.pieces): each piece becomes a body of its own where it stood, moving as the thing moved, and a piece the package marks fixed stays put. Given one piece (thing.pieceOf), that piece alone comes off. The broken event follows, and reset makes the thing whole again.

Parameters

Parameter	Type	Default value	Description
`thing`	`number` \| `WorldThing`	`undefined`	The thing, a piece of one, or the index of either.
`x`	`number`	`0`	Metres a second added to each piece that comes off, x.
`y`	`number`	`0`	The same, y.
`z`	`number`	`0`	The same, z.

Returns

void

Nothing; a thing that is not in pieces is left as it is.

drive()

drive(
   thing, 
   throttle, 
   right, 
   brake?
): void;

Drive a thing that can be driven (thing.drives): the rider's wish, held until the next call. Send zeros to let go.

Parameters

Parameter	Type	Default value	Description
`thing`	`number` \| `WorldThing`	`undefined`	The thing, or its index.
`throttle`	`number`	`undefined`	From -1 (back) to 1 (forward).
`right`	`number`	`undefined`	Steering, from -1 (left) to 1 (right).
`brake`	`number`	`0`	The brakes, from 0 to 1.

Returns

void

Nothing.

find()

find(words): WorldThing | null;

The thing some words name ("the trunk"), or null.

Parameters

Parameter	Type	Description
`words`	`string`	What was said.

Returns

WorldThing | null

The best match, or null.

findAll()

findAll(words, out?): WorldThing[];

Every thing that answers some words, the best first.

Parameters

Parameter	Type	Default value	Description
`words`	`string`	`undefined`	What was said.
`out`	`WorldThing`[]	`[]`	The array to fill.

Returns

WorldThing[]

out.

getOff()

getOff(thing): void;

Whoever sits on a thing gets off: the character is back on its entity. Move the entity to where it should stand first (physics.teleport), beside the thing.

Parameters

Parameter	Type	Description
`thing`	`number` \| `WorldThing`	The thing, or its index.

Returns

void

Nothing.

getOn()

getOn(thing, entity): void;

Sit a character on a thing that has rider spots (thing.rider): its hips go on the seat, its hands are held to the grips as they turn, its feet to the rests, and it leans and moves with the thing. The host does it every frame from the character's own skeleton; the entity itself stays where it was (take its body out of the simulation with physics.setEnabled(entity, false) so the thing does not run into it).

Parameters

Parameter	Type	Description
`thing`	`number` \| `WorldThing`	The thing, or its index.
`entity`	`number`	The character's entity.

Returns

void

Nothing; a thing with no rider spots is ignored.

joint()

joint(
   thing, 
   joint, 
   value
): void;

Set one joint of a thing with moving parts: a lid opened, handlebars turned. The value is held to the joint's limits by the host.

Parameters

Parameter	Type	Description
`thing`	`WorldThing`	The thing.
`joint`	`string` \| `number`	The joint's name (`'steering'`) or its place in `thing.joints`.
`value`	`number`	Degrees for a hinge, metres for a slide.

Returns

void

Nothing; a name the thing does not have is ignored.

limit()

limit(
   x, 
   z, 
   velocity
): void;

Keep a walker inside the world's walk limit: changes velocity in place.

Parameters

Parameter	Type	Description
`x`	`number`	Where the walker is, x.
`z`	`number`	Where the walker is, z.
`velocity`	`Vec3`	The velocity asked for.

Returns

void

Nothing.

move()

move(
   thing, 
   x, 
   y, 
   z
): void;

Put a loose thing somewhere: the middle of its base at this point, at rest.

Parameters

Parameter	Type	Description
`thing`	`number` \| `WorldThing`	The thing, or its index.
`x`	`number`	Where, x.
`y`	`number`	Where, y.
`z`	`number`	Where, z.

Returns

void

Nothing.

near()

near(at, radius): readonly WorldThing[];

What is near a point, the nearest first. The array is reused by the next call.

Parameters

Parameter	Type	Description
`at`	`Vec3`	The point.
`radius`	`number`	Metres.

Returns

readonly WorldThing[]

The things within radius.

push()

push(
   thing, 
   x, 
   y, 
   z
): void;

Shove a loose thing: an impulse at its middle, in newton-seconds.

Parameters

Parameter	Type	Description
`thing`	`number` \| `WorldThing`	The thing, or its index.
`x`	`number`	Impulse x.
`y`	`number`	Impulse y.
`z`	`number`	Impulse z.

Returns

void

Nothing.

reset()

reset(thing?): void;

Put a loose thing back where the package had it; with no thing, all of them.

Parameters

Parameter	Type	Description
`thing?`	`number` \| `WorldThing`	The thing, its index, or nothing for every loose thing.

Returns

void

Nothing.

spot()

spot(thing, name): WorldSpotNow | null;

Where one of a thing's rider spots is now, in the world (seat, gripLeft, gripRight, footLeft, footRight): a grip turns with the handlebars. The record is reused by the next call.

Parameters

Parameter	Type	Description
`thing`	`WorldThing`	The thing.
`name`	`string`	The spot's name.

Returns

WorldSpotNow | null

The spot's place, the way it faces and its up; null when the thing has no such spot.

standFor()

standFor(thing, from?): WorldStand;

Where to stand to use a thing. The record is reused by the next call.

Parameters

Parameter	Type	Default value	Description
`thing`	`WorldThing`	`undefined`	The thing.
`from`	`Vec3` \| `null`	`null`	Where the asker is, to stand on the nearest side; omit for the package's own spot.

Returns

WorldStand

The spot and the facing.

Example

import { defineGame, things } from 'gameable';

export default defineGame({
  update(ctx) {
    for (const event of ctx.events) {
      if (event.tag !== 'world-event') continue;
      if (event.val.kind === 'loaded') {
        const trunk = things.find('the trunk');
        if (trunk) console.log('stand at', things.standFor(trunk));
      } else if (event.val.kind === 'hit') {
        console.log(things.all[event.val.thing]?.label, 'was knocked', event.val.strength);
      }
    }
  },
});

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.

TrapDoor

const TrapDoor: ActorClass<TrapDoorProps>;

A flat wood hatch hinged at local -Z that swings down about local X. onPassed is never fired: doorway plane crossings are not meaningful for a hatch.

Example

spawnActor(ctx, TrapDoor, { position: { x: 0, y: 0, z: 0 }, props: { opensWhen: ['switch'] } });

TriggerBox

const TriggerBox: ActorClass<object>;

Overlap marker. Sizes are read from props at spawn; overlaps use entity root points.

Example

spawnActor(ctx, TriggerBox, { name: 'gate', position: { x: 0, y: 0, z: 0 } });

TriggerCapsule

const TriggerCapsule: ActorClass<object>;

Overlap marker. Sizes are read from props at spawn; overlaps use entity root points.

Example

spawnActor(ctx, TriggerCapsule, { name: 'gate', position: { x: 0, y: 0, z: 0 } });

TriggerSphere

const TriggerSphere: ActorClass<object>;

Overlap marker. Sizes are read from props at spawn; overlaps use entity root points.

Example

spawnActor(ctx, TriggerSphere, { name: 'gate', position: { x: 0, y: 0, z: 0 } });

ui

const ui: object;

Retained UI and player interactions for the active guest.

Type Declaration

events

Get Signature

get events(): readonly UiEvent[];

This tick's UI events in arrival order; the array is reused each tick.

Returns

readonly UiEvent[]

The pooled event array.

clear()

clear(): void;

Clear the UI once; subsequent clears emit nothing.

Returns

void

clicked()

clicked(id): boolean;

Parameters

Parameter	Type	Description
`id`	`string`	Button or clickable card id.

Returns

boolean

Whether it was clicked this tick.

dropped()

dropped(id): UiEvent | null;

Parameters

Parameter	Type	Description
`id`	`string`	Draggable node id.

Returns

UiEvent | null

Its drop event this tick, including the target, or null.

invalidate()

invalidate(): void;

Forget the previous model so the next set emits again.

Returns

void

set()

set(nodes, options?): boolean;

Emit a model only when its value changes, comparing up to 24 levels.

Parameters

Parameter	Type	Description
`nodes`	`UiNode` \| readonly `UiNode`[]	One node or the ordered top-level nodes.
`options?`	{ `theme?`: `UiTheme`; }	Optional theme overrides.
`options.theme?`	`UiTheme`	Theme token overrides.

Returns

boolean

True when JSON will cross this frame.

submitted()

submitted(id): boolean;

Parameters

Parameter	Type	Description
`id`	`string`	Input id.

Returns

boolean

Whether Enter submitted it this tick.

value()

value(id): string | null;

Parameters

Parameter	Type	Description
`id`	`string`	Input id.

Returns

string | null

Latest changed or submitted text across ticks, or null if unedited.

Example

import { defineGame, ui } from 'gameable';
defineGame({ systems: [() => {
  ui.set({ type: 'button', id: 'play', text: 'Play' });
  if (ui.clicked('play')) ui.clear();
}] });

VehicleGripVolume

const VehicleGripVolume: ActorClass<VehicleGripVolumeProps>;

Timed oil sphere. Overlapping registered vehicle chassis refresh one source until recovery seconds after last contact; multiple areas combine by minimum grip. Duration zero expires immediately. Recovery zero lasts through the current step. Scale uses the largest world scale axis. Visuals can be supplied by a separate actor.

Example

spawnActor(ctx, VehicleGripVolume, { position: hit.point, props: { radius: 3, duration: 8, gripScale: 0.15, recovery: 1 } });

Velocity

const Velocity: VelocityStore;

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

vfx

const vfx: object;

Emit particles and change the page's look. Declare features: { vfx: true }. Options and vectors are copied; reuse them in frame callbacks.

Type Declaration

burst()

burst(
   preset, 
   at, 
   options?
): void;

Play a one-shot preset at a world position.

Parameters

Parameter	Type	Description
`preset`	`VfxPreset`	Built-in preset name.
`at`	`Vec3`	World position.
`options?`	`BurstOptions`	Optional overrides.

Returns

void

Nothing.

Example

import { vfx } from 'gameable';
vfx.burst('dust', { x: 0, y: 0, z: 0 });

move()

move(id, at): void;

Move an emitter (or change its entity offset).

Parameters

Parameter	Type	Description
`id`	`number`	Handle from start; 0 is ignored.
`at`	`Vec3`	Position or offset.

Returns

void

Nothing.

Example

import { vfx } from 'gameable';
const id = vfx.start('fire', {});
vfx.move(id, { x: 1, y: 0, z: 0 });

post()

post(settings): void;

Apply partial post settings.

Parameters

Parameter	Type	Description
`settings`	`PostSettings`	Fields to change; reset first restores neutral values.

Returns

void

Nothing.

Example

import { vfx } from 'gameable';
vfx.post({ reset: true, exposure: 1.2 });

start()

start(preset, options): number;

Start an emitter that runs until stopped.

Parameters

Parameter	Type	Description
`preset`	`VfxPreset`	Built-in preset name.
`options`	`StartOptions`	Position or entity attachment and overrides.

Returns

number

A guest-minted effect handle.

Example

import { vfx } from 'gameable';
const id = vfx.start('smoke', { at: { x: 0, y: 0, z: 0 } });
vfx.stop(id);

stop()

stop(id): void;

Stop an emitter.

Parameters

Parameter	Type	Description
`id`	`number`	Handle from start; 0 is ignored.

Returns

void

Nothing.

Example

import { vfx } from 'gameable';
const id = vfx.start('trail', {});
vfx.stop(id);

Example

import { defineGame, vfx } from 'gameable';
export default defineGame({
  features: { vfx: true },
  init() {
    vfx.burst('hit-sparks', { x: 0, y: 1, z: 0 });
    vfx.post({ bloom: 0.5 });
  },
});

WheeledVehicle

const WheeledVehicle: ActorClass<WheeledVehicleProps>;

Possessable four-wheel arcade car. Authority simulation; no client prediction yet.

Example

const car = spawnActor(ctx, WheeledVehicle, { position: { x: 0, y: 1, z: 0 }, props: { handling: 'grippy', maxSpeed: 30 } });

WorldText

const WorldText: ActorClass<WorldTextProps>;

Placeable world text, included when the game composes actorWidgets() into its UI. In rooms the game's UI system chooses which side displays these guest data.

Example

spawnActor(ctx, WorldText, { position: { x: 0, y: 2, z: 0 }, props: { text: 'Welcome' } });

Functions

abilities()

function abilities(opts): ActorComponent;

Create fixed-capacity RPG stats on one actor. Register definitions at module scope or in init. All mutations are authority-only. Events borrow pooled payloads; copy before retaining. Attribute changes settle once per component step. Periodic modifiers pulse at each period including an exact expiry boundary, rather than modifying current values. Infinite lifetimes are represented by the definition, never non-JSON numbers.

Parameters

Parameter	Type	Description
`opts`	`AbilitiesOptions`	Attributes, storage ceilings (default 64 each) and event callbacks.

Returns

The component declaration.

Example

const stats = abilities({ attributes: { health: { base: 100, min: 0, max: 100 } } });

abilityCooldownRemaining()

function abilityCooldownRemaining(actor, id): number;

Read simulated seconds until the ability cooldown completes; ungranted returns zero.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`id`	`string`	Registered effect or ability id.

Returns

number

Remaining simulated seconds, or zero if ungranted.

Example

const seconds = abilityCooldownRemaining(hero, 'jump');

activateAbility()

function activateAbility(actor, id): boolean;

Spend base cost and activate; failure emits a reason, clients cannot mutate.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`id`	`string`	Registered effect or ability id.

Returns

boolean

Whether activation succeeded.

Example

const jumped = activateAbility(hero, 'jump');

activateCamera()

function activateCamera(ctx, actor): void;

Select an actor as the view target, also writing the current frame immediately. The last activation wins. A dead actor has no effect.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Running guest context.
`actor`	`ActorHandle`<{ `activateOnStart`: `boolean`; `fov`: `number`; }>	Camera actor handle.

Returns

void

Example

activateCamera(ctx, view);

activateEffect()

function activateEffect(
   ctx, 
   actor, 
   component?
): void;

Activate once; omitting the name selects the first ParticleEffect component.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`actor`	`ActorHandle`	Owning actor.
`component?`	`string`	Component name.

Returns

void

Example

activateEffect(ctx, torch, 'flame');

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.

actorCatalog()

function actorCatalog(): ActorCatalog;

Describe every registered actor without hooks, handles or mutable references.

Returns

ActorCatalog

Detached JSON-safe catalog in registry order.

Example

const json = JSON.stringify(actorCatalog());

actorClass()

function actorClass(name): ActorClass<object> | null;

Look up a class by its unique name, or return null.

Parameters

Parameter	Type	Description
`name`	`string`	Unique class name or instance lookup name.

Returns

ActorClass<object> | null

The matching class, or null.

Example

const cls = actorClass('Crate');

actorContains()

function actorContains(actor, entity): boolean;

Test an entity point against an actor's overlap shapes, including rotation and scale.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Volume actor.
`entity`	`number`	Entity to test.

Returns

boolean

True when any overlap shape contains the point.

Example

const inside = actorContains(volume, ctx.player);

actorWidgets()

function actorWidgets(): readonly UiNode[];

Borrow actor widgets in spawn/component order, with one reused array per guest. Unchanged reads allocate nothing; additions, edits and removals reconcile on the next read. The game owns ui.set; in rooms its UI system decides which side displays these guest data.

Returns

readonly UiNode[]

Borrowed visible nodes; do not mutate the array or nodes.

Example

ctx.ui.set([...myScreens, ...actorWidgets()]);

addItem()

function addItem(
   actor, 
   item, 
   amount?
): number;

Add to existing stacks then empty slots; return overflow (all on clients or dead actors).

Parameters

Parameter	Type	Default value	Description
`actor`	`ActorHandle`	`undefined`	Owning actor.
`item`	`string`	`undefined`	Catalog id.
`amount`	`number`	`1`	Nonnegative safe integer; defaults to one.

Returns

number

Uninserted amount.

Example

const overflow = addItem(actor, 'coin', 5);

addMovementInput()

function addMovementInput(
   entity, 
   worldDirection, 
   scale?
): void;

Accumulate world-space input; the component consumes and clamps it once per tick.

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Actor root entity.
`worldDirection`	`Vec3`	`undefined`	World direction.
`scale`	`number`	`1`	Analog strength.

Returns

void

Example

addMovementInput(player, { x: 1, y: 0, z: 0 });

addScore()

function addScore(
   ctx, 
   seat, 
   points
): void;

Change a logged-in player's score.

Parameters

Parameter	Type
`ctx`	`GameContext`
`seat`	\| `string` \| `number` \| `ActorHandle`<`PlayerStateProps`>
`points`	`number`

Returns

void

Example

addScore(ctx, 0, 10);

addTag()

function addTag(actor, tag): boolean;

Add an idempotent manual tag; returns false at capacity or on clients.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`tag`	`string`	Exact manual tag or hierarchical query.

Returns

boolean

Whether the tag was added or already present.

Example

addTag(hero, 'state.ready');

applyDamage()

function applyDamage(
   ctx, 
   target, 
   amount, 
   info?
): void;

Notify a class of damage, then reduce Health through the gameplay damage part. Zero health leaves the actor alive until its class decides to destroy it.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	Current game context.
`target`	`number` \| `ActorHandle`<`object`>	`undefined`	Actor receiving damage.
`amount`	`number`	`undefined`	Positive damage amount.
`info`	`DamageInfo`	`EMPTY_DAMAGE_INFO`	Damage attribution.

Returns

void

Example

applyDamage(ctx, target, 10, { instigator: attacker, type: 'fire' });

applyEffect()

function applyEffect(
   actor, 
   id, 
   source?
): boolean;

Apply an effect; false means gating, duplicate or capacity rejection. Source is saved as its root entity.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`id`	`string`	Registered effect or ability id.
`source?`	`ActorHandle`<`object`>	Optional actor responsible for application.

Returns

boolean

Whether the effect was applied or refreshed.

Example

applyEffect(hero, 'heal', healer);

applyLevelEdits()

function applyLevelEdits(
   level, 
   edits, 
   options?
): LevelFile;

Apply edits to a level document and return the new document. The input is never changed.

Parameters

Parameter	Type	Description
`level`	`LevelFile`	The document as it is.
`edits`	readonly `LevelEdit`[]	What to change, in order.
`options`	`ApplyLevelEditsOptions`	Whether to validate the result.

Returns

LevelFile

The edited document.

Throws

When an edit names an actor that is not there, a taken name, an unknown class, or an attachment that would dangle.

Example

const next = applyLevelEdits(level, [{ op: 'set', name: 'exit', position: [3, 1.2, -10.5] }]);

applyTransfer()

function applyTransfer(
   docA, 
   docB, 
   give, 
   take
): 
  | {
  a: TransferDoc;
  b: TransferDoc;
}
  | null;

Trade between two player documents: a gives b everything in give, and takes from b everything in take. A number field moves that amount (the giver must have at least that much); a list field moves those items (the giver must hold each one; an object item matches by value, whatever its key order). A missing document counts as {}.

Parameters

Parameter	Type	Description
`docA`	`unknown`	Player a's document, or null.
`docB`	`unknown`	Player b's document, or null.
`give`	`unknown`	What a gives b, such as `{ coins: 5 }`.
`take`	`unknown`	What a takes from b, such as `{ owned: ['gem'] }`.

Returns

| { a: TransferDoc; b: TransferDoc; } | null

Both new documents (the inputs are untouched), or null when the trade is impossible.

Example

import { applyTransfer } from 'gameable';

applyTransfer({ coins: 10 }, { owned: ['gem'] }, { coins: 4 }, { owned: ['gem'] });
// { a: { coins: 6, owned: ['gem'] }, b: { owned: [], coins: 4 } }

applyVehicleImpulse()

function applyVehicleImpulse(
   ctx, 
   pawn, 
   impulse, 
   point
): void;

Apply a world-space impulse at a world-space chassis point, imparting linear motion and spin. Authority/solo only; dead actors and non-vehicles are ignored. No damage is applied.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Frame context.
`pawn`	`ActorHandle`	Vehicle pawn.
`impulse`	`Vec3`	Newton-seconds along world axes.
`point`	`Vec3`	World application point; offset it from the centre to impart spin.

Returns

void

Example

applyVehicleImpulse(ctx, car, { x: 2000, y: 0, z: -4000 }, hit.point);

arriveAtLevelStart()

function arriveAtLevelStart(
   ctx, 
   entity, 
   start, 
   index?
): void;

Teleport to an arrival marker, clear motion and reset the player's view. Uses the same transform, physics and camera operations as respawnPlayer.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	Current context.
`entity`	`number`	`undefined`	Player entity.
`start`	`ActorHandle`	`undefined`	Loaded PlayerStart or TargetPoint.
`index`	`number`	`0`	Party arrival index; offsets 0, +1, -1, +2 metres along local X.

Returns

void

Example

arriveAtLevelStart(ctx, ctx.player, start);

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 'gameable';

const arena = assetId('arena');

attach()

function attach(
   ctx, 
   child, 
   parent, 
   opts?
): void;

Attach a child actor to a parent's root using local TRS; cycles throw.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current game context.
`child`	`ActorHandle`	Child actor to move.
`parent`	`ActorHandle`	Parent actor or component entity.
`opts`	`AttachmentOptions`	Local transform or spawn options.

Returns

void

Example

attach(ctx, child, parent, { offset: [0, 2, 0] });

attachedActor()

function attachedActor(className, opts?): ActorComponent;

Spawn an owned actor attached to this component, with JSON-safe instance props.

Parameters

Parameter	Type
`className`	`string`
`opts`	`ComponentOptions` & `object`

Returns

Example

const passenger = attachedActor('Passenger', { offset: [0, 1, 0] });

attachedActorOf()

function attachedActorOf(actor, component): ActorHandle<object> | null;

Find a living child, including after snapshot restoration.

Parameters

Parameter	Type
`actor`	`ActorHandle`
`component`	`string`

Returns

ActorHandle<object> | null

Example

const passenger = attachedActorOf(vehicle, 'passenger');

audioComponent()

function audioComponent(asset, opts?): ActorComponent;

Attach playback to this component's entity. Autoplay defaults to false and runs on the first step.

Parameters

Parameter	Type	Description
`asset`	`string`	Manifest audio id.
`opts`	`AudioComponentOptions`	Playback and attachment settings.

Returns

An entity-attached audio component.

Example

const sound = audioComponent('wind', { autoPlay: true, looping: true });

autoActorName()

function autoActorName(level, index): string;

The name of one entry: the written one, or the automatic one.

Parameters

Parameter	Type	Description
`level`	`LevelFile`	The level document.
`index`	`number`	The entry's index in `actors`.

Returns

string

Its name.

Throws

When there is no such entry.

Example

const name = autoActorName(level, 0);

bindVehicleInput()

function bindVehicleInput(controller, bindings?): void;

Bind a seated PlayerController; collection precedes all pawn component steps.

Parameters

Parameter	Type	Description
`controller`	`ActorHandle`	Controller actor.
`bindings`	`VehicleBindings`	Optional key overrides.

Returns

void

Example

bindVehicleInput(controller, { brake: 'Control' });

box()

function box(halfExtents, opts?): ActorComponent;

A box specified by half extents.

Parameters

Parameter	Type	Description
`halfExtents`	readonly [`number`, `number`, `number`]	Half size along each axis, in metres.
`opts`	`ShapeOptions`	Local transform or spawn options.

Returns

The component declaration.

Example

import { box } from 'gameable';
const root = box([1, 1, 1], { collision: 'block' });

breakConstraint()

function breakConstraint(
   ctx, 
   actor, 
   component?
): void;

Remove a joint immediately and prevent recreation, including before its first step.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Game context.
`actor`	`ActorHandle`	Owning actor.
`component?`	`string`	Component name; defaults to the first constraint.

Returns

void

Example

breakConstraint(ctx, door);

cameraArm()

function cameraArm(length, opts?): ActorComponent;

Hold children behind an origin, with collision retraction and exponential lag.

Parameters

Parameter	Type	Description
`length`	`number`	Arm length in metres.
`opts`	`ArmOptions`	Local transform and arm settings.

Returns

A spring arm scene component.

Example

const arm = cameraArm(4, { usePawnControlRotation: true });

cameraComponent()

function cameraComponent(opts?): ActorComponent;

Declare a point of view on an actor, with vertical field of view in degrees.

Parameters

Parameter	Type	Description
`opts`	`ComponentOptions` & `object`	Local transform and field of view (70 degrees by default).

Returns

A camera scene component.

Example

const eye = cameraComponent({ attach: 'arm', fov: 70 });

canActivate()

function canActivate(actor, id): boolean;

Query cost, cooldown, lifetime and tag gates without mutating state.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`id`	`string`	Registered effect or ability id.

Returns

boolean

Whether activation would succeed.

Example

if (canActivate(hero, 'jump')) activateAbility(hero, 'jump');

canSee()

function canSee(
   ctx, 
   actor, 
   pawn, 
   component?
): boolean;

Test sight immediately without advancing timers or firing callbacks.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`actor`	`ActorHandle`	Sensing actor.
`pawn`	`number`	Target pawn entity.
`component?`	`string`	Named sensor, or the first sensing component.

Returns

boolean

Example

if (canSee(ctx, guard, ctx.player)) guard.state.alert = true;

capsule()

function capsule(dims, opts?): ActorComponent;

A vertical capsule specified by radius and half height of its straight section.

Parameters

Parameter	Type	Description
`dims`	readonly [`number`, `number`]	Shape dimensions in metres.
`opts`	`ShapeOptions`	Local transform or spawn options.

Returns

The component declaration.

Example

import { capsule } from 'gameable';
const root = capsule([0.5, 1]);

characterBody()

function characterBody(opts?): ActorComponent;

A character controller with the SDK's default capsule dimensions.

Parameters

Parameter	Type	Description
`opts`	`ShapeOptions`	Local transform or spawn options.

Returns

The component declaration.

Example

import { characterBody } from 'gameable';
const root = characterBody();

characterMovement()

function characterMovement(options?): ActorComponent;

Kinematic capsule root driven by the guest movement solver, including pawn blocking. Use as the actor's root; submit input before the next actor step.

Parameters

Parameter	Type	Description
`options`	`CharacterMovementOptions`	Metre-based solver settings, collision profile and facing.

Returns

Root component declaration.

Example

const Hero = defineActor('Hero', { components: { root: characterMovement({ maxWalkSpeed: 4 }) } });

chaseVehicle()

function chaseVehicle(
   ctx, 
   ai, 
   target, 
   opts?
): void;

Pursue a vehicle with bounded velocity prediction and physical contact rams.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Frame context.
`ai`	`ActorHandle`	AI controller.
`target`	`ActorHandle`	Vehicle actor.
`opts`	`ChaseOptions`	Prediction horizon and ram policy.

Returns

void

Example

chaseVehicle(ctx, police, suspect, { leadTime: 0.6, ramDistance: 5, ramCooldown: 4 });

choosePlayerStart()

function choosePlayerStart(
   ctx, 
   seat, 
   tag?, 
   ignore?
): 
  | ActorHandle<{
  seat: number | null;
  tag: string;
}>
  | null;

Choose a start: matching tag when available, free starts before occupied ones, explicit seat before seat modulo candidate count. Ties use actor spawn order.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	Current context.
`seat`	`number`	`undefined`	Player seat.
`tag`	`string`	`''`	Preferred tag; falls back to all starts if none match.
`ignore`	`number`	`0`	Entity being respawned, ignored for occupancy.

Returns

| ActorHandle<{ seat: number | null; tag: string; }> | null

Chosen marker, or null when no starts exist (origin fallback).

Example

const start = choosePlayerStart(ctx, 0, 'red');

circuitStandings()

function circuitStandings(model, id): CircuitStandings | undefined;

Read a circuit from a client's parsed HUD model (for example adapter.hudModel). The HUD transport retains full state for late joiners; undefined means no publication yet.

Parameters

Parameter	Type	Description
`model`	`unknown`	Parsed HUD model.
`id`	`string`	Circuit id.

Returns

CircuitStandings | undefined

Borrowed published standings, or undefined before receipt.

Example

const state = circuitStandings(adapter.hudModel, 'track'); console.log(state?.rows);

clearVehicleGrip()

function clearVehicleGrip(
   ctx, 
   pawn, 
   sourceId?
): void;

Remove one grip source, or all sources when sourceId is omitted. Authority/solo only.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Frame context.
`pawn`	`ActorHandle`	Vehicle pawn.
`sourceId?`	`string` \| `number`	Source to clear; omit to clear all.

Returns

void

Example

clearVehicleGrip(ctx, car, 'rocket');

closeDoor()

function closeDoor(ctx, door): void;

Request closing unless stayOpen has latched.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current guest context.
`door`	`ActorHandle`<`DoorCoreProps`>	Kit door instance.

Returns

void

Example

closeDoor(ctx, door);

collisionProfile()

function collisionProfile(name): Readonly<CollisionSetup>;

Return an independent, deeply frozen profile. Unknown names list valid choices.

Parameters

Parameter	Type	Description
`name`	`string`	Profile name from the default ini.

Returns

Readonly<CollisionSetup>

A frozen collision setup and response container.

Example

const pawn = collisionProfile('Pawn');

combineMove()

function combineMove(state, out): Axis2;

Combine WASD/arrow keys, the left touch stick and the first connected physical gamepad. Sticks use a radial 0.15 deadzone, rescaled to full range; forward is positive y. The sum is clamped to the unit circle. Allocates nothing.

Parameters

Parameter	Type	Description
`state`	`object` & \| { `keys`: `KeyState`; } \| { `down`: `ArrayLike`<`number`>; }	Host input, with either snapshot or guest key storage.
`out`	`Axis2`	Reusable destination for the combined axes.

Returns

DataTableCatalogEntry[]

The destination. Never retain a caller's pooled result.

Example

import { combineMove } from 'gameable';
const move = { x: 0, y: 0 };
combineMove({ down: new Uint32Array(8), gamepads: [] }, move);

componentCatalog()

function componentCatalog(): ComponentCatalog;

Describe loaded component factories as detached JSON data.

Returns

ComponentCatalog

Versioned component catalog.

Example

const json = JSON.stringify(componentCatalog());

componentDescription()

function componentDescription(name): ComponentCatalogEntry | null;

Look up a component factory description, including deprecated names.

Parameters

Parameter	Type	Description
`name`	`string`	Component factory name.

Returns

ComponentCatalogEntry | null

Detached description, or null when unknown.

Example

const description = componentDescription('cameraArm');

computeDrive()

function computeDrive(
   state, 
   target, 
   tangent, 
   settings, 
   out
): void;

Write pursuit steering and longitudinal control into caller-owned storage. No transforms or allocation. tangent is the desired path direction; null uses the target heading alone.

Parameters

Parameter	Type	Description
`state`	`Readonly`<`DriveState`>	Borrowed pose and signed speed.
`target`	`Readonly`<`Vec3`>	World target.
`tangent`	`Readonly`<`Vec3`> \| `null`	Path direction, if available.
`settings`	`Readonly`<`DriveSettings`>	Speed, stopping distance and gains.
`out`	`VehicleInput`	Caller-owned normalized input.

Returns

void

Example

computeDrive(state, target, null, settings, input);

configureGameplayActors()

function configureGameplayActors(ctx, options?): void;

Configure shared actor services in init. Inventory owner indices are player seats (solo = 0). Parts and scores are automatically included in actor snapshots. Call again from each game init.

Parameters

Parameter	Type	Description
`ctx`	`Pick`<`GameContext`, `"world"`>	Current guest context.
`options`	{ `damage?`: `Damage`; `inventory?`: `Inventory`; }	Component or service configuration.
`options.damage?`	`Damage`	Shared gameplay health bookkeeping.
`options.inventory?`	`Inventory`	Shared inventory whose owners are player seats.

Returns

void

Example

configureGameplayActors(ctx, { inventory: createInventory({owners: 2, slots: 8, items: [{id: 'key'}]}) });

constraintValue()

function constraintValue(actor, component?): number | null;

Read a constraint coordinate in degrees (hinge) or metres; null when unavailable.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`component?`	`string`	Component name; defaults to the first constraint.

Returns

number | null

Example

const angle = constraintValue(door);

controllerOf()

function controllerOf(pawn): ActorHandle<object> | null;

Parameters

Parameter	Type	Description
`pawn`	`number` \| `ActorHandle`<`object`>	A pawn: its entity or its actor.

Returns

ActorHandle<object> | null

The living controller that possesses it, or null.

Example

const controller = controllerOf(self);

countItem()

function countItem(actor, item): number;

Count bag items, excluding equipment; dead actors hold zero.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`item`	`string`	Catalog id.

Returns

number

Total held in the bag.

Example

const coins = countItem(actor, 'coin');

createAbilities()

function createAbilities(options): Abilities;

Create preallocated charge counters. Cooldowns must be finite nonnegative seconds; zero still takes one step. Charges default to 1 and must be positive safe integers. Ids must be unique. Invalid indices and options throw. A running clock keeps the duration and dt captured when use started it, including subsequent charge cycles; spending another charge while it runs does not restart it. Queries allocate nothing.

Parameters

Parameter	Type	Description
`options`	{ `abilities`: readonly `object`[]; `onReady?`: (`ctx`, `owner`, `ability`) => `void`; `owners`: `number`; }	Owner capacity, ability definitions and optional recharge callback.
`options.abilities`	readonly `object`[]	Unique ids, cooldown seconds and charge limits.
`options.onReady?`	(`ctx`, `owner`, `ability`) => `void`	Synchronous notifications in owner then ability order.
`options.owners`	`number`	Number of owner indices, not entity ids.

Returns

Abilities

Full abilities implementing the gameplay lifecycle.

Example

import { createAbilities, defineGame } from 'gameable';
const skills = createAbilities({ owners: 1, abilities: [{ id: 'dash', cooldown: 0.5 }] });
export default defineGame({
  init: () => skills.reset(),
  systems: [(ctx) => {
    if (ctx.frame % 60 === 0) skills.use(ctx, 0, 'dash');
    skills.step(ctx);
  }],
});

createBehaviorTree()

function createBehaviorTree<C>(root, options?): BehaviorTree<C>;

Compile descriptions once; tick and reset use only preallocated storage.

Each entity has its own tick counter. Before a previously running node runs, if its last-ticked stamp is older than the previous tick, its entire subtree is reset. Thus skipping a branch for even one tick interrupts it; resetting is lazy until re-entry. Completed nodes reset their own memory immediately. Calls recurse only to the description's depth. Do not re-enter the same tree from a leaf. Reusing a description creates independent node occurrences.

Type Parameters

Type Parameter
`C`

Parameters

Parameter	Type	Description
`root`	`BtNode`<`C`>	The stateless tree description.
`options?`	{ `maxEntities?`: `number`; }	Capacity; maxEntities defaults to 4096.
`options.maxEntities?`	`number`	Maximum number of entities; defaults to 4096.

Returns

BehaviorTree<C>

A tree with independent per-entity state; invalid entity ids throw RangeError.

Example

import { bt, createBehaviorTree } from 'gameable';
const tree = createBehaviorTree(bt.wait<null>(0.5), { maxEntities: 200 });
tree.tick(null, 10, 1 / 60);
tree.reset(10);

createCharacterMovement()

function createCharacterMovement(settings?): CharacterMovement;

Create independent state and allocate all per-mover scratch outside the frame loop.

Parameters

Parameter	Type	Description
`settings`	`Partial`<`CharacterMovementSettings`>	Optional overrides of the metre-based defaults.

Returns

CharacterMovement

Computed result; caller owns or borrows it as described above.

Example

const cm = createCharacterMovement({ maxWalkSpeed: 4 });

createCheckpointModule()

function createCheckpointModule(match, options): GameplayModule;

Parameters

Parameter	Type	Description
`match`	`MatchModule`	Shared match state.
`options`	`CheckpointModuleOptions`	Immutable module configuration.

Returns

GameplayModule

The configured module with reusable state.

Example

import { createCheckpointModule, type MatchModule } from 'gameable';
const configure = (match: MatchModule) => createCheckpointModule(match, { axis: 'z', direction: 'decreasing', thresholds: [], points: [], spawns: [[0,3,0]], maxAbsX: 4, minY: 2, fallY: -5, lobbyRespawn: 'seat-start', resetKnock: true });
console.log(configure);

createCircuitRace()

function createCircuitRace(options): CircuitRace;

Create independent lap/places state. Start expects gate 1; only a full ordered circuit awards a lap.

Parameters

Parameter	Type	Description
`options`	`CircuitOptions`	Circuit identity, gate geometry and capacity.

Returns

CircuitRace

Preallocated crossing/ranking system and explicit snapshot adapter.

Example

import { createCircuitRace } from 'gameable';
const race = createCircuitRace({id:'track',laps:2,maxRacers:4,gates:[{position:[0,0,0],yaw:0,halfExtents:[3,2,1]},{position:[0,0,10],yaw:0,halfExtents:[3,2,1]}]});
console.log(race.standings);

createCrowd()

function createCrowd(nav, options?): Crowd;

Construct deterministic, allocation-free crowd simulation in the guest. Navigation queries must also honour their allocation-free contract.

Parameters

Parameter	Type	Description
`nav`	`NavQuery`	Navigation queries over walkable ground.
`options`	`CrowdOptions`	Capacity, avoidance and application settings.

Returns

Crowd

A crowd with all storage reserved at construction.

Example

import { createNavGrid, createCrowd } from 'gameable';
const nav = createNavGrid({ min: [-10, -10], max: [10, 10] });
nav.buildFlat();
const crowd = createCrowd(nav, { maxAgents: 50 });
crowd.add(1);
crowd.setPosition(1, -5, 0);
crowd.moveTo(1, 5, 0);
crowd.step(1 / 60);

createDamage()

function createDamage(options?): Damage;

Create preallocated health bookkeeping. Call reset from game init. Callbacks run synchronously for the entity being mutated, damage before death.

Parameters

Parameter	Type	Description
`options`	{ `capacity?`: `number`; `invulnerableSeconds?`: `number`; `onDamage?`: (`ctx`, `entity`, `amount`, `source`) => `void`; `onDeath?`: (`ctx`, `entity`, `source`) => `void`; `onHeal?`: (`ctx`, `entity`, `amount`) => `void`; `onRevive?`: (`ctx`, `entity`) => `void`; }	Entity ceiling (default current ECS ceiling), i-frame duration and callbacks.
`options.capacity?`	`number`	Fixed entity ceiling; defaults to getMaxEntities().
`options.invulnerableSeconds?`	`number`	Seconds of protection after a nonfatal hit; defaults to zero.
`options.onDamage?`	(`ctx`, `entity`, `amount`, `source`) => `void`	Called with the hp actually removed, before onDeath.
`options.onDeath?`	(`ctx`, `entity`, `source`) => `void`	Called once per death, after onDamage.
`options.onHeal?`	(`ctx`, `entity`, `amount`) => `void`	Called with the hp actually restored.
`options.onRevive?`	(`ctx`, `entity`) => `void`	Called after a dead entity is revived.

Returns

Damage

A health part; its snapshot excludes the Health component itself.

Example

import { createDamage, defineGame } from 'gameable';
const hits = createDamage({ invulnerableSeconds: 0.2 });
export default defineGame({ init: () => hits.reset(), systems: [ctx => hits.step(ctx)] });

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 'gameable';
import { createMockHost, createFrameInput } from 'gameable/test';

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

createInventory()

function createInventory(options): Inventory;

Create preallocated inventories. Item ids must be unique; stacks default to 1 and must be integers in 1..65535. At most 32768 items fit the Int16 slot index. Invalid indices, amounts and options throw. Runtime operations allocate nothing.

Parameters

Parameter	Type	Description
`options`	{ `items`: readonly `object`[]; `onChange?`: (`owner`, `item`, `total`) => `void`; `owners`: `number`; `slots`: `number`; }	Owner/slot capacities, item definitions and optional change callback.
`options.items`	readonly `object`[]	Unique ids and maximum per-slot stack sizes.
`options.onChange?`	(`owner`, `item`, `total`) => `void`	Synchronous notifications; see Inventory for ordering.
`options.owners`	`number`	Number of owner indices, not entity ids.
`options.slots`	`number`	Number of slots per owner.

Returns

Inventory

Empty inventories implementing the gameplay lifecycle.

Example

import { createInventory } from 'gameable';
const bags = createInventory({ owners: 2, slots: 3, items: [{ id: 'coin', stack: 99 }] });
bags.add(0, 'coin', 12);
bags.transfer(0, 1, 'coin', 4);
console.log(bags.count(1, 'coin')); // 4

createMatchHudModule()

function createMatchHudModule(match, options): GameplayModule;

Publish private event histories and shared roster semantics without array identity misses.

Parameters

Parameter	Type	Description
`match`	`MatchModule`	Shared match state.
`options`	`MatchHudModuleOptions`	Immutable module configuration.

Returns

GameplayModule

The configured module with reusable state.

Example

import { createMatchHudModule, type MatchModule } from 'gameable';
const configure = (match: MatchModule) => createMatchHudModule(match, { namespace: 'race', secondsStep: 0.1 });
console.log(configure);

createMatchModule()

function createMatchModule(options): MatchModule;

Construct independent match state; initialize it after guest snapshot restoration.

Parameters

Parameter	Type	Description
`options`	`MatchModuleOptions`	Immutable module configuration.

Returns

MatchModule

The configured module with reusable state.

Example

import { createMatchModule } from 'gameable';
const match = createMatchModule({ maxPlayers: 1, history: 8, spawns: [[0,3,0]], start: 'all-ready', minPlayers: 2, soloMinPlayers: 1, lateJoin: 'spectate-after-loading', spectatorSpawnZ: 3, loadingSeconds: 20, cardSeconds: 1.5, countdownSeconds: 4.5, limitSeconds: 180, afterFirstSeconds: 90, resultsSeconds: 8 });
console.log(match.state.phase);

createMoverModule()

function createMoverModule(match, options): MoverModule;

Build course prefabs at construction, then update poses using authority time.

Parameters

Parameter	Type	Description
`match`	`MatchModule`	Shared match state.
`options`	`MoverModuleOptions`	Immutable module configuration.

Returns

MoverModule

The configured module with reusable state.

Example

import { createMoverModule, type MatchModule, type MoverModuleOptions } from 'gameable';
const configure = (match: MatchModule, options: MoverModuleOptions) => createMoverModule(match, options);
console.log(configure);

createNavGrid()

function createNavGrid(options): NavGrid;

Create a bounded heightfield with allocation-free navigation queries.

Parameters

Parameter	Type	Description
`options`	`NavGridOptions`	Bounds, agent dimensions and storage limits.

Returns

NavGrid

An unbuilt navigation grid.

Example

import { createNavGrid } from 'gameable';
const grid = createNavGrid({ min: [0, 0], max: [20, 20] });
grid.buildFlat();
const path = new Float32Array(256 * 3);
const count = grid.findPath(2, 2, 18, 18, path);
console.log(count);

createPlacingModule()

function createPlacingModule(match, options): GameplayModule;

Award places before the match system decides whether racing has ended.

Parameters

Parameter	Type	Description
`match`	`MatchModule`	Shared match state.
`options`	`PlacingModuleOptions`	Immutable module configuration.

Returns

GameplayModule

The configured module with reusable state.

Example

import { createPlacingModule, type MatchModule } from 'gameable';
const configure = (match: MatchModule) => createPlacingModule(match, { axis: 'z', direction: 'decreasing', at: -68, maxAbsX: 5, minY: 2, maxY: 6, tieBreak: 'seat', requiresAllCheckpoints: false, freezeFinishers: true });
console.log(configure);

createQuests()

function createQuests(options): Quests;

Create independent quest state for integer owner seats. Duplicate ids, invalid targets and cyclic or missing prerequisites throw at creation.

Parameters

Parameter	Type	Description
`options`	{ `onComplete?`: (`owner`, `quest`) => `void`; `onObjectiveDone?`: (`owner`, `quest`, `objective`) => `void`; `onProgress?`: (`owner`, `quest`, `objective`, `value`) => `void`; `onStart?`: (`owner`, `quest`) => `void`; `owners`: `number`; `quests`: readonly `object`[]; }	Quest definitions, owner capacity and synchronous callbacks.
`options.onComplete?`	(`owner`, `quest`) => `void`	Called after all objective completion events.
`options.onObjectiveDone?`	(`owner`, `quest`, `objective`) => `void`	Called after progress first reaches its target.
`options.onProgress?`	(`owner`, `quest`, `objective`, `value`) => `void`	Called when an objective value changes.
`options.onStart?`	(`owner`, `quest`) => `void`	Called when an available quest is started.
`options.owners`	`number`	Number of independent owner seats.
`options.quests`	readonly `object`[]	Quest ids, prerequisites and objective targets.

Returns

Quests

A preallocated quest log; call reset from game init.

Example

import { createQuests } from 'gameable';
const quests = createQuests({ owners: 2, quests: [{ id: 'win', objectives: [{ id: 'points', target: 10 }] }] });
quests.start(0, 'win');
quests.progress(0, 'win', 'points', 3);

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.

createSelection()

function createSelection(max?): Selection;

Create a bounded selection (default 256); box projection uses pooled scratch.

Parameters

Parameter	Type	Default value	Description
`max`	`number`	`256`	Maximum selected entities (default 256).

Returns

Selection

A game-owned selection set.

Example

const selected = createSelection(); selected.set(unit);

createThirdPersonController()

function createThirdPersonController(clips?, platforming?): object;

Create one allocation-free camera-relative controller. 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. canJump: false (or jumpSpeed: 0) turns jumping off: Space does nothing.

update drives the single player: ctx.player from ctx.input, with ctx.camera. updatePlayers drives a room on its authority: each player's own entity (PlayerHandle.entity, so a possess moves the controller too) from that player's own input, with that player's own camera. Each seat has its own state, made the first time the seat is seen and reset whenever the seat's entity changes (a join, a respawn, a possess). Body setup preserves look; a room camera resets only when its spawn generation is acknowledged. updateLocal drives a page's own prediction body from its local player's input and camera, using that body's entity to reset the seat state.

Parameters

Parameter	Type	Description
`clips?`	`ThirdPersonClips`	Optional complete base-layer clip mapping, configured once.
`platforming?`	`PlatformingOptions`	Opt-in double jump, dash, wall jump, coyote time and buffering for physics characters.

Returns

Persistent state, reset and update functions.

reset

reset: (ctx) => void;

Reset the single player's state and look; forget every seat.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	The init context.

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.platforming

platforming: object;

state.platforming.buffer

buffer: number = 0;

state.platforming.burst

burst: number = 0;

state.platforming.cooldown

cooldown: number = 0;

state.platforming.coyote

coyote: number = 0;

state.platforming.jumps

jumps: number = 0;

state.platforming.wallLock

wallLock: number = 0;

state.platforming.x

x: number = 0;

state.platforming.z

z: 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;

stateOf

stateOf: (player) => 
  | {
  airborne: number;
  descending: boolean;
  facing: number;
  grounded: boolean;
  landing: number;
  pitch: number;
  platforming: {
     buffer: number;
     burst: number;
     cooldown: number;
     coyote: number;
     jumps: number;
     wallLock: number;
     x: number;
     z: number;
  };
  speed: number;
  state: string;
  turning: boolean;
  vx: number;
  vz: number;
  yaw: number;
}
  | undefined;

Parameters

Parameter	Type	Description
`player`	`number`	A player id.

Returns

| { airborne: number; descending: boolean; facing: number; grounded: boolean; landing: number; pitch: number; platforming: { buffer: number; burst: number; cooldown: number; coyote: number; jumps: number; wallLock: number; x: number; z: number; }; speed: number; state: string; turning: boolean; vx: number; vz: number; yaw: number; } | undefined

That seat's state, or undefined before it was first driven.

update

update: (ctx, freeze) => void;

Drive the single player one step.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	The frame context.
`freeze`	`boolean`	`false`	True to hold the player still.

Returns

void

updateLocal

updateLocal: (ctx, entity, freeze) => void;

Drive a local body from this page's player input and camera, with its own seat state. The player camera already integrates the mouse, just as on the authority.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	The client frame context.
`entity`	`number`	`undefined`	The page's own body; 0 drives nothing.
`freeze`	`boolean`	`false`	True to hold the body still.

Returns

void

Example

controller.updateLocal(ctx, ownBody);

updatePlayers

updatePlayers: (ctx, freeze) => void;

Drive every room player's own entity one step, from their own input.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	The frame context, on the authority.
`freeze`	`boolean` \| ((`player`) => `boolean`)	`false`	True to hold everyone still, or a test per player (hoist it: a function made per frame allocates), such as "this player is talking".

Returns

void

Example

const controller = createThirdPersonController();
// In init: controller.reset(ctx); in a system:
if (ctx.net.role === 'solo') controller.update(ctx);
else controller.updatePlayers(ctx);

createTimers()

function createTimers(options): Timers;

Create preallocated timers. Invalid slots throw RangeError. Nonfinite durations or nonpositive/nonfinite timesteps throw RangeError; zero/negative durations take one step. Repeating timers rearm before callbacks. All timers advance before callbacks run.

Parameters

Parameter	Type	Description
`options`	{ `capacity`: `number`; `onFire?`: (`ctx`, `timer`) => `void`; }	Slot capacity and optional synchronous onFire callback.
`options.capacity`	`number`	Number of timer slots.
`options.onFire?`	(`ctx`, `timer`) => `void`	Called synchronously in ascending slot order.

Returns

Timers

Timer slots implementing the gameplay lifecycle.

Example

import { createTimers, defineGame } from 'gameable';
const timers = createTimers({ capacity: 1 });
export default defineGame({ init(ctx) { timers.reset(); timers.start(ctx, 0, 1); }, systems: [ctx => timers.step(ctx)] });

createTopDownCamera()

function createTopDownCamera(options?): TopDownCamera;

Fixed-tilt perspective camera with keys, middle/touch drag, pinch and optional edge pan. Keep rig.state in snapshots; restore with Object.assign(rig.state, saved). Do not also declare player.camera: its host camera takes precedence.

Parameters

Parameter	Type	Description
`options`	`TopDownCameraOptions`	Controls and distance/focus limits.

Returns

TopDownCamera

A rig to update once per tick.

Example

const rig = createTopDownCamera({ distance: 14 });
defineGame({ systems: [(ctx) => rig.update(ctx, ctx.dt)] });

createTriggers()

function createTriggers(options): Triggers;

Create preallocated geometric zones. Call reset from init before adding zones. No physics or networking is consulted. Entities without Transform are outside. Events run synchronously: exits first, then enters, volume index then watch order.

Parameters

Parameter	Type	Description
`options`	{ `capacity`: `number`; `compactSnapshot?`: `boolean`; `contains?`: (`volume`, `entity`) => `boolean`; `onEnter?`: (`ctx`, `volume`, `entity`) => `void`; `onExit?`: (`ctx`, `volume`, `entity`) => `void`; `watchCapacity`: `number`; }	Fixed volume/watch ceilings and optional event callbacks.
`options.capacity`	`number`	Maximum number of volumes.
`options.compactSnapshot?`	`boolean`	Serialize only allocated volumes and occupied inside slots.
`options.contains?`	(`volume`, `entity`) => `boolean`	Optional local-space containment override for moving actor shapes.
`options.onEnter?`	(`ctx`, `volume`, `entity`) => `void`	Called after exits, in volume then watch order.
`options.onExit?`	(`ctx`, `volume`, `entity`) => `void`	Called before enters, in volume then watch order.
`options.watchCapacity`	`number`	Maximum number of watched entities.

Returns

Triggers

A trigger part whose snapshot includes volumes, watches and inside bits.

Example

import { createTriggers, defineGame } from 'gameable';
const zones = createTriggers({ capacity: 1, watchCapacity: 1 });
export default defineGame({
  init(ctx) { zones.reset(); zones.addSphere(0, 0, 0, 3); zones.watch(ctx.player); },
  systems: [ctx => zones.step(ctx)],
});

createTurns()

function createTurns(options): Turns;

Create a turn controller. Reset in init; each event-producing call supplies ctx. Time limits restart for each new turn, rather than each phase. Snapshot includes the captured dt, integer countdown, eliminated seats and skips.

Parameters

Parameter	Type	Description
`options`	{ `onPhase?`: (`ctx`, `seat`, `phase`) => `void`; `onRound?`: (`ctx`, `round`) => `void`; `onTimeout?`: (`ctx`, `seat`) => `void`; `onTurn?`: (`ctx`, `seat`, `round`) => `void`; `phases?`: readonly `string`[]; `seats`: `number`; `turnSeconds?`: `number`; }	Seats, unique phase ids, duration and ordered event callbacks.
`options.onPhase?`	(`ctx`, `seat`, `phase`) => `void`	Called when a phase starts.
`options.onRound?`	(`ctx`, `round`) => `void`	Called before turn events when a round starts.
`options.onTimeout?`	(`ctx`, `seat`) => `void`	Called before ending an expired turn.
`options.onTurn?`	(`ctx`, `seat`, `round`) => `void`	Called when an eligible seat begins its turn.
`options.phases?`	readonly `string`[]	Unique phase ids; defaults to a single turn phase.
`options.seats`	`number`	Number of seats, indexed from zero.
`options.turnSeconds?`	`number`	Turn duration in seconds; zero disables timeouts.

Returns

Turns

A preallocated controller with JSON-safe persistence.

Example

import { createTurns, defineGame } from 'gameable';
const turns = createTurns({ seats: 2, turnSeconds: 30 });
export default defineGame({
  init: ctx => { turns.reset(); turns.start(ctx); },
  systems: [ctx => {
    if (ctx.frame === 60) turns.eliminate(ctx, 0);
    turns.step(ctx);
  }],
});

createTweens()

function createTweens(options): Tweens;

Create fixed-step tweens with registered lane names for snapshots. Built-in Transform lanes follow ECS resizing. Custom names must be unique and cannot shadow built-ins; each custom array must have one name. Snapshots include target values, which restore writes back into the registered lanes. Reset and stop do not change lane values. Start does not write until step. Repeat holds its final value until the next step; yoyo swaps endpoints. All final writes and loop rearming precede onDone callbacks. Nonfinite values/durations, invalid indices or timesteps throw RangeError.

Parameters

Parameter	Type	Description
`options`	{ `capacity`: `number`; `lanes?`: `Record`<`string`, `Float32Array`<`ArrayBufferLike`>>; `onDone?`: (`ctx`, `tween`) => `void`; }	Capacity, custom lanes and optional nonloop completion callback.
`options.capacity`	`number`	Number of tween slots.
`options.lanes?`	`Record`<`string`, `Float32Array`<`ArrayBufferLike`>>	Named custom Float32Array lanes.
`options.onDone?`	(`ctx`, `tween`) => `void`	Called synchronously in ascending slot order for nonloop completions.

Returns

Tweens

The tween pool implementing the gameplay lifecycle.

Example

import { createTweens, defineGame, Transform } from 'gameable';
const tweens = createTweens({ capacity: 8 });
export default defineGame({ init(ctx) { tweens.reset(); tweens.start(ctx, Transform.x, 1, 5, 1); }, systems: [ctx => tweens.step(ctx)] });

createWalkJumpModule()

function createWalkJumpModule(match, options): WalkJumpModule;

Build the controller adapter; put its tuning in the game rules too.

Parameters

Parameter	Type	Description
`match`	`MatchModule`	Shared match state.
`options`	`WalkJumpModuleOptions`	Immutable module configuration.

Returns

WalkJumpModule

The configured module with reusable state.

Example

import { createWalkJumpModule, type MatchModule, type WalkJumpModuleOptions } from 'gameable';
const configure = (match: MatchModule, options: WalkJumpModuleOptions) => createWalkJumpModule(match, options);
console.log(configure);

createWaves()

function createWaves(options): Waves;

Create a wave spawner. Events run synchronously: wave-start, spawn attempts in ascending index order, wave-clear, then all-clear for a nonlooping finale. A looping finale omits all-clear. Call killed when an entity dies/despawns.

Parameters

Parameter	Type	Description
`options`	{ `loop?`: `boolean`; `maxAlive?`: `number`; `onAllClear?`: (`ctx`) => `void`; `onSpawn`: (`ctx`, `wave`, `index`) => `number`; `onWaveClear?`: (`ctx`, `wave`) => `void`; `onWaveStart?`: (`ctx`, `wave`) => `void`; `waves`: readonly `object`[]; }	Wave durations in seconds, capacity and callbacks.
`options.loop?`	`boolean`	Restart wave zero after the final clear.
`options.maxAlive?`	`number`	Optional positive limit on simultaneous survivors.
`options.onAllClear?`	(`ctx`) => `void`	Called after the final nonlooping clear.
`options.onSpawn`	(`ctx`, `wave`, `index`) => `number`	Called for each attempt; return an entity or zero.
`options.onWaveClear?`	(`ctx`, `wave`) => `void`	Called once all attempts and tracked entities are gone.
`options.onWaveStart?`	(`ctx`, `wave`) => `void`	Called when a wave starts.
`options.waves`	readonly `object`[]	Spawn counts and durations in seconds.

Returns

Waves

A preallocated spawner with JSON-safe persistence.

Example

import { createWaves, defineGame } from 'gameable';
const waves = createWaves({ waves: [{ count: 2, every: 0.5 }], onSpawn: () => 0 });
export default defineGame({ init: ctx => { waves.reset(); waves.start(ctx); }, systems: [ctx => waves.step(ctx)] });

crossingFraction()

function crossingFraction(
   gate, 
   from, 
   to
): number;

Forward swept plane hit fraction, or -1. Starting on the plane is not a crossing.

Parameters

Parameter	Type	Description
`gate`	`CircuitGate`	Gate geometry.
`from`	`CircuitPoint`	Previous position.
`to`	`CircuitPoint`	Current position.

Returns

number

Fraction in (0,1], or -1.

Example

console.log(crossingFraction({position:[0,0,0],yaw:0,halfExtents:[1,1,1]}, [0,0,-2], [0,0,2]));

dataAsset()

function dataAsset<Value>(name): FrozenData<Value> | null;

Find an immutable config by name, or null when absent (including table names).

Type Parameters

Type Parameter	Default type
`Value` extends `object`	`Record`<`string`, `unknown`>

Parameters

Parameter	Type	Description
`name`	`string`	Asset name.

Returns

FrozenData<Value> | null

The config object, or null.

Example

const rules = dataAsset<{ lives: number }>('Rules');

dataTable()

function dataTable<Row>(name): DataTable<Row> | null;

Find a registered table by name, or null when absent (including asset names).

Type Parameters

Type Parameter	Default type
`Row` extends `object`	`Record`<`string`, `unknown`>

Parameters

Parameter	Type	Description
`name`	`string`	Table name.

Returns

DataTable<Row> | null

The typed table, or null. The caller supplies its known row type.

Example

const loot = dataTable<{ weight: number }>('Loot');

deactivateCamera()

function deactivateCamera(ctx): void;

Release the view target; normal game/player camera writes resume next step. Without another camera writer the last view remains. Safe to repeat.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Running guest context.

Returns

void

Example

deactivateCamera(ctx);

deactivateEffect()

function deactivateEffect(
   ctx, 
   actor, 
   component?
): void;

Stop the held emitter exactly once, including component destruction.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`actor`	`ActorHandle`	Owning actor.
`component?`	`string`	Component name.

Returns

void

Example

deactivateEffect(ctx, torch);

defineAbility()

function defineAbility(definition): void;

Parameters

Parameter	Type	Description
`definition`	`AbilityDefinition`	Cost, tags and simulated-second timers.

Returns

void

Example

defineAbility({ id: 'jump', cooldown: 0, cost: { attribute: 'energy', amount: 1 } });

defineActor()

function defineActor<P>(name, spec): ActorClass<P>;

Define a unique actor class, validating its component graph immediately. lifeSpan sets an engine-owned lifespan in seconds (the Unreal SetLifeSpan equivalent); omit it or use zero for an actor that lives until explicitly destroyed.

Type Parameters

Type Parameter	Default type
`P` extends `object`	`Record`<`string`, `unknown`>

Parameters

Parameter	Type	Description
`name`	`string`	Unique class name or instance lookup name.
`spec`	`ActorSpec`<`P`>	Default components, properties and hooks.

Returns

ActorClass<P>

The registered actor class.

Example

const Marker = defineActor('Marker', { components: { root: scene() } });

defineAIController()

function defineAIController<P>(name, spec): ActorClass<AIControllerProps & P>;

Define an AI whose component retains movement when lifecycle hooks are overridden.

Type Parameters

Type Parameter
`P` extends `object`

Parameters

Parameter	Type
`name`	`string`
`spec`	`Omit`<`ActorSpec`<`AIControllerProps` & `P`>, `"components"`> & `object` & `object`

Returns

ActorClass<AIControllerProps & P>

Example

const Guard = defineAIController('Guard', { components: { root: scene() }, onMoveCompleted(self, result, ctx) {} });

defineDataAsset()

function defineDataAsset<Value>(
   name, 
   value, 
   schema?
): FrozenData<Value>;

Validate, deeply freeze and register a single config object. Assets use their name as their catalog row key; tableRef fields must reference tables, not assets.

Type Parameters

Type Parameter
`Value` extends `object`

Parameters

Parameter	Type	Description
`name`	`string`	Unique content name.
`value`	`Value`	Config object; an optional string description is used in the catalog.
`schema`	`DataSchema`	Optional field constraints.

Returns

FrozenData<Value>

The immutable config object.

Example

const rules = defineDataAsset('Rules', { lives: 3 });

defineDataTable()

function defineDataTable<Row>(name, spec): DataTable<Row>;

Define, validate and deeply freeze a table in declaration order. Missing lookups return undefined. Definitions share one namespace with assets and persist until resetDataTableRegistry(), just like actor declarations. Seed the supplied RNG in init.

Type Parameters

Type Parameter
`Row` extends `object`

Parameters

Parameter	Type	Description
`name`	`string`	Unique content name.
`spec`	{ `description`: `string`; `rows`: `Record`<`string`, `Row`>; `schema?`: `DataSchema`; }	Rows, optional schema and authoring description.
`spec.description`	`string`	Authoring description.
`spec.rows`	`Record`<`string`, `Row`>	Named content rows.
`spec.schema?`	`DataSchema`	Optional required-field constraints.

Returns

DataTable<Row>

The registered table.

Example

const loot = defineDataTable('Loot', {
  description: 'Drop weights.', rows: { coin: { weight: 3 }, gem: { weight: 1 } },
});

defineEffect()

function defineEffect(definition): void;

Register a unique effect. Init-time definitions reset with the actor runtime; module-scope declarations seed each fresh runtime, like actor classes.

Parameters

Parameter	Type	Description
`definition`	`EffectDefinition`	Effect settings; stack uses independent lifetimes, refresh restarts one lifetime.

Returns

void

Example

defineEffect({ id: 'armor', duration: 'infinite', modifiers: [] });

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 'gameable';

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 }); }],
});

defineGameMode()

function defineGameMode<P>(name, spec): ActorClass<GameModeProps & P>;

Define match rules without replacing the framework state machine.

Type Parameters

Type Parameter
`P` extends `object`

Parameters

Parameter	Type
`name`	`string`
`spec`	`Omit`<`ActorSpec`<`GameModeProps` & `P`>, `"components"`> & `Partial`<`Pick`<`ActorSpec`<`GameModeProps` & `P`>, `"components"`>> & `GameModeHooks`<`GameModeProps` & `P`>

Returns

ActorClass<GameModeProps & P>

Example

const Duel = defineGameMode('Duel', { ...GameMode.spec, props: { ...GameMode.spec.props!, minPlayers: 2 } });

defineMessage()

function defineMessage<T>(
   name, 
   check, 
   options?
): MessageDef<T>;

Declare a game message. Call it at module scope, once per name: a second definition with the same name before the next init throws.

A received payload that is over maxBytes, does not parse, fails check or makes check throw is dropped and counted in ctx.net.stats.dropped; a system never sees it.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`name`	`string`	The message name; unique within the game.
`check`	`MessageCheck`<`T`>	The game's own type guard. Pure: no clock, no randomness.
`options?`	`MessageOptions`	`maxBytes`, default 2,048 (the wire cap).

Returns

MessageDef<T>

The definition.

Throws

On a duplicate name, an empty name, a name starting with aos: (reserved for the engine, as ctx.net.setPhase's aos:phase), or a maxBytes that is not a whole number from 1 to 2,048.

Example

import { defineMessage, hasKeys } from 'gameable';

const hasFor = hasKeys('for');
export const Vote = defineMessage(
  'vote',
  (p): p is { for: number } => hasFor(p) && typeof p.for === 'number',
  { maxBytes: 64 },
);

definePlayerController()

function definePlayerController<P>(name, spec): ActorClass<P>;

Define a seated controller whose playerTick survives ordinary actor hook overrides.

Type Parameters

Type Parameter
`P` extends `object`

Parameters

Parameter	Type
`name`	`string`
`spec`	`Omit`<`ActorSpec`<`P`>, `"components"`> & `Partial`<`Pick`<`ActorSpec`<`P`>, `"components"`>> & `object`

Returns

ActorClass<P>

Example

const Controller = definePlayerController('MyController', { components: { root: scene() }, playerTick(self, input, ctx) {} });

defineProjectile()

function defineProjectile<P>(name, spec?): ActorClass<ProjectileProps & P>;

Define a projectile with shared flight, lifespan and optional impact effects. Effect-only defaults require a hook at definition; instance overrides are checked at spawn.

Type Parameters

Type Parameter	Default type
`P` extends `object`	`object`

Parameters

Parameter	Type	Description
`name`	`string`	Unique actor class name.
`spec`	`ProjectileSpec`<`P`>	Projectile defaults and actor hooks.

Returns

ActorClass<ProjectileProps & P>

The registered projectile class.

Example

const Spark = defineProjectile('Spark', { props: { hitResponse: 'effect' }, onProjectileHit(self, hit, ctx) { ctx.physics.applyImpulse(hit.entity, 0, 10, 0, hit.point.x, hit.point.y, hit.point.z); } });

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 'gameable';

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

describeDataTables()

function describeDataTables(): DataTableCatalogEntry[];

Describe declarations in registration order, detached from frozen runtime values.

Returns

JSON-safe entries for tables and assets, with row schemas and reference metadata.

Example

const catalog = JSON.stringify(describeDataTables());

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 'gameable';

despawn(enemy);

destroyActor()

function destroyActor(
   ctx, 
   handle, 
   reason?
): void;

Queue destruction inside an actor step, or complete it immediately outside one.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	Current game context.
`handle`	`ActorHandle`	`undefined`	Actor to destroy.
`reason`	`EndPlayReason`	`'destroyed'`	Reason passed to endPlay.

Returns

void

Example

destroyActor(ctx, actor, 'levelUnload');

detach()

function detach(ctx, child): void;

Detach while retaining the child's current world transform.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current game context.
`child`	`ActorHandle`	Child actor to move.

Returns

void

Example

detach(ctx, child);

doorState()

function doorState(door): Readonly<DoorStatus>;

Borrow a read-only status view; do not retain it across restore.

Parameters

Parameter	Type	Description
`door`	`ActorHandle`<`DoorCoreProps`>	Kit door instance.

Returns

Readonly<DoorStatus>

Frozen live view of phase, fraction and lock status.

Example

console.log(doorState(door).locked);

driveTowards()

function driveTowards(
   ctx, 
   ai, 
   target, 
   opts?
): void;

Drive a possessed car toward a point or living actor. Completion fires once through onMoveCompleted.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Frame context.
`ai`	`ActorHandle`	AI controller.
`target`	`Vec3` \| `ActorHandle`<`object`>	World point or actor.
`opts`	`DriveOptions`	Speed and arrival controls.

Returns

void

Example

driveTowards(ctx, ai, { x: 0, y: 0, z: 40 }, { speed: 12 });

dropThroughPlatform()

function dropThroughPlatform(entity, seconds?): boolean;

Drop through one-way surfaces for a short, per-character interval. Only works while supported by a SoftPlatform; ordinary floors remain solid.

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	CharacterMovement capsule.
`seconds`	`number`	`0.3`	Ignore interval, default 0.3 seconds.

Returns

boolean

Whether a drop was requested.

Example

dropThroughPlatform(hero.entity);

endMatch()

function endMatch(ctx, winners?): void;

End the match; ties share victory unless explicit seats are supplied.

Parameters

Parameter	Type
`ctx`	`GameContext`
`winners?`	`number`[]

Returns

void

Example

endMatch(ctx, [0]);

endPhase()

function endPhase(ctx): void;

End the current phase; the final phase resolves the round by score.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current authority context.

Returns

void

Example

endPhase(ctx);

endRound()

function endRound(ctx, winner?): void;

Resolve a round. Omitted winner uses scores; null explicitly declares a draw.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current authority context.
`winner?`	`number` \| `null`	Team id or player seat; null declares a draw.

Returns

void

Example

endRound(ctx, 1);

equipItem()

function equipItem(
   actor, 
   slot, 
   item
): boolean;

Move one bag item into its declared equipment slot, returning old equipment to the bag. Fails without changes when the old item cannot fit after taking the new one.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`slot`	`string`	Named equipment slot.
`item`	`string`	Catalog id with a matching equipSlot.

Returns

boolean

Whether equipment was set.

Example

const changed = equipItem(actor, 'hand', 'sword');

equipped()

function equipped(actor, slot): string | undefined;

Read an equipment id, or undefined for empty, unknown slots or dead actors.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`slot`	`string`	Named equipment slot.

Returns

string | undefined

Equipped item id or undefined.

Example

const weapon = equipped(actor, 'hand');

faceTile()

function faceTile(entity, tile): void;

Turn toward a tile without stepping.

Parameters

Parameter	Type	Description
`entity`	`number`	Walker entity.
`tile`	`Readonly`<`GridTile`>	Target tile.

Returns

void

Example

faceTile(hero.entity, { x: 3, z: 0 });

faceToward()

function faceToward(entity, target): number;

Turn an entity, upright, to face another entity or a point on the ground plane.

Parameters

Parameter	Type	Description
`entity`	`number`	The entity to turn.
`target`	`number` \| `FlatPoint`	What it should face: an entity, or a point.

Returns

number

The yaw it now has.

Example

import { faceToward } from 'gameable';

declare const npc: number;
declare const hero: number;
faceToward(npc, hero); // the NPC turns to the hero

featuresOf()

function featuresOf(definition): FeatureOptions;

Normalise a game's features block.

Parameters

Parameter	Type	Description
`definition`	`GameDefinition`	The `defineGame` result.

Returns

FeatureOptions

A frozen table: feature name to its options; true becomes {}, false is dropped.

Example

import { defineGame, featuresOf } from 'gameable';

const game = defineGame({ features: { characters: true, multiplayer: { maxPlayers: 6 } } });
console.log(featuresOf(game)); // { characters: {}, multiplayer: { maxPlayers: 6 } }

findThing()

function findThing(things, words): WorldThing | null;

The thing some words name, or null.

Parameters

Parameter	Type	Description
`things`	readonly `WorldThing`[]	The world's things.
`words`	`string`	What was said, for example `"the trunk"`.

Returns

WorldThing | null

The best match, or null when nothing answers.

Example

import { findThing } from 'gameable';

const trunk = findThing(things, 'the trunk');
console.log(trunk?.label); // 'steamer trunk'

findThings()

function findThings(
   things, 
   words, 
   out?
): WorldThing[];

Every thing that answers some words, the best first.

An occasional question, not a per-step one: it splits the words asked.

Parameters

Parameter	Type	Default value	Description
`things`	readonly `WorldThing`[]	`undefined`	The world's things.
`words`	`string`	`undefined`	What was said, for example `"the trunk"` or `"walk to the round window"`.
`out`	`WorldThing`[]	`[]`	The array to fill; emptied first.

Returns

WorldThing[]

out.

Example

import { findThings, type WorldThing } from 'gameable';

const found: WorldThing[] = [];
findThings(things, 'a box', found);
console.log(found.map((thing) => thing.label)); // ['hat box', 'steamer trunk']

fireImpulse()

function fireImpulse(
   ctx, 
   actor, 
   component?
): void;

Fire a radial component once; omitting the name selects the first radial component.

Parameters

Parameter	Type
`ctx`	`GameContext`
`actor`	`ActorHandle`
`component?`	`string`

Returns

void

Example

fireImpulse(ctx, explosion, 'force');

fitBox()

function fitBox(vertices): FittedShape;

Fit the local AABB; scale must already be baked into vertices.

Parameters

Parameter	Type	Description
`vertices`	`Float32Array`	Mesh-local xyz points in metres.

Returns

FittedShape

Box half-extents and center, with identity rotation.

Example

const box = fitBox(new Float32Array([-1,-1,-1,1,1,1]));

fitCapsule()

function fitCapsule(vertices): FittedShape;

Fit a longest-bounds-axis capsule, ties X then Y then Z. Expand the radial heuristic to enclose every vertex before applying the length rule.

Parameters

Parameter	Type	Description
`vertices`	`Float32Array`	Mesh-local xyz points, with scale pre-baked.

Returns

FittedShape

Capsule radius and cylindrical half-height, with local Y rotated onto its axis.

Example

const capsule = fitCapsule(new Float32Array([0,-2,0,1,2,0,-1,2,0]));

fitKDop()

function fitKDop(vertices, count): Float32Array;

Fit 10X, 18 or 26 outward support planes and return convex-hull xyz points. No decomposition or padding is applied. Pre-bake build scale into the vertices.

Parameters

Parameter	Type	Description
`vertices`	`Float32Array`	Nonempty finite mesh-local xyz points.
`count`	`10` \| `18` \| `26`	Number of support directions; 10 means the 10X variant.

Returns

Float32Array

Packed convex hull vertices for engine convex geometry.

Example

const points = fitKDop(new Float32Array([-1,-1,-1,1,1,1]), 26);

fitSphere()

function fitSphere(vertices): FittedShape;

Choose the smaller of the incremental sphere and AABB-center sphere.

Parameters

Parameter	Type	Description
`vertices`	`Float32Array`	Mesh-local xyz points, with scale pre-baked.

Returns

FittedShape

Enclosing sphere; zero-radius meshes fail.

Example

const sphere = fitSphere(new Float32Array([-1,0,0,1,0,0]));

flyingMovement()

function flyingMovement(opts?): ActorComponent;

Fly a pawn with acceleration, braking and player-relative movement.

Parameters

Parameter	Type
`opts`	{ `acceleration?`: `number`; `deceleration?`: `number`; `maxSpeed?`: `number`; }
`opts.acceleration?`	`number`
`opts.deceleration?`	`number`
`opts.maxSpeed?`	`number`

Returns

Example

const movement = flyingMovement({ maxSpeed: 12 });

followRacingLine()

function followRacingLine(
   ctx, 
   ai, 
   line, 
   opts?
): void;

Follow a sampled spline or explicitly ordered TargetPoints; positions are captured at request time.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Frame context.
`ai`	`ActorHandle`	AI controller.
`line`	\| readonly `string`[] \| { `actor`: `string`; `component`: `string`; }	Named spline component or ordered TargetPoint names.
`opts`	`RacingLineOptions`	Line speed, lookahead and rival offset.

Returns

void

Example

followRacingLine(ctx, ai, { actor: 'track', component: 'line' }, { speed: 18, loop: true });

formationSlot()

function formationSlot(
   i, 
   n, 
   spacing, 
   yaw, 
   out
): Vec3;

Write a centred grid slot, front (+Z) row first, rotated about +Y by yaw radians. Rows contain ceil(sqrt(n)) slots; the final partial row is centred separately. Invalid indices and empty formations write zero. No allocations.

Parameters

Parameter	Type	Description
`i`	`number`	Zero-based slot index.
`n`	`number`	Number of formation members.
`spacing`	`number`	Distance between slots in metres.
`yaw`	`number`	Facing in radians about +Y.
`out`	`Vec3`	Caller-owned offset vector.

Returns

The supplied offset vector.

Example

formationSlot(0, 4, 2, 0, offset);

gameMode()

function gameMode(): 
  | ActorHandle<GameModeProps>
  | null;

The live mode, including a derived class.

Returns

| ActorHandle<GameModeProps> | null

Example

const mode = gameMode();

gameState()

function gameState(): 
  | ActorHandle<GameStateProps>
  | null;

The mode's live public state actor.

Returns

| ActorHandle<GameStateProps> | null

Example

const elapsed = gameState()?.props.elapsed;

getAttribute()

function getAttribute(actor, name): number;

Read the clamped modified value.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`name`	`string`	Declared attribute name.

Returns

number

The current modified value.

Example

const hp = getAttribute(hero, 'health');

getAttributeBase()

function getAttributeBase(actor, name): number;

Read the permanent base value.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`name`	`string`	Declared attribute name.

Returns

number

The permanent base value.

Example

const hp = getAttributeBase(hero, 'health');

getMaxEntities()

function getMaxEntities(): number;

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

Returns

number

The configured entity ceiling.

grantAbility()

function grantAbility(actor, id): boolean;

Grant a registered ability once; false means client or capacity rejection.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`id`	`string`	Registered effect or ability id.

Returns

boolean

Whether the ability is granted.

Example

grantAbility(hero, 'jump');

gridInputFromKeys()

function gridInputFromKeys(ctx, directions?): GridDirection | undefined;

Read WASD/arrows, with the newest pressed key winning. Simultaneous presses use W/up, S/down, D/right, A/left order. Call once in init to preallocate key history. Eight-way mode combines the newest horizontal and vertical keys.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	Input context.
`directions`	`4` \| `8`	`4`	Four by default; pass the component's direction count.

Returns

GridDirection | undefined

A compass direction, or undefined when no movement key is held.

Example

const dir = gridInputFromKeys(ctx); if (dir) requestGridMove(hero.entity, dir);

gridMovement()

function gridMovement(options?): ActorComponent;

Kinematic tile stepping. Use as the actor root; north is -Z. Origin is tile (0,0)'s centre. Requests made in actor ticks/systems are consumed on the following component step. A fresh hold spends turnInPlaceSeconds turning before walking; continuing steps have no delay.

Parameters

Parameter	Type	Description
`options`	`GridMovementOptions`	Tile geometry, timing, collision policy and borrowed-tile callbacks.

Returns

A kinematic capsule or box component.

Example

const root = gridMovement({ stepSeconds: 0.22, collision: 'Pawn' });

gridStateOf()

function gridStateOf(entity): Readonly<GridState>;

Read borrowed state.

Parameters

Parameter	Type	Description
`entity`	`number`	Walker entity.

Returns

Readonly<GridState>

Current state.

Example

const moving = gridStateOf(hero.entity).moving;

hasAllTags()

function hasAllTags(actor, tags): boolean;

Test all hierarchical tags; an empty list succeeds.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`tags`	readonly `string`[]	Tag queries to match.

Returns

boolean

Whether every query matches.

Example

const ready = hasAllTags(hero, ['weapon', 'state.ready']);

hasAnyTag()

function hasAnyTag(actor, tags): boolean;

Test any hierarchical tag.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`tags`	readonly `string`[]	Tag queries to match.

Returns

boolean

Whether at least one query matches.

Example

const busy = hasAnyTag(hero, ['state.stunned', 'state.dead']);

hasEffect()

function hasEffect(actor, id): boolean;

Test for at least one active effect stack.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`id`	`string`	Registered effect or ability id.

Returns

boolean

Whether any stack is active.

Example

const armored = hasEffect(hero, 'armor');

hasItem()

function hasItem(
   actor, 
   item, 
   amount?
): boolean;

Test bag contents, excluding equipment.

Parameters

Parameter	Type	Default value	Description
`actor`	`ActorHandle`	`undefined`	Owning actor.
`item`	`string`	`undefined`	Catalog id.
`amount`	`number`	`1`	Nonnegative safe integer; defaults to one.

Returns

boolean

Whether the bag holds the requested amount.

Example

if (hasItem(actor, 'key')) actor.state.unlocked = true;

hasKeys()

function hasKeys<K>(...keys): (x) => x is Record<K, unknown>;

A guard for a record with every one of keys as an own property (any value, even undefined); extra keys are allowed. Make it once, at module scope: the guard it returns allocates nothing per call.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type	Description
...`keys`	`K`[]	The keys a payload must have.

Returns

The guard.

(x) => x is Record<K, unknown>

Example

const hasItemSlot = hasKeys('item', 'slot');
const Pick = defineMessage(
  'pick',
  (p): p is { item: string; slot: number } =>
    hasItemSlot(p) && typeof p.item === 'string' && typeof p.slot === 'number',
);

hasTag()

function hasTag(actor, tag): boolean;

Query tags hierarchically: state.stunned matches state, but state does not match state.stunned.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`tag`	`string`	Exact tag or ancestor.

Returns

boolean

Whether any manual or granted tag matches.

Example

if (hasTag(hero, 'state')) hero.state.busy = true;

hitUnderCursor()

function hitUnderCursor(
   ctx, 
   out, 
   opts?
): boolean;

Raycast through the pointer and copy a hit into caller-owned storage. Query is physics.raycast's layer mask; default distance is 500 metres. This helper allocates nothing; physics.raycast's host/ABI may allocate its result. False on an unusable camera or a miss, leaving out unchanged.

Parameters

Parameter	Type
`ctx`	`GameContext`
`out`	`CursorHit`
`opts?`	{ `maxDistance?`: `number`; `query?`: `CollisionLayers`; }
`opts.maxDistance?`	`number`
`opts.query?`	`CollisionLayers`

Returns

boolean

Example

if (hitUnderCursor(ctx, hit)) console.log(hit.entity);

hostMoveQuery()

function hostMoveQuery(
   entity, 
   capsule, 
   mask?
): MoveQuery;

Adapt guest physics queries to the movement solver. Results are borrowed until the next call. The guest supplies contact points rather than penetration normals; normals point from the contact toward the closest capsule segment point, with a deterministic horizontal escape at zero distance.

Parameters

Parameter	Type	Description
`entity`	`number`	Mover entity to exclude from every probe.
`capsule`	`Capsule`	Radius and straight-section half height in metres.
`mask?`	`CollisionLayers`	Blocking layers, or all layers when omitted.

Returns

MoveQuery

Reusable query adapter.

Example

const query = hostMoveQuery(player, { radius: 0.35, halfHeight: 0.55 });

inputFor()

function inputFor(ctx, pawn): 
  | {
  touch: {
     get active(): boolean;
     get pinch(): number;
     get turn(): number;
     stick: Axis2;
  };
  get control(): Readonly<NonNullable<InputState["control"]>>;
  get focused(): boolean;
  get mods(): InputMods;
  get mouse(): MouseState;
  action: ActionState;
  axis2: Axis2;
  gamepad:   | {
     axes: ArrayLike<number>;
     buttons: number;
     connected: boolean;
     index: number;
     pressed: number;
     released: number;
   }
     | null;
  isDown: boolean;
  mouseDown: boolean;
  mousePressed: boolean;
  mouseReleased: boolean;
  pressed: boolean;
  released: boolean;
}
  | null;

The input that drives a pawn: its player's, or null for an AI's pawn or no controller.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	The game context.
`pawn`	`number` \| `ActorHandle`<`object`>	The pawn.

Returns

The player's input, read like ctx.input, or null.

Type Literal

{
  touch: {
     get active(): boolean;
     get pinch(): number;
     get turn(): number;
     stick: Axis2;
  };
  get control(): Readonly<NonNullable<InputState["control"]>>;
  get focused(): boolean;
  get mods(): InputMods;
  get mouse(): MouseState;
  action: ActionState;
  axis2: Axis2;
  gamepad:   | {
     axes: ArrayLike<number>;
     buttons: number;
     connected: boolean;
     index: number;
     pressed: number;
     released: number;
   }
     | null;
  isDown: boolean;
  mouseDown: boolean;
  mousePressed: boolean;
  mouseReleased: boolean;
  pressed: boolean;
  released: boolean;
}

touch

touch: object;

Fingers on a touch screen, as the host's touch layer packs them: the first finger is the pointer (mouse), a tap is pressed('Tap'), and the thumb sticks, the pinch and the turn are here.

touch.active

Get Signature

get active(): boolean;

Is a finger on the screen? (The touch pad is connected.)

Returns

boolean

True while any finger is down.

touch.pinch

Get Signature

get pinch(): number;

Two fingers' pinch this step, as a scale factor: over 1 the fingers moved apart (zoom in), under 1 together, exactly 1 with no pinch.

Returns

number

The scale factor.

touch.turn

Get Signature

get turn(): number;

Two fingers' turn this step, in radians, counter-clockwise on the screen positive.

Returns

number

The turn.

touch.stick()

stick(side): Axis2;

A thumb stick's push.

Parameters

Parameter	Type	Description
`side`	`"left"` \| `"right"`	The left stick (movement) or the right one (the camera).

Returns

A pooled { x, y }, -1..1, y up the screen positive. Never retain it.

control

Get Signature

get control(): Readonly<NonNullable<InputState["control"]>>;

Received page control for this frame. Owned by the SDK; read during the tick.

Returns

Readonly<NonNullable<InputState["control"]>>

The control state received with this input sequence.

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

The modifiers for this frame.

mouse

Get Signature

get mouse(): MouseState;

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

Returns

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

action()

action(name): ActionState;

Read a declared button into pooled storage. Unknown names throw.

Parameters

Parameter	Type	Description
`name`	`string`	Declared button action name.

Returns

Pooled button state; read immediately.

axis2()

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

Parameters

Parameter	Type	Default value	Description
`negX`	`string`	`undefined`	Declared axis name, or key driving x negative, e.g. `'A'`.
`posX?`	`string`	`undefined`	Key that drives x positive, for example `'D'`.
`negY?`	`string`	`undefined`	Key that drives y negative, for example `'S'`.
`posY?`	`string`	`undefined`	Key that drives y positive, for example `'W'`.
`stick?`	`StickSide`	`'left'`	Which thumb stick to add, `'left'` by default.

Returns

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.

null

Example

const move = inputFor(ctx, self)?.axis('move');

interactable()

function interactable(): ActorComponent;

Add interaction to any actor; its props include InteractableProps and its spec supplies onInteract. The actor runtime's optional onInteract hook keeps callbacks out of level JSON.

Returns

The reusable component declaration.

Example

const Terminal = defineActor('Terminal', {components: {root: scene(), use: interactable()}, props: {prompt: 'Use',range: 2,facingDegrees: 75,action: 'E',once: false,enabled: true}, onInteract(self, who, ctx) { console.log(who); }});

interactionNotice()

function interactionNotice(
   ctx, 
   seat, 
   message
): void;

Publish a short notice to one player using the preallocated interaction model.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current guest context.
`seat`	`number`	Player seat index.
`message`	`string`	Notice text.

Returns

void

Example

interactionNotice(ctx, 0, 'Find the key');

inventoryComponent()

function inventoryComponent(options): ActorComponent;

Attach a bag and named equipment to each actor. Owner indices are reused lowest first. Each distinct schema gets one library per runtime; identical schemas share it, even with different callbacks. Library storage allocates once on the first spawn of each schema; subsequent item calls allocate nothing. Equipment swaps emit bag removal/addition followed by unequipped/equipped events. Destruction and snapshot restoration are silent. Dropping world pickups is not supported.

Parameters

Parameter	Type	Description
`options`	`InventoryComponentOptions`	Bag schema and event callbacks.

Returns

A scene component with authority lifecycle hooks.

Example

import { defineActor, scene, inventoryComponent } from 'gameable';
const Chest = defineActor('Chest', {
  components: { root: scene(), bag: inventoryComponent({ slots: 8, items: [{ id: 'coin', stack: 99 }] }) },
});

isDoor()

function isDoor(actor): boolean;

Marker-based identification, including legacy Door and derived specs.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`<`object`> \| `null` \| `undefined`	Candidate actor instance.

Returns

boolean

Whether the actor carries the door marker.

Example

if (isDoor(actor)) console.log(actor.name);

isDoorOpen()

function isDoorOpen(door): boolean;

Whether the door is fully open.

Parameters

Parameter	Type	Description
`door`	`ActorHandle`	Kit or legacy door instance.

Returns

boolean

Whether the panel is fully open.

Example

if (isDoorOpen(door)) leave();

isRecord()

function isRecord(x): x is Record<string, unknown>;

A plain JSON object: not null, not an array.

Parameters

Parameter	Type	Description
`x`	`unknown`	A parsed payload.

Returns

x is Record<string, unknown>

True for an object record.

Example

const Move = defineMessage('move', (p): p is { x: number } => isRecord(p) && typeof p.x === 'number');

isSignalOn()

function isSignalOn(actor): boolean;

Read the shared actor signal contract.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`<`object`> \| `null` \| `undefined`	Signal source, or a missing actor.

Returns

boolean

Whether the signal reports on.

Example

if (isSignalOn(lever)) openDoor(ctx, door);

isSoundPlaying()

function isSoundPlaying(actor, component?): boolean;

Read playback status after the latest sound-ended events.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`component?`	`string`	Audio component name.

Returns

boolean

Whether the sound remains live.

Example

const playing = isSoundPlaying(actor);

jump()

function jump(entity): void;

Request a jump on the next movement tick; airborne requests are consumed too.

Parameters

Parameter	Type	Description
`entity`	`number`	Actor root entity.

Returns

void

Example

jump(player);

keyIndex()

function keyIndex(name): number;

Bit index for a key name, or -1 when the name is unknown. Names are case-sensitive, except that a bare letter or F-key also answers in lower case ('w', 'f1'). Allocates nothing.

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. Case-sensitive, like the aliases it covers. Allocates nothing.

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.

lastDamageInstigator()

function lastDamageInstigator(entity): number;

Parameters

Parameter	Type	Description
`entity`	`number`	An entity.

Returns

number

The instigator entity of the last hit that removed its health, or 0.

Example

const killer = lastDamageInstigator(pawn);

launchCharacter()

function launchCharacter(
   entity, 
   velocity, 
   xyOverride, 
   zOverride
): void;

Launch into falling mode, adding or replacing horizontal and vertical velocity.

Parameters

Parameter	Type	Description
`entity`	`number`	Actor root entity.
`velocity`	`Vec3`	Launch velocity in metres per second.
`xyOverride`	`boolean`	Replace horizontal (world X/Z) velocity.
`zOverride`	`boolean`	Replace vertical (world Y) velocity, the option name uses a Z-up convention.

Returns

void

Example

launchCharacter(player, { x: 2, y: 6, z: 0 }, true, true);

levelActorNames()

function levelActorNames(level): string[];

Resolve the name of every entry in a level, in file order.

Parameters

Parameter	Type	Description
`level`	`LevelFile`	The level document.

Returns

string[]

One name per entry: the written one, or the automatic one.

Example

const names = levelActorNames({ format: 1, actors: [{ class: 'Door', position: [0, 0, 0] }] }); // ['Door1']

levelDocumentOf()

function levelDocumentOf(level): string;

A level document as a file: two-space indent, a number or string list on one line, a newline at the end, the way the templates' level files are written. A save by hand and a save by a worker then look the same.

Parameters

Parameter	Type	Description
`level`	`LevelFile`	The document.

Returns

string

The file's text.

Example

const text = levelDocumentOf(applyLevelEdits(level, edits));

limitWalk()

function limitWalk(
   walk, 
   x, 
   z, 
   velocity
): void;

Keep a walker inside the world's walk limit: change the velocity it asked for.

A room's walls do the stopping (inside-collision: nothing changes here). An open place has a circle with a soft edge: from fadeFrom outward the speed away from the middle falls off, at radius it is none, and past it the walker is eased back in. Walking along the edge or back in is never slowed.

Parameters

Parameter	Type	Description
`walk`	`WorldWalk`	The world's walk limit.
`x`	`number`	Where the walker is, x.
`z`	`number`	Where the walker is, z.
`velocity`	`Vec3`	The velocity asked for; `x` and `z` are changed in place.

Returns

void

Nothing.

Example

import { limitWalk } from 'gameable';

const velocity = { x: 2, y: 0, z: 0 };
limitWalk(list.walk, 12.5, 0, velocity);
console.log(velocity.x); // 1: half way through the soft edge of an 11 to 14 metre limit

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 'gameable';

loadAsset('boss-arena', 10);

loadLevel()

function loadLevel(
   ctx, 
   level, 
   options?
): object;

Spawn in file order, then attach using local position and rotation. Validates before spawning. Every actor gets a source naming the level and its entry, and a name (the entry's, or the automatic one), so an editor can list it and write it back.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current guest context.
`level`	`LevelFile`	Level document.
`options`	`LoadLevelOptions`	The level's name for the actors' sources.

Returns

object

Handles in file order and a dictionary of actors by name.

actors

actors: ActorHandle<object>[];

named

named: Record<string, ActorHandle>;

Example

const { named } = loadLevel(ctx, { format: 1, actors: [{ class: 'Door', name: 'gate', position: [0, 0, 8] }] });

lockDoor()

function lockDoor(door, item): void;

Lock future opening requests with an inventory item.

Parameters

Parameter	Type	Description
`door`	`ActorHandle`<`DoorCoreProps`>	Kit door instance.
`item`	`string`	Required inventory item id.

Returns

void

Example

lockDoor(door, 'key');

lowerCollision()

function lowerCollision(input): LoweredCollision;

Map collision policy onto engine body fields. Prefab spawn carries the overlap mask to a companion sensor when both block and overlap channels are present.

Parameters

Parameter	Type	Description
`input`	\| `CollisionSetup` \| `"NoCollision"` \| `"BlockAll"` \| `"OverlapAll"` \| `"BlockAllDynamic"` \| `"OverlapAllDynamic"` \| `"IgnoreOnlyPawn"` \| `"OverlapOnlyPawn"` \| `"Pawn"` \| `"Spectator"` \| `"CharacterMesh"` \| `"PhysicsActor"` \| `"Destructible"` \| `"InvisibleWall"` \| `"InvisibleWallDynamic"` \| `"Trigger"` \| `"Ragdoll"` \| `"Vehicle"` \| `"UI"`	Named profile or custom setup.

Returns

LoweredCollision

Body fields, overlap mask and query-only metadata.

Example

const fields = lowerCollision('BlockAll');

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 'gameable';

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

matchState()

function matchState(): MatchState;

Current match lifecycle, or waiting before a mode exists.

Returns

MatchState

Example

const state = matchState();

matchSummary()

function matchSummary(): Readonly<MatchSummary>;

Borrow the current match summary for composition into the game's own HUD. The object and its rows are reused: copy them if a historical value is needed.

Returns

Readonly<MatchSummary>

Example

ctx.hud.set({ score: 10, match: matchSummary() });

maxEntities()

function maxEntities(): number;

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

Returns

number

The configured maximum.

Example

import { maxEntities } from 'gameable';

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

mergeTileColliders()

function mergeTileColliders(cells, cellSize?): TileCollisionBox[];

Greedily merge identical-height cells, scanning z then x and extending x first. Duplicate cells collapse; conflicting duplicate heights throw. This deterministic greedy cover reduces seams but is not a globally minimum rectangle partition. Cell (x,z) covers [x,x+1] by [z,z+1], scaled by cellSize.

Parameters

Parameter	Type	Default value	Description
`cells`	readonly `CollisionCell`[]	`undefined`	Occupied integer grid coordinates and positive heights.
`cellSize`	`number`	`1`	Horizontal grid spacing in metres, default one.

Returns

TileCollisionBox[]

Disjoint boxes preserving occupied volume.

Example

const boxes = mergeTileColliders([{ x: 0, z: 0, height: 1 }, { x: 1, z: 0, height: 1 }]);

mesh()

function mesh(assetName, opts?): ActorComponent;

A renderable addressed by its manifest id.

Parameters

Parameter	Type	Description
`assetName`	`string`	Manifest asset id.
`opts`	`ShapeOptions`	Local transform or spawn options.

Returns

The mesh component declaration.

Example

import { mesh } from 'gameable';
const look = mesh('crate');
const house = mesh('thing.house', { fit: 'box' }); // collides as drawn

moduleCatalog()

function moduleCatalog(): ModuleCatalog;

Describe loaded gameplay factories as detached JSON data.

Returns

ModuleCatalog

Gameplay module catalog.

Example

const json = JSON.stringify(moduleCatalog());

moveItem()

function moveItem(
   actor, 
   from, 
   to
): void;

Merge matching stacks or swap bag slots; emits no item events.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`from`	`number`	Source bag slot.
`to`	`number`	Destination bag slot.

Returns

void

Example

moveItem(actor, 0, 1);

movementOf()

function movementOf(entity): 
  | {
  floor: FloorResult;
  isFalling: boolean;
  isMovingOnGround: boolean;
  mode: "walking" | "falling";
  velocity: Readonly<Vec3>;
}
  | undefined;

Read borrowed solver state, or undefined for an entity without this component.

Parameters

Parameter	Type	Description
`entity`	`number`	Actor root entity.

Returns

| { floor: FloorResult; isFalling: boolean; isMovingOnGround: boolean; mode: "walking" | "falling"; velocity: Readonly<Vec3>; } | undefined

Current movement mode, velocity and floor.

Example

const airborne = movementOf(player)?.isFalling;

moverCarry()

function moverCarry(
   mover, 
   contact, 
   previousX, 
   currentX, 
   x, 
   y, 
   z, 
   grounded
): number | undefined;

Return supported X displacement using the authority's strict foot bounds.

Parameters

Parameter	Type	Description
`mover`	{ `bounds`: readonly `number`[]; `carry`: `boolean`; `collider`: { `dims`: readonly `number`[]; `rotation`: readonly `number`[]; `shape`: `"box"` \| `"capsule"`; }; `id`: `string`; `knock`: `"none"` \| `"rotating-tangent"` \| `"toward-center"`; `motion`: \| { `angularRate`: `number`; `kind`: `"rotate-y"`; } \| { `amplitude`: `number`; `angularRate`: `number`; `kind`: `"sine-x"`; `phase`: `number`; }; `position`: readonly `number`[]; }	Authored platform bounds and base position.
`mover.bounds`	readonly `number`[]	-
`mover.carry`	`boolean`	-
`mover.collider`	{ `dims`: readonly `number`[]; `rotation`: readonly `number`[]; `shape`: `"box"` \| `"capsule"`; }	-
`mover.collider.dims`	readonly `number`[]	-
`mover.collider.rotation`	readonly `number`[]	-
`mover.collider.shape`	`"box"` \| `"capsule"`	-
`mover.id`	`string`	-
`mover.knock`	`"none"` \| `"rotating-tangent"` \| `"toward-center"`	-
`mover.motion`	\| { `angularRate`: `number`; `kind`: `"rotate-y"`; } \| { `amplitude`: `number`; `angularRate`: `number`; `kind`: `"sine-x"`; `phase`: `number`; }	-
`mover.position`	readonly `number`[]	-
`contact`	{ `carryTolerance`: `number`; `foot`: `number`; }	Foot offset and support tolerance.
`contact.carryTolerance`	`number`	-
`contact.foot`	`number`	-
`previousX`	`number`	Last consumed replicated or authority X.
`currentX`	`number`	Current platform X.
`x`	`number`	Player centre X.
`y`	`number`	Player centre Y.
`z`	`number`	Player centre Z.
`grounded`	`boolean`	Whether the character has walkable ground contact.

Returns

number | undefined

X displacement, or undefined for unsupported feet.

Example

import { moverCarry, type MoverModuleOptions } from 'gameable';
const supported = (mover: MoverModuleOptions['movers'][number], contact: MoverModuleOptions['contact']) =>
  moverCarry(mover, contact, 0, 0.1, 0, 3.15, -34.5, true);
console.log(supported);

moverPose()

function moverPose(
   mover, 
   time, 
   out
): void;

Compute an authority mover pose into reusable storage.

Parameters

Parameter	Type	Description
`mover`	{ `bounds`: readonly `number`[]; `carry`: `boolean`; `collider`: { `dims`: readonly `number`[]; `rotation`: readonly `number`[]; `shape`: `"box"` \| `"capsule"`; }; `id`: `string`; `knock`: `"none"` \| `"rotating-tangent"` \| `"toward-center"`; `motion`: \| { `angularRate`: `number`; `kind`: `"rotate-y"`; } \| { `amplitude`: `number`; `angularRate`: `number`; `kind`: `"sine-x"`; `phase`: `number`; }; `position`: readonly `number`[]; }	Authored motion and base position.
`mover.bounds`	readonly `number`[]	-
`mover.carry`	`boolean`	-
`mover.collider`	{ `dims`: readonly `number`[]; `rotation`: readonly `number`[]; `shape`: `"box"` \| `"capsule"`; }	-
`mover.collider.dims`	readonly `number`[]	-
`mover.collider.rotation`	readonly `number`[]	-
`mover.collider.shape`	`"box"` \| `"capsule"`	-
`mover.id`	`string`	-
`mover.knock`	`"none"` \| `"rotating-tangent"` \| `"toward-center"`	-
`mover.motion`	\| { `angularRate`: `number`; `kind`: `"rotate-y"`; } \| { `amplitude`: `number`; `angularRate`: `number`; `kind`: `"sine-x"`; `phase`: `number`; }	-
`mover.position`	readonly `number`[]	-
`time`	`number`	Authority elapsed seconds.
`out`	{ `x`: `number`; `y`: `number`; `yaw`: `number`; `z`: `number`; }	Caller-owned pose storage.
`out.x`	`number`	-
`out.y`	`number`	-
`out.yaw`	`number`	-
`out.z`	`number`	-

Returns

void

Example

import { moverPose, type MoverModuleOptions } from 'gameable';
const sample = (mover: MoverModuleOptions['movers'][number]) => {
  const pose = { x: 0, y: 0, z: 0, yaw: 0 };
  moverPose(mover, 1, pose);
  return pose;
};
console.log(sample);

moveState()

function moveState(pawn): "failed" | "arrived" | "moving" | "idle";

Read the current pawn's order; unknown or destroyed pawns are idle.

Parameters

Parameter	Type	Description
`pawn`	`number`	Character actor root entity.

Returns

"failed" | "arrived" | "moving" | "idle"

Current walking request status.

Example

const arrived = moveState(player) === 'arrived';

moveStatus()

function moveStatus(ai): "moving" | "idle";

Read the controller's current movement status.

Parameters

Parameter	Type
`ai`	`ActorHandle`

Returns

"moving" | "idle"

Example

const moving = moveStatus(ai) === 'moving';

moveThing()

function moveThing(
   thing, 
   position, 
   rotation, 
   moved?
): void;

Put a thing somewhere new: its position, its turn, and its box round both.

The host's loader and the guest's list both call this, so the box a game reads is the same on either side.

Parameters

Parameter	Type	Default value	Description
`thing`	`WorldThing`	`undefined`	The thing; changed in place.
`position`	`Vec3`	`undefined`	The middle of its base.
`rotation`	`Quat`	`undefined`	How it is turned.
`moved`	`boolean`	`true`	Whether this counts as having moved from where it was made.

Returns

void

Nothing.

Example

import { moveThing } from 'gameable';

moveThing(thing, { x: 1, y: 0, z: -2 }, { x: 0, y: 0, z: 0, w: 1 });
console.log(thing.min, thing.max); // the box where it is now

moveTo()

function moveTo(
   ctx, 
   ai, 
   target, 
   opts?
): void;

Begin a navigation move (straight-line when no bounds exist), aborting an existing request first.

Parameters

Parameter	Type
`ctx`	`GameContext`
`ai`	`ActorHandle`
`target`	`Vec3` \| `ActorHandle`<`object`>
`opts?`	{ `acceptanceRadius?`: `number`; }
`opts.acceptanceRadius?`	`number`

Returns

void

Example

moveTo(ctx, ai, { x: 5, y: 0, z: 2 });

navigationOf()

function navigationOf(): NavGrid | null;

The shared grid covers the axis-aligned union of bounds volumes; the first supplies tuning. Returns null until the first bounds volume steps. Rotations do not rotate the grid.

Returns

NavGrid | null

Example

const grid = navigationOf();

navigationReady()

function navigationReady(): boolean;

Whether flat ground or a successful physics bake is available.

Returns

boolean

Example

if (navigationReady()) moveTo(ctx, ai, goal);

onTrigger()

function onTrigger(
   ctx, 
   name, 
   handlers
): () => void;

Subscribe during init or a system to an instance name. Returns an unsubscribe function. Registration belongs to the current guest; callbacks are code and are not snapshotted.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`name`	`string`	Trigger instance name.
`handlers`	`TriggerHandlers`	Entry and exit callbacks.

Returns

Unsubscribe function.

() => void

Example

onTrigger(ctx, 'gate', { enter: (other, c) => c.hud.set({ gate: true }) });

openDoor()

function openDoor(ctx, door): void;

Request opening; a locked door must be unlocked first.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current guest context.
`door`	`ActorHandle`<`DoorCoreProps`>	Kit door instance.

Returns

void

Example

openDoor(ctx, door);

orderMove()

function orderMove(
   ctx, 
   pawns, 
   target, 
   opts?
): void;

Order selected pawns to a world-aligned grid around target (default spacing 1.5m). Targets are copied into each pawn's request; the supplied selection is not retained.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current game context.
`pawns`	readonly `number`[]	Selected character actor root entities.
`target`	`Vec3`	World-space formation centre.
`opts?`	{ `acceptanceRadius?`: `number`; `spacing?`: `number`; }	Formation and arrival options.
`opts.acceptanceRadius?`	`number`	Arrival distance in metres (default 0.1).
`opts.spacing?`	`number`	Distance between slots in metres (default 1.5).

Returns

void

Example

orderMove(ctx, selected.entities, goal, { spacing: 2 });

particleEffect()

function particleEffect(preset, opts?): ActorComponent;

Attach a persistent built-in preset to this component's entity on its first step. The game must declare features: { vfx: true }.

Parameters

Parameter	Type	Description
`preset`	`VfxPreset`	Built-in particle preset.
`opts`	`ParticleEffectOptions`	Emitter and attachment overrides.

Returns

Scene component owning the emitter handle.

Example

const flame = particleEffect('fire', { offset: [0, 1, 0] });

pathLength()

function pathLength(path, count): number;

Total three-dimensional distance of count packed XYZ points.

Parameters

Parameter	Type	Description
`path`	`Float32Array`	Packed XYZ path buffer.
`count`	`number`	Number of points to measure.

Returns

number

Total segment length in metres.

Example

const length = pathLength(new Float32Array([0, 0, 0, 3, 0, 4]), 2);

pawnOf()

function pawnOf(controller): number;

Parameters

Parameter	Type	Description
`controller`	`ActorHandle`	A controller actor.

Returns

number

The entity it possesses, or 0.

Example

const pawn = pawnOf(controller);

pawnVelocity()

function pawnVelocity(actor): Readonly<Vec3>;

Read the component's saved velocity, or zero before initialization.

Parameters

Parameter	Type
`actor`	`ActorHandle`

Returns

Readonly<Vec3>

Example

const velocity = pawnVelocity(pawn);

peekSnapshotHeader()

function peekSnapshotHeader(state): SnapshotPeek;

Read only the JSON header of a snapshot, without restoring anything: the page's editor lists the guest's actors this way (user.actors.rows), since actor names, classes and props live in the guest.

Parameters

Parameter	Type	Description
`state`	`ArrayLike`<`number`>	The bytes `snapshot` returned.

Returns

SnapshotPeek

The header's frame, elapsed time, player and folded game state.

Throws

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

Example

const { user } = peekSnapshotHeader(sandbox.snapshot());

physicsJoint()

function physicsJoint(opts): ActorComponent;

Join named actor roots, or this actor's root to the world when names are empty. Creation is attempted once on the first authority step. Snapshots retain the joint ID and attempted flag, just as ECS retains body IDs: guest restore rebinds body handles and restores joint-kind bookkeeping, without emitting body/joint creation commands. Restore the matching host physics world separately; this component never duplicates it.

Parameters

Parameter	Type	Description
`opts`	`PhysicsJointOptions`	Joint and local transform settings.

Returns

Example

const hinge = physicsJoint({ kind: 'hinge', actorA: 'door', min: -90, max: 90 });

physicsVolumeAt()

function physicsVolumeAt(_ctx, entity): ActorHandle<object & object> | null;

Find the highest-priority volume containing an entity's root point.

Parameters

Parameter	Type	Description
`_ctx`	`GameContext`	Current context.
`entity`	`number`	Entity to test; need not be an overlap watcher.

Returns

ActorHandle<object & object> | null

Volume handle or null. Results use current transforms, not last frame's events.

Example

const water = physicsVolumeAt(ctx, ctx.player)?.props.water ?? false;

playAmbientSound()

function playAmbientSound(ctx, actor): number;

Play once, retaining the legacy helper's idempotence.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`actor`	`ActorHandle`<`AmbientProps`>	Ambient actor.

Returns

number

The live sound id, or zero.

Example

playAmbientSound(ctx, ambient);

playerControllerOf()

function playerControllerOf(seat): ActorHandle<object> | null;

The logged-in seat's controller.

Parameters

Parameter	Type
`seat`	`number`

Returns

ActorHandle<object> | null

Example

const controller = playerControllerOf(0);

playerStateOf()

function playerStateOf(seat): 
  | ActorHandle<PlayerStateProps>
  | null;

The logged-in seat's statistics.

Parameters

Parameter	Type
`seat`	`number`

Returns

| ActorHandle<PlayerStateProps> | null

Example

const score = playerStateOf(0)?.props.score;

playSound()

function playSound(
   ctx, 
   actor, 
   component?
): void;

Restart a sound, selecting the first audio component by default.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`actor`	`ActorHandle`	Owning actor.
`component?`	`string`	Audio component name.

Returns

void

Example

playSound(ctx, actor);

pointAlongPath()

function pointAlongPath(
   path, 
   count, 
   d, 
   out
): Vec3;

Write the point at clamped distance d; an empty path writes the origin.

Parameters

Parameter	Type	Description
`path`	`Float32Array`	Packed XYZ path buffer.
`count`	`number`	Number of path points.
`d`	`number`	Distance in metres from the first point.
`out`	`Vec3`	Caller-owned result vector.

Returns

PrefabDef & PlaceholderSpec

The supplied result vector.

Example

pointAlongPath(path, count, 2, marker);

possess()

function possess(
   ctx, 
   controller, 
   pawn
): void;

Make a controller drive a pawn. Any pawn it drove, and any controller that drove this pawn, let go first. A player's controller moves that player's control to the pawn.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	The game context.
`controller`	`ActorHandle`	The controller actor.
`pawn`	`number` \| `ActorHandle`<`object`>	The pawn: an entity (a `definition.player` body works) or an actor.

Returns

void

Example

possess(ctx, controller, spawnActor(ctx, FlyingPawn, { position }));

prefab()

function prefab(spec): PrefabDef & PlaceholderSpec;

Declare a prefab.

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

Parameters

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

Returns

The prefab, ready to spawn.

Example

import { prefab } from 'gameable';

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

previewPath()

function previewPath(
   _ctx, 
   from, 
   to, 
   out, 
   result, 
   opts?
): PathPreview;

Query navigation into caller-owned storage, or a straight segment without bounds. Unready navigation, unreachable goals and truncated paths report reachable=false. Budgets are metres (negative budgets clamp to zero); no query allocations.

Parameters

Parameter	Type	Description
`_ctx`	`GameContext`	Current game context.
`from`	`Vec3`	World-space starting point.
`to`	`Vec3`	World-space destination.
`out`	`Float32Array`	Caller-owned packed XYZ path storage.
`result`	`PathPreview`	Caller-owned preview result.
`opts?`	{ `budget?`: `number`; }	Preview options.
`opts.budget?`	`number`	Movement budget in metres (default Infinity).

Returns

PathPreview

The supplied preview result.

Example

previewPath(ctx, start, goal, path, result, { budget: 5 });

projectileMovement()

function projectileMovement(source, onHit?): ActorComponent;

Sweep a ray along each fixed-step displacement; ignores its own body and the owner entity (or itself when unowned). Ray results allocate in the host API.

Parameters

Parameter	Type	Description
`source`	\| `ProjectileOptions` \| ((`actor`) => `ProjectileOptions`)	Static options or an allocation-free per-actor selector.
`onHit?`	(`self`, `hit`, `ctx`, `stopped`) => `void`	Optional reusable hit callback.

Returns

The projectile integration component.

Example

const flight = projectileMovement({ speed: 30, gravityScale: 0, bounces: 0 });

projectToScreen()

function projectToScreen(
   camera, 
   viewport, 
   point, 
   out
): boolean;

Project a world point without allocation. Depth is distance along the view axis. Returns false for an unusable camera/point or a perspective point on the eye plane; visible is false on failure, behind the camera, or outside the viewport. Uses the same arm approximation and orthographic size as rayFromCamera.

Parameters

Parameter	Type
`camera`	`CameraState`
`viewport`	`Viewport`
`point`	`Vec3`
`out`	`ScreenPoint`

Returns

boolean

Example

projectToScreen(camera.state, view, worldPoint, screenPoint);

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.

radialForce()

function radialForce(opts?): ActorComponent;

Add outward impulses and optional continuous force to an actor.

Parameters

Parameter	Type
`opts`	`RadialForceOptions`

Returns

Example

const force = radialForce({ radius: 5, forceStrength: 10 });

rayFromCamera()

function rayFromCamera(
   camera, 
   viewport, 
   x, 
   y, 
   out
): boolean;

Ray through a top-left-origin screen point (y down), without allocation. Third-person follow uses the unshortened arm; host collision can move the real eye. Orthographic half height is armLength, independent of fovYDeg: the host currently defines no orthographic frustum. Invalid cameras/coordinates leave out unchanged.

Parameters

Parameter	Type
`camera`	`CameraState`
`viewport`	`Viewport`
`x`	`number`
`y`	`number`
`out`	`ScreenRay`

Returns

boolean

Example

rayFromCamera(camera.state, { width: 800, height: 600 }, 400, 300, ray);

rayToGround()

function rayToGround(
   ray, 
   planeY, 
   out
): boolean;

Intersect a forward ray with y = planeY. Parallel rays and intersections behind the origin return false and leave out unchanged.

Parameters

Parameter	Type
`ray`	`ScreenRay`
`planeY`	`number`
`out`	`Vec3`

Returns

boolean

Example

if (rayToGround(ray, 0, destination)) console.log(destination);

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.

readWorldList()

function readWorldList(text): WorldList;

Read the list a world-event of kind loaded carries.

The world facade does this for a game; the function is here for a host, a test, or a tool that holds the same text.

Parameters

Parameter	Type	Description
`text`	`string`	The event's `text`: the list as JSON.

Returns

WorldList

The list.

Throws

When the text is not a world list, or is of a newer format.

Example

import { readWorldList } from 'gameable';

const list = readWorldList(event.val.text);
console.log(list.name, list.things.length);

registerActorPart()

function registerActorPart(name, part): void;

Parameters

Parameter	Type	Description
`name`	`string`	Unique guest-local part key.
`part`	`GameplayPart`	Snapshot lifecycle implementation.

Returns

void

Example

registerActorPart('inventory', bags);

removeEffect()

function removeEffect(actor, id): void;

Remove every stack with this id and emit one expiry per stack.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`id`	`string`	Registered effect or ability id.

Returns

void

Example

removeEffect(hero, 'armor');

removeItem()

function removeItem(
   actor, 
   item, 
   amount?
): boolean;

Remove atomically from highest bag slots; equipment is excluded.

Parameters

Parameter	Type	Default value	Description
`actor`	`ActorHandle`	`undefined`	Owning actor.
`item`	`string`	`undefined`	Catalog id.
`amount`	`number`	`1`	Nonnegative safe integer; defaults to one.

Returns

boolean

Whether the entire amount was removed.

Example

const removed = removeItem(actor, 'coin', 2);

removeTag()

function removeTag(actor, tag): void;

Remove only the exact manual tag; effects and abilities retain their own grants.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`tag`	`string`	Exact manual tag or hierarchical query.

Returns

void

Example

removeTag(hero, 'state.ready');

reportNoise()

function reportNoise(
   ctx, 
   location, 
   loudness, 
   instigator?
): void;

Report an authority noise event. Listeners consume it on their next sensing update; records more than one fixed frame old expire. The location is copied. Inbox slots are reused after their high-water mark.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	Fixed-step context.
`location`	`Vec3`	`undefined`	World position in metres.
`loudness`	`number`	`undefined`	Nonnegative distance multiplier.
`instigator`	`number`	`0`	Source pawn entity, or zero when unspecified.

Returns

void

Example

reportNoise(ctx, self.position, 1, self.entity);

requestGridMove()

function requestGridMove(
   entity, 
   dir, 
   run?
): void;

Request this tick's direction; repeat while held, from an actor tick or system.

Parameters

Parameter	Type	Default value	Description
`entity`	`number`	`undefined`	Walker entity.
`dir`	`GridDirection`	`undefined`	Compass direction.
`run`	`boolean`	`false`	Use the run multiplier.

Returns

void

Example

requestGridMove(hero.entity, 'east', true);

resetAbilitiesRegistry()

function resetAbilitiesRegistry(): void;

Clear module declarations and runtime definition caches for isolated tests. Existing active slots keep their serialized definitions until expiry.

Returns

void

Example

resetAbilitiesRegistry();

resetActorRegistry()

function resetActorRegistry(): void;

Clear actor declarations for isolated tests.

Returns

void

Example

resetActorRegistry();

resetDataTableRegistry()

function resetDataTableRegistry(): void;

Clear content declarations between isolated runtimes/tests, matching resetActorRegistry. Existing table references stay immutable but are no longer registered.

Returns

void

Example

resetDataTableRegistry();

resetPrefabRegistry()

function resetPrefabRegistry(): void;

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

Returns

void

Nothing.

resetVehicle()

function resetVehicle(
   ctx, 
   pawn, 
   position, 
   yaw
): void;

Teleport, clear handling/motion/input and snap the chase arm. Yaw is radians.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Context.
`pawn`	`ActorHandle`	Vehicle pawn.
`position`	`Vec3`	World position.
`yaw`	`number`	Heading.

Returns

void

Example

resetVehicle(ctx, pawn, { x: 0, y: 1, z: 0 }, 0);

resolveRow()

function resolveRow<Row>(handle): FrozenData<Row> | undefined;

Resolve a reference without allocating; missing tables or rows return undefined.

Type Parameters

Type Parameter	Default type
`Row` extends `object`	`Record`<`string`, `unknown`>

Parameters

Parameter	Type	Description
`handle`	`DataRowHandle`	A table/row reference, possibly restored from JSON.

Returns

FrozenData<Row> | undefined

The frozen row, or undefined.

Example

const potion = resolveRow<{ cost: number }>(rowHandle('Items', 'potion'));

respawnPlayer()

function respawnPlayer(
   ctx, 
   entity, 
   options?
): void;

Teleport a player to its checkpoint or chosen PlayerStart, clear velocity and reset facing. An explicit tag selects a PlayerStart instead of the checkpoint. No starts probes the ground under the origin.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	Current context.
`entity`	`number`	`undefined`	Player entity.
`options`	{ `tag?`: `string`; }	`EMPTY_OPTIONS`	Optional preferred marker tag.
`options.tag?`	`string`	`undefined`	Preferred PlayerStart tag, overriding a checkpoint.

Returns

void

Example

respawnPlayer(ctx, ctx.player, { tag: 'red' });

responseBetween()

function responseBetween(a, b): CollisionResponse;

Resolve the symmetric minimum response. Disabled components always ignore.

Parameters

Parameter	Type	Description
`a`	`CollisionSetup`	First component.
`b`	`CollisionSetup`	Second component.

Returns

CollisionResponse

The weaker response.

Example

responseBetween(collisionProfile('Pawn'), collisionProfile('Trigger')); // overlap

restartPlayer()

function restartPlayer(ctx, seat): void;

Respawn the existing body at a PlayerStart and restore full health.

Parameters

Parameter	Type
`ctx`	`GameContext`
`seat`	`number`

Returns

void

Example

restartPlayer(ctx, 0);

roomSeats()

function roomSeats(definition): number | undefined;

The seats a game declares: features.multiplayer.maxPlayers. Seats are ids 0..seats - 1. The guest makes exactly that many player slots and ignores (with one warning) a join or input past them; a room built by createEngineRoomGame refuses the next joiner with full. Both read this function, so the two cannot disagree.

Parameters

Parameter	Type	Description
`definition`	`GameDefinition`	The `defineGame` result.

Returns

number | undefined

The seat count, DEFAULT_ROOM_SEATS for multiplayer: true, or undefined when the game does not declare features.multiplayer.

Throws

When maxPlayers is not a whole number from 1 to 4097.

Example

import { defineGame, roomSeats } from 'gameable';

const game = defineGame({ features: { multiplayer: { maxPlayers: 6 } } });
roomSeats(game); // 6: seats 0 to 5

roomSendHz()

function roomSendHz(definition): number;

The rows rate a game declares, checked: features.multiplayer.sendHz, from 1 to 60 per second (60 is the simulation rate, so more would repeat rows).

Parameters

Parameter	Type	Description
`definition`	`GameDefinition`	The `defineGame` result.

Returns

number

The declared rate, or 20 when none is declared.

Throws

When sendHz is declared but is not a number from 1 to 60.

Example

import { defineGame, roomSendHz } from 'gameable';

roomSendHz(defineGame({ features: { multiplayer: { sendHz: 10 } } })); // 10
roomSendHz(defineGame({ features: { multiplayer: true } })); // 20

rotatingMovement()

function rotatingMovement(source): ActorComponent;

Rotate the root about its local axes each authority step. Rates are degrees/second.

Parameters

Parameter	Type	Description
`source`	\| { `degreesPerSecond`: readonly [`number`, `number`, `number`]; } \| ((`actor`) => `object`)	Static degrees-per-second rates or an allocation-free per-actor selector.

Returns

The reusable rotation component.

Example

const spin = rotatingMovement({ degreesPerSecond: [0, 90, 0] });

rowHandle()

function rowHandle(table, key): DataRowHandle;

Make a JSON-safe reference. Resolution is deferred so declarations may be ordered freely.

Parameters

Parameter	Type	Description
`table`	`string`	Target table name.
`key`	`string`	Target row key.

Returns

DataRowHandle

A frozen reference.

Example

const potion = rowHandle('Items', 'potion');

runBehaviorTree()

function runBehaviorTree(
   ctx, 
   ai, 
   tree
): void;

Tick a tree for the possessed pawn after controller movement on authority steps. Trees are runtime resources; calling again replaces and resets the previous tree. Restoring stops the tree because BehaviorTree has no snapshot API. The game must run it again after restore, for example from the AI's restoreState hook or game code.

Parameters

Parameter	Type
`ctx`	`GameContext`
`ai`	`ActorHandle`
`tree`	`BehaviorTree`<`GameContext`>

Returns

void

Example

runBehaviorTree(ctx, ai, createBehaviorTree(bt.wait(1)));

sameTeam()

function sameTeam(a, b): boolean;

Compare assigned teams; unassigned players are never teammates.

Parameters

Parameter	Type	Description
`a`	`number`	First player seat.
`b`	`number`	Second player seat.

Returns

boolean

Whether both players share an assigned team.

Example

const friendly = sameTeam(0, 1);

scene()

function scene(opts?): ActorComponent;

A transform without rendering or collision.

Parameters

Parameter	Type	Description
`opts`	`ComponentOptions`	Local transform or spawn options.

Returns

The component declaration.

Example

import { scene } from 'gameable';
const root = scene();

screenRay()

function screenRay(
   ctx, 
   x, 
   y, 
   out
): boolean;

Ray through a screen point using this frame's camera and guest viewport.

Parameters

Parameter	Type
`ctx`	`GameContext`
`x`	`number`
`y`	`number`
`out`	`ScreenRay`

Returns

boolean

Example

screenRay(ctx, ctx.input.mouse.x, ctx.input.mouse.y, ray);

seatOf()

function seatOf(controller): number;

Parameters

Parameter	Type	Description
`controller`	`ActorHandle`	A controller actor.

Returns

number

Its player's seat, or NO_SEAT for an AI controller.

Example

const seat = seatOf(controller);

secondsToSteps()

function secondsToSteps(seconds, dt): number;

How many fixed steps last seconds: rounded to the nearest step, at least one.

Parameters

Parameter	Type	Description
`seconds`	`number`	The duration in simulated seconds. Zero or less is one step.
`dt`	`number`	The fixed timestep, `ctx.dt`.

Returns

number

A whole number of steps, at least 1.

Example

import { secondsToSteps } from 'gameable';
console.log(secondsToSteps(0.5, 1 / 60)); // 30

sectionDistance()

function sectionDistance(point, line): number;

Clamped arc progress on a section's polyline, never another section of the track.

Parameters

Parameter	Type	Description
`point`	`CircuitPoint`	Current position.
`line`	readonly `CircuitPoint`[]	Ordered section vertices, including both gate centres.

Returns

number

Arc distance at the closest section point; equal distances prefer earlier arc.

Example

console.log(sectionDistance([0,0,3], [[0,0,0],[0,0,10]]));

senses()

function senses(opts?): ActorComponent;

Sense player pawns, optionally all possessed pawns, from component-local +Z. Callbacks live on the component so replacing actor hooks preserves sensing. Timers and noise inboxes are JSON-safe actor state. No external handles are owned.

Parameters

Parameter	Type	Description
`opts`	`SensesOptions`	Transform, metre/degree/second tuning and callbacks.

Returns

Example

const eyes = senses({ onSeePawn(self, pawn, ctx) { self.state.target = pawn; } });

setAttributeBase()

function setAttributeBase(
   actor, 
   name, 
   value
): void;

Set the clamped permanent base; notifications settle at the next component step.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor handle.
`name`	`string`	Declared attribute name.
`value`	`number`	Proposed numeric value.

Returns

void

Example

setAttributeBase(hero, 'health', 50);

setConstraintMotor()

function setConstraintMotor(
   ctx, 
   actor, 
   motor, 
   component?
): void;

Set a live joint's motor using facade units (degrees or metres).

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Game context.
`actor`	`ActorHandle`	Owning actor.
`motor`	{ `maxForce?`: `number`; `mode`: `MotorMode`; `target`: `number`; }	Motor mode, target and optional force cap.
`motor.maxForce?`	`number`	-
`motor.mode?`	`MotorMode`	-
`motor.target?`	`number`	-
`component?`	`string`	Component name; defaults to the first constraint.

Returns

void

Example

setConstraintMotor(ctx, door, { mode: 'position', target: 90 });

setDesiredRotation()

function setDesiredRotation(entity, yaw): void;

Hold a world yaw independently of velocity when orientRotationToMovement is false. The hold persists until cleared with undefined; rotationRate limits the capsule turn.

Parameters

Parameter	Type	Description
`entity`	`number`	Actor root entity.
`yaw`	`number` \| `undefined`	Held yaw in radians about +Y, or undefined to release it.

Returns

void

Example

setDesiredRotation(player, Math.PI / 2);

setFocus()

function setFocus(
   _ctx, 
   ai, 
   target
): void;

Turn toward a point or living actor; null clears the focus.

Parameters

Parameter	Type
`_ctx`	`GameContext`
`ai`	`ActorHandle`
`target`	`Vec3` \| `ActorHandle`<`object`> \| `null`

Returns

void

Example

setFocus(ctx, ai, target);

setMovementWish()

function setMovementWish(
   actor, 
   x, 
   y, 
   z
): void;

Set an AI's world-space movement wish; magnitudes above one are clamped.

Parameters

Parameter	Type
`actor`	`ActorHandle`
`x`	`number`
`y`	`number`
`z`	`number`

Returns

void

Example

setMovementWish(pawn, 1, 0, 0);

setRespawnPoint()

function setRespawnPoint(
   entity, 
   position, 
   yaw
): void;

Remember a checkpoint for this entity, honoured before PlayerStarts. Yaw is radians. Call inside init or a system. Checkpoints are saved with defineGame snapshots.

Parameters

Parameter	Type	Description
`entity`	`number`	Player entity.
`position`	`Vec3`	World position (copied).
`yaw`	`number`	Facing in radians, zero faces +Z.

Returns

void

Example

setRespawnPoint(ctx.player, { x: 2, y: 0, z: 3 }, Math.PI);

setSeat()

function setSeat(controller, seat): void;

Give a controller a player's seat; a PlayerController gets one at login.

Parameters

Parameter	Type	Description
`controller`	`ActorHandle`	A controller actor.
`seat`	`number`	The player's seat (0 in a single-player game).

Returns

void

Example

setSeat(controller, player.id);

setSignal()

function setSignal(self, on): void;

Set a signal; allocate its record only during actor construction.

Parameters

Parameter	Type	Description
`self`	`ActorHandle`	Signal source actor.
`on`	`boolean`	Whether the signal reports on.

Returns

void

Example

setSignal(self, true);

setTeam()

function setTeam(
   ctx, 
   seat, 
   team
): boolean;

Set a team by id (one based) or configured name, respecting capacity.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current authority context.
`seat`	`number`	Logged-in player seat.
`team`	`string` \| `number`	Configured team name or one-based id; zero clears membership.

Returns

boolean

Whether the requested membership is valid and fits.

Example

setTeam(ctx, 0, 'blue');

setText()

function setText(
   actor, 
   text, 
   component?
): void;

Change a text widget, preserving its style, stable id and world anchor.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`text`	`string` \| `number`	New text or number.
`component?`	`string`	Component name; defaults to the first text widget.

Returns

void

Example

setText(actor, 100, 'label');

setVehicleGrip()

function setVehicleGrip(
   ctx, 
   pawn, 
   sourceId, 
   scale, 
   until
): void;

Set/refresh one grip source until absolute simulated seconds (ctx.elapsed). Scales are clamped to [0,1]; concurrent sources combine by minimum. Expired sources are reusable. Each chassis preallocates world.maxEntities source slots at creation. Authority/solo only; reset and respawn clear every source.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Frame context.
`pawn`	`ActorHandle`	Vehicle pawn.
`sourceId`	`string` \| `number`	Stable identifier unique to the effect source.
`scale`	`number`	Grip multiplier.
`until`	`number`	Absolute expiry in simulated seconds.

Returns

void

Example

setVehicleGrip(ctx, car, 'rocket', 0.3, ctx.elapsed + 0.6);

setVehicleInput()

function setVehicleInput(pawn, input): void;

Submit finite intent, consumed once on the next component step.

Parameters

Parameter	Type	Description
`pawn`	`ActorHandle`	Vehicle pawn.
`input`	`Readonly`<`VehicleInput`>	Normalized controls.

Returns

void

Example

setVehicleInput(pawn, { throttle: 1, steer: 0, brake: 0, handbrake: 0 });

setViewTarget()

function setViewTarget(
   ctx, 
   seat, 
   target
): void;

Select a seated controller's view target; null restores its pawn's camera.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`seat`	`number`	Player seat.
`target`	`ActorHandle`<`object`> \| `null`	Actor to view through, or null.

Returns

void

Example

setViewTarget(ctx, 0, securityCamera);

setWidget()

function setWidget(
   actor, 
   node, 
   component?
): void;

Replace a widget's contents, retaining its component anchor and default identity.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`node`	`UiNode`	New contents.
`component?`	`string`	Component name; defaults to the first widget.

Returns

void

Example

setWidget(actor, { type: 'text', text: 'Ready' }, 'label');

setWidgetVisible()

function setWidgetVisible(
   actor, 
   visible, 
   component?
): void;

Include or omit a widget when the game next composes its UI model.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`visible`	`boolean`	Whether to include the node.
`component?`	`string`	Component name; defaults to the first widget.

Returns

void

Example

setWidgetVisible(actor, false, 'label');

setYaw()

function setYaw(entity, yaw): void;

Turn an entity to a yaw: its whole rotation becomes that turn about +Y (upright), and it is marked moved.

Parameters

Parameter	Type	Description
`entity`	`number`	The entity.
`yaw`	`number`	Radians about `+Y`; `0` faces `+Z`.

Returns

void

Example

import { setYaw } from 'gameable';

declare const guard: number;
setYaw(guard, Math.PI); // facing -Z

shapeForQuery()

function shapeForQuery<T>(setup): T;

Select query geometry without creating a duplicate simulation collider.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`setup`	`CollisionShapeSetup`<`T`>	Shapes, trace flag and query complexity.

Returns

T

The selected simple aggregate or triangle geometry.

Example

shapeForQuery({ simple: 'box', complex: 'mesh', collisionTraceFlag: 'simpleAsComplex' });

shapeForSimulation()

function shapeForSimulation<T>(setup): T;

Select simulation geometry. ComplexAsSimple requires fixed/kinematic triangle surfaces; this helper does not enable dynamic concave simulation.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`setup`	`CollisionShapeSetup`<`T`>	Separate simple and complex geometries with routing policy.

Returns

T

The geometry intended for simulation.

Example

shapeForSimulation({ simple: 'box', complex: 'mesh', collisionTraceFlag: 'simpleAndComplex' });

sideScrollCamera()

function sideScrollCamera(options): object;

Create a fixed side view with soft directional lead and a vertical dead zone. Call reset at init or respawn. All update scratch is owned by the rig.

Parameters

Parameter	Type	Description
`options`	`SideScrollCameraOptions`	Camera centre bounds and response.

Returns

object

Reusable camera controller.

reset()

reset(point): void;

Parameters

Parameter	Type
`point`	`Vec3`

Returns

void

update()

update(
   ctx, 
   point, 
   velocity
): void;

Parameters

Parameter	Type
`ctx`	`GameContext`
`point`	`Vec3`
`velocity`	`Readonly`<`Vec3`>

Returns

void

Example

const rig = sideScrollCamera({ minX: 0, maxX: 40 });
rig.reset({ x: 0, y: 1, z: 0 });
// In a system: rig.update(ctx, hero.position, movementOf(hero.entity)!.velocity);

simpleMoveTo()

function simpleMoveTo(
   _ctx, 
   pawn, 
   target, 
   opts?
): void;

Replace a pawn's walking order, independently of possession. Requires characterMovement. Request storage allocates on the first order; tick processing reuses it. State is saved with the actor and query buffers are rebuilt on restore.

Parameters

Parameter	Type	Description
`_ctx`	`GameContext`	Current game context.
`pawn`	`number`	Character actor root entity.
`target`	`Vec3`	World-space destination, copied into the request.
`opts?`	{ `acceptanceRadius?`: `number`; `speedScale?`: `number`; }	Walking options.
`opts.acceptanceRadius?`	`number`	Arrival distance in metres (default 0.1).
`opts.speedScale?`	`number`	Multiplier of the character's base walking speed (default 1).

Returns

void

Example

simpleMoveTo(ctx, player, { x: 8, y: 0, z: 4 });

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, or zero when the spawn budget is exhausted.

Example

import { spawn } from 'gameable';

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

spawnActor()

function spawnActor<P>(
   ctx, 
   cls, 
   opts
): ActorHandle<P>;

Spawn every component, apply overrides, then run construct on authority/solo. beginPlay waits for the next actor step, including spawns inside a hook.

Type Parameters

Type Parameter
`P` extends `object`

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current game context.
`cls`	`ActorClass`<`P`>	Registered actor class.
`opts`	`ActorSpawnOptions`<`P`>	Local transform or spawn options.

Returns

ActorHandle<P>

The new actor handle, or an inert handle when a spawn budget limit is reached.

Throws

The original construction or validation error after rolling back the actor.

Example

const crate = spawnActor(ctx, Crate, { position: { x: 0, y: 2, z: 0 }, yaw: 90 });

spawnEmitterAtLocation()

function spawnEmitterAtLocation(
   ctx, 
   preset, 
   at, 
   opts?
): void;

SpawnEmitterAtLocation: emit a one-shot preset without acquiring a handle.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`preset`	`VfxPreset`	Built-in preset.
`at`	`Vec3`	World position in metres.
`opts?`	{ `intensity?`: `number`; `scale?`: `number`; `tint?`: readonly [`number`, `number`, `number`]; }	Particle overrides.
`opts.intensity?`	`number`	Particle count and brightness multiplier.
`opts.scale?`	`number`	Particle size multiplier.
`opts.tint?`	readonly [`number`, `number`, `number`]	Linear RGB particle color.

Returns

void

Example

spawnEmitterAtLocation(ctx, 'explosion', self.position);

spawnerWaves()

function spawnerWaves(self): Waves;

Borrow a spawner's waves controller, for manual start/stop and progress queries.

Parameters

Parameter	Type	Description
`self`	`ActorHandle`	Actor instance.

Returns

Waves

The waves controller for this instance.

Example

spawnerWaves(spawner).start(ctx);

spawnTileColliders()

function spawnTileColliders(
   ctx, 
   cells, 
   options?
): number[];

Spawn merged tile boxes as fixed bodies. The current SDK has no aggregate-body spawn command: each merged rectangle is one body, rather than Paper2D's compound. Call during initialization, never each tick.

Parameters

Parameter	Type	Description
`ctx`	`Pick`<`GameContext`, `"spawn"`>	Game context providing spawn.
`cells`	readonly `CollisionCell`[]	Solid cells to merge.
`options`	`TileColliderOptions`	Horizontal spacing and collision policy (default BlockAll).

Returns

number[]

Spawned entity ids.

Example

const entities = spawnTileColliders(ctx, [{ x: 0, z: 0, height: 1 }]);

sphere()

function sphere(dims, opts?): ActorComponent;

A sphere specified by radius.

Parameters

Parameter	Type	Description
`dims`	readonly [`number`]	Shape dimensions in metres.
`opts`	`ShapeOptions`	Local transform or spawn options.

Returns

The component declaration.

Example

import { sphere } from 'gameable';
const root = sphere([1], { collision: 'overlap' });

spline()

function spline(points, opts?): ActorComponent;

Author a local linear or uniformly sampled Catmull-Rom path.

Parameters

Parameter	Type
`points`	readonly readonly [`number`, `number`, `number`][]
`opts`	`ComponentOptions` & `object`

Returns

Example

const path = spline([[0, 0, 0], [0, 0, 5]]);

splineOf()

function splineOf(actor, component): SplinePath;

Get a component's world-space spline queries; rejects other component types.

Parameters

Parameter	Type
`actor`	`ActorHandle`
`component`	`string`

Returns

SplinePath

Example

splineOf(actor, 'path').pointAt(2, position);

spotOf()

function spotOf(
   thing, 
   name, 
   out
): WorldSpotNow | null;

Where one of a thing's rider spots is now, in the world: the seat, a grip, a foot rest.

A spot is on a part and moves with it, so a grip turns with the handlebars: the spot goes through each joint between its part and the thing's root at the value the joint stands at (thing.joints[i].value), then to where the thing is and how it is turned. Allocates nothing when out is reused.

Parameters

Parameter	Type	Description
`thing`	`WorldThing`	The thing.
`name`	`string`	The spot's name: `seat`, `gripLeft`, `gripRight`, `footLeft`, `footRight`.
`out`	`WorldSpotNow`	The record to fill.

Returns

WorldSpotNow | null

out, or null when the thing has no such spot.

Example

import { spotOf, type WorldSpotNow } from 'gameable';

const seat: WorldSpotNow = {
  position: { x: 0, y: 0, z: 0 },
  forward: { x: 0, y: 0, z: 1 },
  up: { x: 0, y: 1, z: 0 },
};
if (spotOf(bike, 'seat', seat)) console.log(seat.position); // where the seat is now

stamina()

function stamina(options?): ActorComponent;

Drain while requested; recover slowly after a delay. Exhaustion locks sprint until full. Requests are sampled on the next component step. State survives actor snapshots.

Parameters

Parameter	Type
`options`	`StaminaOptions`

Returns

Example

const components = { root: scene(), stamina: stamina({ maximum: 5 }) };

staminaOf()

function staminaOf(actor, name?): StaminaState;

Read a stamina component without allocating.

Parameters

Parameter	Type	Default value
`actor`	`ActorHandle`	`undefined`
`name`	`string`	`'stamina'`

Returns

StaminaState

Example

const energy = staminaOf(hero);

standFor()

function standFor(
   thing, 
   from?, 
   out?
): WorldStand;

Where to stand to use a thing, and which way to face.

The package's own spot while the thing is where it was made. For a thing that has moved, or one the package gave no spot, a spot beside it, facing it: on the side of from when given (the nearest side to whoever asks), else on the side the package's spot was, else on its +z side.

Parameters

Parameter	Type	Default value	Description
`thing`	`WorldThing`	`undefined`	The thing.
`from`	`Vec3` \| `null`	`null`	Where the asker is, or null.
`out`	`WorldStand`	`...`	The record to fill.

Returns

WorldStand

out.

Example

import { findThing, standFor } from 'gameable';

const trunk = findThing(things, 'the trunk');
if (trunk) {
  const spot = standFor(trunk, null);
  console.log(spot.x, spot.z, spot.facing); // walk here, turn to this
}

startMatch()

function startMatch(ctx): void;

Start a waiting match.

Parameters

Parameter	Type
`ctx`	`GameContext`

Returns

void

Example

startMatch(ctx);

stepCharacterMovement()

function stepCharacterMovement(
   cm, 
   q, 
   capsule, 
   position, 
   input, 
   dt
): void;

Advance a capsule centre with bounded simulation substeps. Input is normalized world acceleration.

Parameters

Parameter	Type	Description
`cm`	`CharacterMovement`	Mover state and preallocated scratch.
`q`	`MoveQuery`	Blocking-world query adapter.
`capsule`	`Capsule`	Full movement capsule dimensions.
`position`	`Vec3`	Mutable capsule centre in metres.
`input`	{ `acceleration`: `Vec3`; `jump?`: `boolean`; }	Normalized world-space acceleration and optional jump.
`input.acceleration`	`Vec3`	Optional acceleration value.
`input.jump?`	`boolean`	Optional jump value.
`dt`	`number`	Simulation duration in seconds.

Returns

void

Example

const cm = createCharacterMovement();
const p = { x: 0, y: 2, z: 0 };
const empty = { sweep: () => null, overlap: () => [] };
stepCharacterMovement(cm, empty, { radius: 0.35, halfHeight: 0.55 }, p, { acceleration: {x:0,y:0,z:0} }, 1/60);

stepMoves()

function stepMoves(ctx): void;

Advance walking orders once per tick, using addMovementInput for the next actor step. Add to defineGame systems; avoid simultaneously submitting manual or AI walking input.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current frame context.

Returns

void

Example

defineGame({ systems: [stepMoves] });

stopAmbientSound()

function stopAmbientSound(ctx, actor): void;

Stop the ambient component once.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current context.
`actor`	`ActorHandle`<`AmbientProps`>	Ambient actor.

Returns

void

Example

stopAmbientSound(ctx, ambient);

stopBehaviorTree()

function stopBehaviorTree(ai): void;

Stop and reset the pawn's tree state.

Parameters

Parameter	Type
`ai`	`ActorHandle`

Returns

void

Example

stopBehaviorTree(ai);

stopDriving()

function stopDriving(ctx, ai): void;

Abort a drive once and submit neutral controls to its previous pawn.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Frame context.
`ai`	`ActorHandle`	AI controller.

Returns

void

Example

stopDriving(ctx, ai);

stopMove()

function stopMove(_ctx, pawn): void;

Cancel an order and clear accumulated input and velocity immediately.

Parameters

Parameter	Type	Description
`_ctx`	`GameContext`	Current game context.
`pawn`	`number`	Character actor root entity.

Returns

void

Example

stopMove(ctx, player);

stopMovement()

function stopMovement(ctx, ai): void;

Abort the current request exactly once.

Parameters

Parameter	Type
`ctx`	`GameContext`
`ai`	`ActorHandle`

Returns

void

Example

stopMovement(ctx, ai);

stopMovementImmediately()

function stopMovementImmediately(entity): void;

Clear velocity, accumulated input and a pending jump.

Parameters

Parameter	Type	Description
`entity`	`number`	Actor root entity.

Returns

void

Example

stopMovementImmediately(player);

stopSound()

function stopSound(
   ctx, 
   actor, 
   component?, 
   fadeMs?
): void;

Stop once, optionally fading out; also cancels pending autoplay.

Parameters

Parameter	Type	Default value	Description
`ctx`	`GameContext`	`undefined`	Current context.
`actor`	`ActorHandle`	`undefined`	Owning actor.
`component?`	`string`	`undefined`	Audio component name.
`fadeMs?`	`number`	`0`	Fade duration in milliseconds.

Returns

void

Example

stopSound(ctx, actor, 'sound', 100);

suggestActorClass()

function suggestActorClass(name, names?): string[];

Suggest registered actor names from typos or descriptive aliases, including TriggerVolume.

Parameters

Parameter	Type	Description
`name`	`string`	Class name supplied by an author.
`names`	readonly `string`[]	Available classes; defaults to the live registry.

Returns

string[]

Up to three closest names, ordered by name for ties; empty when no match is close.

Example

const names = suggestActorClass('PlayrStart'); // ['PlayerStart']

teamOf()

function teamOf(seat): number;

Read a player's team id, zero when unassigned.

Parameters

Parameter	Type	Description
`seat`	`number`	Logged-in player seat.

Returns

number

Team id, or zero when unassigned.

Example

const team = teamOf(0);

teamScore()

function teamScore(team): number;

Read accumulated team points, including points awarded directly to a team.

Parameters

Parameter	Type	Description
`team`	`string` \| `number`	Configured team name or one-based id; zero clears membership.

Returns

number

Accumulated match points for this team.

Example

const points = teamScore('blue');

teleportToTile()

function teleportToTile(entity, tile): void;

Place on a tile, cancelling a step and releasing its reservation. Destination must be clear.

Parameters

Parameter	Type	Description
`entity`	`number`	Walker entity.
`tile`	`Readonly`<`GridTile`>	Destination tile.

Returns

void

Example

teleportToTile(hero.entity, { x: 0, z: 0 });

thingsNear()

function thingsNear(
   things, 
   point, 
   radius, 
   out?
): WorldThing[];

What is near a point: every thing whose box is within radius, the nearest first.

Allocates nothing when out is reused, so a system may ask every step.

Parameters

Parameter	Type	Default value	Description
`things`	readonly `WorldThing`[]	`undefined`	The world's things.
`point`	`Vec3`	`undefined`	The point, for example the player's feet.
`radius`	`number`	`undefined`	Metres.
`out`	`WorldThing`[]	`[]`	The array to fill; emptied first.

Returns

WorldThing[]

out.

Example

import { thingsNear, type WorldThing } from 'gameable';

const near: WorldThing[] = [];
thingsNear(things, { x: 0, y: 0, z: -2 }, 1.5, near);
console.log(near[0]?.label); // the nearest thing within a metre and a half

topDownCamera()

function topDownCamera(options?): ActorComponent;

Pan/rotate/zoom a focus point while this actor is the active camera. Attach to a CameraActor subclass and use activateCamera; omit player.camera. Pose and follow bookkeeping live in actor state and survive snapshot restore.

Parameters

Parameter	Type	Description
`options`	`TopDownCameraOptions`	Rig controls and limits.

Returns

A top-down camera scene component.

Example

const view = defineActor('MapCamera', { ...CameraActor.spec, components: { root: scene(), view: topDownCamera() } });

topDownEye()

function topDownEye(state, out): Vec3;

Compute the eye from focus, yaw, downward pitch and boom distance without allocating.

Parameters

Parameter	Type	Description
`state`	`TopDownCameraState`	Camera pose.
`out`	`Vec3`	Caller-owned result.

Returns

out.

Example

topDownEye(createTopDownCamera().state, { x: 0, y: 0, z: 0 });

topDownForward()

function topDownForward(yaw, out): Vec3;

Compute unit ground-plane pan forward; yaw zero points toward -Z.

Parameters

Parameter	Type	Description
`yaw`	`number`	Radians about +Y.
`out`	`Vec3`	Caller-owned result.

Returns

out.

Example

topDownForward(0, { x: 0, y: 0, z: 0 });

traceMask()

function traceMask(responses, channel): CollisionLayers;

Build a trace mask from the policies of candidate bodies. A single response container cannot describe which object types answer a trace; supply the registry of setups used in the scene. Bodies sharing a layer still need post-filtering.

Parameters

Parameter	Type	Description
`responses`	readonly `CollisionSetup`[]	Candidate body collision setups.
`channel`	`"visibility"` \| `"camera"`	Trace channel to test.

Returns

CollisionLayers

Layers whose bodies permit this query (block or overlap).

Example

const mask = traceMask([collisionProfile('Pawn')], 'camera');

transferItem()

function transferItem(
   from, 
   to, 
   item, 
   amount
): boolean;

Transfer all requested items or none; both bags commit before notifications. Across schemas, match items by id and use the destination stack limits. A missing destination id or insufficient space fails without changing either bag.

Parameters

Parameter	Type	Description
`from`	`ActorHandle`	Source actor.
`to`	`ActorHandle`	Destination actor.
`item`	`string`	Catalog id.
`amount`	`number`	Nonnegative safe integer.

Returns

boolean

Whether the entire transfer succeeded.

Example

const transferred = transferItem(chest, player, 'coin', 5);

trySpawnActor()

function trySpawnActor<P>(
   ctx, 
   cls, 
   opts
): ActorHandle<P> | null;

Try to spawn an actor atomically within the guest's per-step and live limits.

Type Parameters

Type Parameter
`P` extends `object`

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	Current game context.
`cls`	`ActorClass`<`P`>	Registered actor class.
`opts`	`ActorSpawnOptions`<`P`>	Instance transform and overrides.

Returns

ActorHandle<P> | null

The new handle, or null when allocation or construction fails or a limit is reached.

Example

const crate = trySpawnActor(ctx, Crate, { position: { x: 0, y: 2, z: 0 } });

unequipItem()

function unequipItem(actor, slot): boolean;

Return equipment to the bag atomically; an empty slot succeeds without events.

Parameters

Parameter	Type	Description
`actor`	`ActorHandle`	Owning actor.
`slot`	`string`	Named equipment slot.

Returns

boolean

Whether the item was returned or the slot was empty.

Example

const returned = unequipItem(actor, 'hand');

unlockDoor()

function unlockDoor(door): void;

Clear the required key. Player unlocks additionally fire onUnlocked.

Parameters

Parameter	Type	Description
`door`	`ActorHandle`<`DoorCoreProps`>	Kit door instance.

Returns

void

Example

unlockDoor(door);

unPossess()

function unPossess(ctx, controller): void;

Make a controller let its pawn go. Its player then controls nothing until the next possess.

Parameters

Parameter	Type	Description
`ctx`	`GameContext`	The game context.
`controller`	`ActorHandle`	The controller actor.

Returns

void

Example

unPossess(ctx, controller);

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.

validateDataTables()

function validateDataTables(): string[];

Check deferred references in tables and assets after all declarations are loaded.

Returns

string[]

Problems naming the source row, field and missing target; empty means valid.

Example

const problems = validateDataTables();

validateLevel()

function validateLevel(data, options?): LevelFile;

Validate a level without spawning. All errors include their JSON path. Catalog types, bounds and allowed values provide authoring diagnostics.

Parameters

Parameter	Type	Description
`data`	`unknown`	Parsed JSON document.
`options`	`ValidateLevelOptions`	The game's own classes, when they are not registered here.

Returns

LevelFile

The validated document.

Example

const level = validateLevel({ format: 1, actors: [] });

vehicleMovement()

function vehicleMovement(options?): ActorComponent;

Dynamic box root with host arcade handling. Selector runs once at creation.

Parameters

Parameter	Type	Description
`options`	\| `VehicleOptions` \| ((`pawn`) => `VehicleOptions`)	Preset and explicit overrides, or a pawn selector.

Returns

WaypointMovementComponent

Dynamic box root declaration.

Example

const root = vehicleMovement(pawn => pawn.props);

vehicleStateOf()

function vehicleStateOf(pawn): Readonly<VehicleState> | undefined;

Borrow post-step telemetry, or undefined for a non-vehicle.

Parameters

Parameter	Type	Description
`pawn`	`ActorHandle`	Vehicle pawn.

Returns

Readonly<VehicleState> | undefined

Borrowed telemetry, or undefined for a non-vehicle.

Example

const speed = vehicleStateOf(pawn)?.speed;

viewport()

function viewport(): Viewport;

Current guest view dimensions; a borrowed record, treated as read-only. Hosts send a resized event on the first tick and after view resizes, so dimensions are CSS pixels before the first update. Until that event arrives, uses init dimensions divided by DPR when known, otherwise as given. The current GameConfig carries no DPR, so init dimensions are used as given. Input is client CSS coordinates: an embedded view also requires subtracting its client offset in page code.

Returns

Viewport

Example

const size = viewport(); console.log(size.width, size.height);

viewTargetOf()

function viewTargetOf(seat): ActorHandle<object> | null;

Find the explicit living view target for a seat (null means use its pawn).

Parameters

Parameter	Type	Description
`seat`	`number`	Player seat.

Returns

ActorHandle<object> | null

Explicit target, or null if unset or destroyed.

Example

const target = viewTargetOf(0);

waypointMovement()

function waypointMovement(source): WaypointMovementComponent;

Move the root using the actor API, which teleports kinematic bodies like race movers.

Parameters

Parameter	Type	Description
`source`	\| `WaypointMovementOptions` \| ((`actor`) => `WaypointMovementOptions`)	Static options or an allocation-free per-actor selector.

Returns

The component and its per-actor control factory.

Example

const movement = waypointMovement({ points: [{x: 3,y: 0,z: 0}], seconds: 2, mode: 'pingPong' });

worldText()

function worldText(text, opts?): ActorComponent;

World text composed into the game's UI via actorWidgets().

Parameters

Parameter	Type	Description
`text`	`string`	Initial text.
`opts`	`ComponentOptions` & `object`	Text style and component attachment options.

Returns

Example

const label = worldText('Shop', { size: 'lg', offset: [0, 2, 0] });

worldToScreen()

function worldToScreen(
   ctx, 
   point, 
   out
): boolean;

Project a world point using this frame's camera and guest viewport.

Parameters

Parameter	Type
`ctx`	`GameContext`
`point`	`Vec3`
`out`	`ScreenPoint`

Returns

boolean

Example

worldToScreen(ctx, destination, labelPosition);

worldWidget()

function worldWidget(node, opts?): ActorComponent;

Draw a UI node anchored to this component's entity without owning the UI model. Offset is the world anchor offset in metres, applied once; attachment rotation/scale remain local.

Parameters

Parameter	Type	Description
`node`	`UiNode`	Widget contents, copied separately for each actor.
`opts`	`ComponentOptions` & `object`	Attachment and visibility options.

Returns