@aosengine/core

Classes

ModuleError

A module that could not be registered, initialised or found.

Extends

Error

Constructors

Constructor

new ModuleError(
   moduleId, 
   message, 
   options?
): ModuleError;

Build a module error.

Parameters

Parameter	Type	Description
`moduleId`	`string`	Module or service id involved.
`message`	`string`	What went wrong.
`options?`	`ErrorOptions`	Standard `Error` options, used to keep the cause.

Returns

ModuleError

Overrides

Error.constructor

Properties

moduleId

readonly moduleId: string;

The module or service id involved.

SceneGraph

Maps entity ids to scene objects.

Constructors

Constructor

new SceneGraph(scene, name?): SceneGraph;

Build a scene graph and attach its root to the scene.

Parameters

Parameter	Type	Default value	Description
`scene`	`Scene`	`undefined`	Scene to attach to.
`name`	`string`	`'aosengine:root'`	Name given to the root group, for debugging.

Returns

SceneGraph

Properties

root

readonly root: Group;

Group every spawned object is parented under.

scene

readonly scene: Scene;

The scene the root was added to.

Accessors

size

Get Signature

get size(): number;

How many entities are in the graph.

Returns

number

The entity count.

Methods

despawn()

despawn(id): boolean;

Remove an entity.

Children are re-parented to the root rather than removed with it, so a despawn cannot silently take a subtree the caller still tracks. Despawn them explicitly if that is what you want.

Parameters

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

Returns

boolean

True when the entity existed.

dispose()

dispose(): void;

Remove every entity and detach the root from the scene.

Returns

void

get()

get(id): Object3D<Object3DEventMap> | undefined;

Look up an entity's object.

Parameters

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

Returns

Object3D<Object3DEventMap> | undefined

The object, or undefined when the id is not spawned.

idOf()

idOf(object): number;

The entity id an object was spawned under.

Parameters

Parameter	Type	Description
`object`	`Object3D`	Any object in the graph.

Returns

number

The id, or 0 when the object was not spawned here.

ids()

ids(): IterableIterator<number>;

Every spawned entity id, in insertion order.

Returns

IterableIterator<number>

An iterator over ids.

setParent()

setParent(id, parentId?): void;

Re-parent an entity.

Parameters

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	Entity id to move.
`parentId`	`number`	`NO_ENTITY`	New parent's entity id, or `0` for the root.

Returns

void

spawn()

spawn(
   id, 
   object, 
   parentId?
): Object3D;

Add an object under an entity id.

Parameters

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	Entity id. Must be a positive integer; `0` is the root.
`object`	`Object3D`	`undefined`	The object to add.
`parentId`	`number`	`NO_ENTITY`	Parent entity id, or `0` for the root.

Returns

Object3D

The object, so calls can be chained.

Example

import { SceneGraph } from '@aosengine/core';
import { Group, Scene } from 'three/webgpu';

const graph = new SceneGraph(new Scene());
graph.spawn(1, new Group());
graph.spawn(2, new Group(), 1); // child of entity 1

TransformStore

Previous and current position, rotation and scale for a set of entity ids.

Constructors

Constructor

new TransformStore(capacity?): TransformStore;

Build a transform store.

Parameters

Parameter	Type	Default value	Description
`capacity`	`number`	`DEFAULT_TRANSFORM_CAPACITY`	Slots to reserve up front.

Returns

TransformStore

Accessors

capacity

Get Signature

get capacity(): number;

Slots currently allocated.

Returns

number

The number of addressable entity slots.

highWater

Get Signature

get highWater(): number;

One past the highest slot ever written.

Returns

number

The bound commit scans to.

Methods

clear()

clear(id): void;

Forget an entity. Its slot is reset to the identity transform.

Parameters

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

Returns

void

commit()

commit(): void;

Make the current transform the previous one, for every slot that changed.

Call once per fixed step, before that step writes new values. Costs a byte per slot to scan plus ten floats per slot that actually moved.

Returns

void

ensure()

ensure(id): void;

Grow so that id is addressable.

Capacity doubles until it fits, so a run of spawn calls is amortised O(1).

Parameters

Parameter	Type	Description
`id`	`number`	Entity id that must fit.

Returns

void

getPosition()

getPosition(id, out): number[] | Float32Array<ArrayBufferLike>;

Read the current position into out.

Parameters

Parameter	Type	Description
`id`	`number`	Entity id.
`out`	`number`[] \| `Float32Array`<`ArrayBufferLike`>	A length-3 array to fill.

Returns

number[] | Float32Array<ArrayBufferLike>

out.

getQuaternion()

getQuaternion(id, out): number[] | Float32Array<ArrayBufferLike>;

Read the current rotation into out.

Parameters

Parameter	Type	Description
`id`	`number`	Entity id.
`out`	`number`[] \| `Float32Array`<`ArrayBufferLike`>	A length-4 array to fill.

Returns

number[] | Float32Array<ArrayBufferLike>

out.

has()

has(id): boolean;

Whether an entity has ever been written.

Parameters

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

Returns

boolean

True when the slot holds a transform.

isDirty()

isDirty(id): boolean;

Whether an entity is mid-motion or still owes its object a write.

Parameters

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

Returns

boolean

True when the next writeInterpolated will touch the object.

set()

set(
   id, 
   px, 
   py, 
   pz, 
   qx, 
   qy, 
   qz, 
   qw, 
   sx, 
   sy, 
   sz
): void;

Write a whole transform at once. This is the packed-buffer entry point.

Parameters

Parameter	Type	Description
`id`	`number`	Entity id.
`px`	`number`	Position x.
`py`	`number`	Position y.
`pz`	`number`	Position z.
`qx`	`number`	Quaternion x.
`qy`	`number`	Quaternion y.
`qz`	`number`	Quaternion z.
`qw`	`number`	Quaternion w.
`sx`	`number`	Scale x.
`sy`	`number`	Scale y.
`sz`	`number`	Scale z.

Returns

void

setPosition()

setPosition(
   id, 
   x, 
   y, 
   z
): void;

Write the current position of an entity.

The first write to a slot also seeds the previous transform, so a freshly spawned entity does not interpolate in from the origin.

Parameters

Parameter	Type	Description
`id`	`number`	Entity id.
`x`	`number`	Position x.
`y`	`number`	Position y.
`z`	`number`	Position z.

Returns

void

setQuaternion()

setQuaternion(
   id, 
   x, 
   y, 
   z, 
   w
): void;

Write the current rotation of an entity.

Parameters

Parameter	Type	Description
`id`	`number`	Entity id.
`x`	`number`	Quaternion x.
`y`	`number`	Quaternion y.
`z`	`number`	Quaternion z.
`w`	`number`	Quaternion w.

Returns

void

setScale()

setScale(
   id, 
   x, 
   y, 
   z
): void;

Write the current scale of an entity.

Parameters

Parameter	Type	Description
`id`	`number`	Entity id.
`x`	`number`	Scale x.
`y`	`number`	Scale y.
`z`	`number`	Scale z.

Returns

void

snap()

snap(id): void;

Collapse one entity's history, so the next frame does not interpolate.

Use after a teleport.

Parameters

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

Returns

void

writeInterpolated()

writeInterpolated(
   id, 
   object, 
   alpha
): boolean;

Write the blend of previous and current onto an Object3D.

Once previous and current agree and the object has received that value, this returns without touching the object — and so without dirtying its world matrix — until the entity moves again.

Parameters

Parameter	Type	Description
`id`	`number`	Entity id.
`object`	`Object3D`	Target object; its `position`, `quaternion` and `scale` are written.
`alpha`	`number`	Interpolation factor, normally the loop's `alpha` in `[0, 1)`.

Returns

boolean

True when the entity existed, whether or not the object needed writing.

Interfaces

CreateEngineOptions

Options accepted by createEngine.

Properties

canvas

readonly canvas: HTMLCanvasElement;

The canvas to render into. The engine observes it for size changes.

debug?

readonly optional debug?: boolean;

Create the F3 debug overlay. Defaults to false.

dracoDecoderPath?

readonly optional dracoDecoderPath?: string;

Draco decoder directory handed to the default gltf loader.

fixedHz?

readonly optional fixedHz?: number;

Simulation rate. Defaults to 60.

ktx2TranscoderPath?

readonly optional ktx2TranscoderPath?: string;

Basis transcoder directory handed to the default gltf loader.

loaders?

readonly optional loaders?: Readonly<Record<string, AssetLoader>>;

Asset loaders, replacing the built-in gltf and audio pair.

Adding a type is engine.ctx.assets.registerLoader(...), not this.

manifest?

readonly optional manifest?: string | object | AssetManifest;

The asset manifest: a URL to fetch, or an already-parsed document.

Omit for an engine with an empty registry, which is what the unit tests and the splat viewer use.

maxSubsteps?

readonly optional maxSubsteps?: number;

Most fixed steps one frame may run. Defaults to 5.

modules?

readonly optional modules?: readonly EngineModule[];

Modules to register, in any order; order decides the run order.

renderer?

readonly optional renderer?: EngineRendererOptions;

Renderer options.

DebugOverlay

The debug overlay.

Properties

element

readonly element: HTMLElement | null;

The panel element, or null when there is no DOM to mount into.

stats

readonly stats: FrameStats;

The frame-time window behind the numbers.

visible

readonly visible: boolean;

Whether the panel is currently shown.

Methods

dispose()

dispose(): void;

Remove the panel and the key listener.

Returns

void

sample()

sample(frameMs, nowMs): void;

Record a frame and, at most every intervalMs, redraw.

Parameters

Parameter	Type	Description
`frameMs`	`number`	How long the frame took, in milliseconds.
`nowMs`	`number`	Current timestamp, in milliseconds.

Returns

void

setVisible()

setVisible(value): void;

Show or hide the panel.

Parameters

Parameter	Type	Description
`value`	`boolean`	True to show.

Returns

void

toggle()

toggle(): void;

Flip visibility. This is what the hotkey does.

Returns

void

DebugOverlayOptions

Options accepted by createDebugOverlay.

Properties

backendName

readonly backendName: string;

Backend label, for example webgpu or webgl.

container?

readonly optional container?: HTMLElement;

Where to mount the panel. Defaults to document.body.

hotkey?

readonly optional hotkey?: string;

KeyboardEvent.code that toggles visibility. Defaults to F3.

intervalMs?

readonly optional intervalMs?: number;

How often the text is rewritten, in milliseconds. Defaults to 250.

renderer

readonly renderer: WebGPURenderer;

Renderer whose info.render counters are shown.

samples?

readonly optional samples?: number;

Frames in the percentile window. Defaults to 120.

visible?

readonly optional visible?: boolean;

Whether the panel starts visible. Defaults to true.

Engine

A booted engine.

Properties

assets

readonly assets: AssetRegistry;

The asset registry.

camera

readonly camera: PerspectiveCamera;

The camera being rendered from.

ctx

readonly ctx: EngineContext;

The module context, for code that is not a module.

events

readonly events: Events<EngineEventMap>;

The engine event bus.

graph

readonly graph: SceneGraph;

Entity-id to Object3D mapping, rooted in the scene.

loop

readonly loop: FixedLoop;

The fixed-step loop.

modules

readonly modules: ModuleRegistry;

The module registry.

overlay

readonly overlay: DebugOverlay | null;

The debug overlay, when debug was set.

renderer

readonly renderer: WebGPURenderer;

The initialised renderer.

running

readonly running: boolean;

Whether the loop is running.

scene

readonly scene: Scene;

The scene being rendered.

Methods

dispose()

dispose(): Promise<void>;

Stop, dispose every module in reverse order, then the renderer.

Returns

Promise<void>

Resolves once the renderer has released its device.

get()

get<K>(id): EngineServices[K];

Look up a module's service.

Type Parameters

Type Parameter
`K` extends `"physics"`

Parameters

Parameter	Type	Description
`id`	`K`	Service id, typed through `EngineServices`.

Returns

EngineServices[K]

The service.

resize()

resize(width, height): void;

Resize the drawing buffer and the camera.

Called automatically by the canvas ResizeObserver; call it yourself only when you manage the canvas size some other way.

Parameters

Parameter	Type	Description
`width`	`number`	CSS width in pixels.
`height`	`number`	CSS height in pixels.

Returns

void

start()

start(): void;

Start the loop.

Returns

void

stop()

stop(): void;

Stop the loop. Modules keep their resources; start resumes.

Returns

void

EngineCaps

What the host turned out to be able to do, decided once after renderer.init().

Properties

characters

readonly characters: boolean;

True when splat characters can run.

Characters need compute shaders and a shared GPUDevice, so this tracks webgpu exactly. Check it before calling createCharacter.

webgpu

readonly webgpu: boolean;

True when the renderer got a real WebGPU backend rather than the WebGL fallback.

EngineConfig

The engine options after defaults were applied.

Properties

antialias

readonly antialias: boolean;

Whether MSAA was requested.

backend

readonly backend: RendererBackend;

Backend that was requested (not necessarily the one that was obtained).

debug

readonly debug: boolean;

Whether the debug overlay was created.

fixedDt

readonly fixedDt: number;

Length of one fixed step, in seconds: 1 / fixedHz.

fixedHz

readonly fixedHz: number;

Simulation rate in hertz.

maxSubsteps

readonly maxSubsteps: number;

Most fixed steps one frame may run.

pixelRatioCap

readonly pixelRatioCap: number;

Upper bound applied to devicePixelRatio.

EngineContext

Everything a module is given at init.

Properties

assets

readonly assets: AssetRegistry;

The asset registry built from the manifest.

camera

readonly camera: PerspectiveCamera;

The camera the engine renders with. Camera rigs drive this.

caps

readonly caps: EngineCaps;

What this host can actually do.

config

readonly config: EngineConfig;

The resolved engine options.

events

readonly events: Events<EngineEventMap>;

The engine event bus.

renderer

readonly renderer: WebGPURenderer;

The initialised renderer. Its backend.device is the one shared GPU device.

scene

readonly scene: Scene;

The scene the engine renders.

time

readonly time: Time;

The engine clock.

Methods

get()

get<K>(id): EngineServices[K];

Look up another module's service.

Only valid after that module's init has run, which order controls.

Type Parameters

Type Parameter
`K` extends `"physics"`

Parameters

Parameter	Type	Description
`id`	`K`	Service id.

Returns

EngineServices[K]

The service.

registerService()

registerService(id, service): void;

Publish a service under an id, so other modules can get it.

Equivalent to returning the service from init; use this when a module exposes something before it has finished initialising, or exposes nothing but wants to register under a different id.

Parameters

Parameter	Type	Description
`id`	`string`	Service id, matching a key of `EngineServices`.
`service`	`object`	The service object.

Returns

void

EngineEventMap

Events the engine itself publishes.

Other packages add their own by declaration merging, exactly as they do for EngineServices:

declare module '@aosengine/core' {
  interface EngineEventMap {
    'physics:contact': { a: number; b: number };
  }
}

Properties

engine:frame

engine:frame: object;

A frame finished, after rendering.

The payload object is reused every frame; read it in the handler and never retain it.

alpha

alpha: number;

dtReal

dtReal: number;

frame

frame: number;

substeps

substeps: number;

engine:resize

engine:resize: object;

The drawing buffer changed size.

height

height: number;

width

width: number;

engine:start

engine:start: undefined;

The loop has started.

engine:stop

engine:stop: undefined;

The loop has stopped.

EngineModule

One host subsystem.

init runs once, in order. dispose runs in reverse order and must release everything the module took. The per-frame hooks are optional and are called only on the modules that implement them, so an empty hook costs nothing.

Nothing in beginFrame, fixedUpdate, update or endFrame may allocate: they run at least 60 times a second.

Extended by

Properties

id

readonly id: string;

Unique id. Also the service id when init returns a service.

order?

readonly optional order?: number;

Sort key. Lower runs first; equal keys keep registration order.

Rough convention: input -100, gameplay -50, physics 0, rendering helpers 200. Gameplay runs before physics so that the commands a guest tick emits are simulated by the step that follows rather than the next one.

Methods

beginFrame()?

optional beginFrame(): void;

Run before the frame's fixed steps. Input capture lives here.

Returns

void

dispose()

dispose(): void;

Release everything this module took.

Returns

void

endFrame()?

optional endFrame(): void;

Run after rendering. Input's end-of-frame bookkeeping lives here.

Returns

void

fixedUpdate()?

optional fixedUpdate(dt): void;

Run once per fixed step.

Parameters

Parameter	Type	Description
`dt`	`number`	Always `ctx.config.fixedDt`, whatever `time.timeScale` is; time scale changes how many steps a frame runs, not their length.

Returns

void

init()

init(ctx): void | object | Promise<void | object>;

Acquire resources.

Parameters

Parameter	Type	Description
`ctx`	`EngineContext`	The host surface.

Returns

void | object | Promise<void | object>

Nothing, or the service to publish under id.

update()?

optional update(dt, alpha): void;

Run once per frame, after the fixed steps and before rendering.

Parameters

Parameter	Type	Description
`dt`	`number`	Clamped wall-clock seconds since the previous frame, scaled by `time.timeScale`.
`alpha`	`number`	Interpolation factor in `[0, 1)` for smoothing transforms.

Returns

void

EngineRendererOptions

Renderer options accepted by createEngine.

Properties

antialias?

readonly optional antialias?: boolean;

Request MSAA. Defaults to true.

backend?

readonly optional backend?: RendererBackend;

Which backend to target.

auto takes WebGPU when the browser has it and falls back to WebGL otherwise. webgpu refuses to boot without it. webgl forces the fallback, which is useful for reproducing what a WebGL player sees — characters are unavailable there.

pixelRatioCap?

readonly optional pixelRatioCap?: number;

Upper bound on devicePixelRatio. Defaults to 2.

Events

Typed pub/sub over the event map M.

Type Parameters

Type Parameter
`M` extends `EventMap`

Methods

clear()

clear(): void;

Drop every handler.

Returns

void

emit()

emit<K>(type, payload): void;

Publish an event.

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`type`	`K`	Event name.
`payload`	`M`[`K`]	Payload, matching the map.

Returns

void

listenerCount()

listenerCount(type): number;

How many handlers are subscribed to an event.

Parameters

Parameter	Type	Description
`type`	keyof `M`	Event name.

Returns

number

The live listener count.

off()

off<K>(type, listener): void;

Unsubscribe a handler.

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`type`	`K`	Event name.
`listener`	`Listener`<`M`[`K`]>	The exact function passed to `on`.

Returns

void

on()

on<K>(type, listener): () => void;

Subscribe to an event.

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`type`	`K`	Event name.
`listener`	`Listener`<`M`[`K`]>	Handler.

Returns

An unsubscribe function, so callers need not keep the reference.

() => void

once()

once<K>(type, listener): () => void;

Subscribe to the next occurrence only.

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type	Description
`type`	`K`	Event name.
`listener`	`Listener`<`M`[`K`]>	Handler.

Returns

An unsubscribe function.

() => void

FirstPersonRig

A first-person camera rig.

Properties

camera

readonly camera: PerspectiveCamera;

The camera being driven.

eyeHeight

eyeHeight: number;

Metres from the pose position up to the eyes. Writable: crouching changes it.

pitch

readonly pitch: number;

Last applied pitch, in radians, after clamping.

yaw

readonly yaw: number;

Last applied yaw, in radians.

Methods

setPose()

setPose(
   position, 
   yaw, 
   pitch
): void;

Place the camera.

position is the body's position — feet, or capsule base — not the eyes; eyeHeight is added to y.

Parameters

Parameter	Type	Description
`position`	`Vector3Like`	Body position in world space.
`yaw`	`number`	Rotation about world +Y, in radians. `0` looks down −Z.
`pitch`	`number`	Rotation about the camera's local +X, in radians. Positive looks up.

Returns

void

FirstPersonRigOptions

Options accepted by createFirstPersonRig.

Properties

camera

readonly camera: PerspectiveCamera;

The camera to drive.

eyeHeight?

readonly optional eyeHeight?: number;

Metres from the given position up to the eyes. Defaults to 1.7.

maxPitch?

readonly optional maxPitch?: number;

Pitch is clamped to plus or minus this, in radians.

FixedLoop

A driven fixed-step accumulator.

Properties

accumulator

readonly accumulator: number;

Unconsumed simulation time, always in [0, fixedDt) after a step.

alpha

readonly alpha: number;

Interpolation factor for the last frame, in [0, 1).

fixedDt

readonly fixedDt: number;

Length of one fixed step, in seconds.

frame

readonly frame: number;

Frames stepped so far.

maxSubsteps

readonly maxSubsteps: number;

Most fixed steps one frame may run.

timeScale

timeScale: number;

Simulation speed multiplier. 1 is real time, 0.5 is half speed, 0 pauses the simulation while frames keep rendering.

Scales how much simulation time a frame buys, not the step length: a fixed step is always fixedDt long, so physics and the game see the same dt at every speed and a recording replays at any speed. Negative values are treated as 0.

Methods

reset()

reset(): void;

Forget the accumulator and the baseline timestamp.

Call after a long pause (tab hidden, breakpoint, level load) so the next step starts clean instead of clamping.

Returns

void

step()

step(nowMs): FrameTiming;

Advance the loop to nowMs.

The very first call only establishes the baseline: dtReal is 0 and no fixed step runs, so a slow boot cannot manufacture a burst of simulation.

Parameters

Parameter	Type	Description
`nowMs`	`number`	A monotonic timestamp in milliseconds, usually from rAF.

Returns

FrameTiming

What this frame did. The same record every call; do not retain it.

FixedLoopOptions

Options accepted by createFixedLoop.

Properties

fixedDt?

readonly optional fixedDt?: number;

Length of one fixed step, in seconds. Defaults to 1/60.

fixedUpdate?

readonly optional fixedUpdate?: (dt) => void;

Run once per fixed step, always with exactly fixedDt.

Parameters

Parameter	Type	Description
`dt`	`number`	Always `fixedDt`, whatever `timeScale` is.

Returns

void

maxSubsteps?

readonly optional maxSubsteps?: number;

Most fixed steps one frame may run. Defaults to 5.

render?

readonly optional render?: (alpha) => void;

Run once per frame, last.

Parameters

Parameter	Type	Description
`alpha`	`number`	Interpolation factor in `[0, 1)`.

Returns

void

update?

readonly optional update?: (dtReal, alpha) => void;

Run once per frame, after the fixed steps.

Parameters

Parameter	Type	Description
`dtReal`	`number`	Clamped wall-clock seconds since the previous frame. Not scaled by `timeScale`; presentation code decides for itself.
`alpha`	`number`	Interpolation factor in `[0, 1)`.

Returns

void

FrameStats

A rolling window of frame durations.

Properties

capacity

readonly capacity: number;

Frames the window holds.

count

readonly count: number;

Samples recorded so far, capped at capacity.

fps

readonly fps: number;

Smoothed frames per second.

last

readonly last: number;

Duration of the most recent frame, in milliseconds.

Methods

percentile()

percentile(p): number;

A percentile of the window.

Parameters

Parameter	Type	Description
`p`	`number`	Percentile in `[0, 1]`; `0.5` is the median.

Returns

number

The frame time in milliseconds, or 0 before any sample.

push()

push(frameMs): void;

Record one frame.

Parameters

Parameter	Type	Description
`frameMs`	`number`	How long the frame took, in milliseconds.

Returns

void

reset()

reset(): void;

Forget every sample.

Returns

void

FrameTiming

What a call to FixedLoop.step did.

The loop hands back the same record every frame. Read it before the next step; never retain it.

Properties

alpha

readonly alpha: number;

Interpolation factor for rendering, always in [0, 1).

clamped

readonly clamped: boolean;

True when time had to be thrown away to avoid a death spiral.

dtReal

readonly dtReal: number;

Wall-clock seconds since the previous frame, after clamping.

rawDt

readonly rawDt: number;

Wall-clock seconds since the previous frame, before clamping.

substeps

readonly substeps: number;

Fixed steps run this frame, 0 to maxSubsteps.

ModuleRegistry

Holds modules, orders them, initialises them and takes them down again.

Properties

beginFrameHooks

readonly beginFrameHooks: readonly EngineModule[];

Modules implementing beginFrame, in run order.

endFrameHooks

readonly endFrameHooks: readonly EngineModule[];

Modules implementing endFrame, in run order.

fixedUpdateHooks

readonly fixedUpdateHooks: readonly EngineModule[];

Modules implementing fixedUpdate, in run order.

modules

readonly modules: readonly EngineModule[];

Registered modules in run order.

updateHooks

readonly updateHooks: readonly EngineModule[];

Modules implementing update, in run order.

Methods

disposeAll()

disposeAll(): void;

Dispose every initialised module in reverse order.

A throwing dispose is collected and rethrown at the end, so one bad module cannot strand the others.

Returns

void

get()

get<K>(id): EngineServices[K];

Look up a service, typed through EngineServices.

Type Parameters

Type Parameter
`K` extends `"physics"`

Parameters

Parameter	Type	Description
`id`	`K`	Service id.

Returns

EngineServices[K]

The service.

has()

has(id): boolean;

Whether a service is registered under an id.

Parameters

Parameter	Type	Description
`id`	`string`	Service id.

Returns

boolean

True when get would succeed.

initAll()

initAll(ctx): Promise<void>;

Initialise every module in order, awaiting each one.

Modules are initialised sequentially, not in parallel, because order is a dependency order: a module may ctx.get anything registered before it.

Parameters

Parameter	Type	Description
`ctx`	`EngineContext`	The host surface.

Returns

Promise<void>

Resolves once every module has initialised.

register()

register(module): void;

Add a module. Must happen before ModuleRegistry.initAll.

Parameters

Parameter	Type	Description
`module`	`EngineModule`	The module.

Returns

void

registerService()

registerService(id, service): void;

Publish a service under an id.

Parameters

Parameter	Type	Description
`id`	`string`	Service id.
`service`	`object`	The service object.

Returns

void

tryGet()

tryGet(id): unknown;

Look up a service without the typed table.

The escape hatch for code that does not know the id at compile time, and for core itself, which must not know what modules exist.

Parameters

Parameter	Type	Description
`id`	`string`	Service id.

Returns

unknown

The service, or undefined when nothing is registered.

MutableTime

The engine's own handle on the clock: the same object, writable.

Extends

Time

Properties

elapsed

elapsed: number;

Scaled seconds simulated since start().

Overrides

Time.elapsed

fixedDt

fixedDt: number;

Length of one fixed step, in seconds.

Overrides

Time.fixedDt

now

now: number;

performance.now() of the current frame, in milliseconds.

Overrides

Time.now

renderFrame

renderFrame: number;

Frames rendered since start(), starting at 0.

Rendered frames, not fixed steps: on a 144 Hz display this runs ahead of the simulation's own step counter, which the guest sees as its frame.

Overrides

Time.renderFrame

timeScale

timeScale: number;

Simulation speed multiplier. 0 pauses, 0.5 is half speed.

Changes how many fixed steps a frame buys, never how long a step is: a fixed step is always fixedDt.

Inherited from

Time.timeScale

PatchableAdapterPrototype

The parts of GPUAdapter the patch touches.

Methods

requestDevice()

requestDevice(descriptor?): Promise<GPUDevice>;

The method being wrapped.

Parameters

Parameter	Type	Description
`descriptor?`	`GPUDeviceDescriptor`	Device descriptor, as the caller wrote it.

Returns

Promise<GPUDevice>

The requested device.

ThirdPersonRig

A third-person orbit camera with a collision-aware spring arm.

Properties

actualDistance

readonly actualDistance: number;

Arm length actually used last frame, after collision.

camera

readonly camera: PerspectiveCamera;

The camera being driven.

collisionProbe

collisionProbe: CollisionProbe | null;

Obstacle probe. Assign to swap it at runtime, or null to disable collision.

distance

readonly distance: number;

Requested arm length, before collision.

pitch

readonly pitch: number;

Last applied pitch, in radians, after clamping.

pivotHeight

pivotHeight: number;

Height of the orbit pivot above the target.

yaw

readonly yaw: number;

Last applied yaw, in radians.

Methods

apply()

apply(): void;

Re-run the probe and reposition the camera with the current target and orbit.

Both setters call this; you only need it when the world changed but the inputs did not.

Returns

void

setOrbit()

setOrbit(
   yaw, 
   pitch, 
   distance
): void;

Set the orbit and apply the result.

Parameters

Parameter	Type	Description
`yaw`	`number`	Rotation about world +Y, in radians. `0` puts the camera on +Z.
`pitch`	`number`	Rotation above the horizon, in radians. Positive looks down at the target.
`distance`	`number`	Requested arm length, in metres.

Returns

void

setTarget()

setTarget(position): void;

Point the rig at a target and apply the result.

Parameters

Parameter	Type	Description
`position`	`Vector3Like`	The target's world position, at its feet.

Returns

void

setTargetAndOrbit()

setTargetAndOrbit(
   position, 
   yaw, 
   pitch, 
   distance
): void;

Set the target and the orbit together and apply once.

The per-frame entry point: one probe, one camera write, instead of the two that calling setTarget then setOrbit would cost.

Parameters

Parameter	Type	Description
`position`	`Vector3Like`	The target's world position, at its feet.
`yaw`	`number`	Rotation about world +Y, in radians.
`pitch`	`number`	Rotation above the horizon, in radians.
`distance`	`number`	Requested arm length, in metres.

Returns

void

ThirdPersonRigOptions

Options accepted by createThirdPersonRig.

Properties

camera

readonly camera: PerspectiveCamera;

The camera to drive.

collisionPadding?

readonly optional collisionPadding?: number;

Gap left between camera and obstacle. Defaults to 0.15.

collisionProbe?

readonly optional collisionProbe?: CollisionProbe;

Obstacle probe. Omit for a rig that never collides.

maxPitch?

readonly optional maxPitch?: number;

Pitch is clamped to plus or minus this, in radians.

minDistance?

readonly optional minDistance?: number;

Closest the arm may pull in. Defaults to 0.4.

pivotHeight?

readonly optional pivotHeight?: number;

Height of the orbit pivot above the target position. Defaults to 1.5.

Time

Read-only view of the engine clock, as modules and game code see it.

Extended by

MutableTime

Properties

elapsed

readonly elapsed: number;

Scaled seconds simulated since start().

fixedDt

readonly fixedDt: number;

Length of one fixed step, in seconds.

now

readonly now: number;

performance.now() of the current frame, in milliseconds.

renderFrame

readonly renderFrame: number;

Frames rendered since start(), starting at 0.

Rendered frames, not fixed steps: on a 144 Hz display this runs ahead of the simulation's own step counter, which the guest sees as its frame.

timeScale

timeScale: number;

Simulation speed multiplier. 0 pauses, 0.5 is half speed.

Changes how many fixed steps a frame buys, never how long a step is: a fixed step is always fixedDt.

Vector3Like

Anything with x, y and z. Avoids allocating a Vector3 per call.

Properties

x

readonly x: number;

X component.

y

readonly y: number;

Y component.

z

readonly z: number;

Z component.

WebGPUPatchOptions

Options accepted by initWebGPUPatches.

Properties

maxStorageBuffersPerShaderStage?

readonly optional maxStorageBuffersPerShaderStage?: number;

Storage buffers per shader stage to ask for.

The patch requests min(this, adapter.limits.maxStorageBuffersPerShaderStage), so asking for more than the adapter has is harmless. Defaults to DEFAULT_MAX_STORAGE_BUFFERS_PER_SHADER_STAGE.

target?

readonly optional target?: PatchableAdapterPrototype;

Prototype to patch. Defaults to the global GPUAdapter.prototype.

Tests pass a fake here; production never sets it.

timestampQuery?

readonly optional timestampQuery?: boolean;

Also request the timestamp-query feature when the adapter has it.

Needed to time GPU passes in the debug overlay and the benchmarks. Off by default, because the feature has a cost.

Type Aliases

CollisionProbe

type CollisionProbe = (from, to) => number | null;

Asks how far a ray gets before it hits something.

Parameters

Parameter	Type	Description
`from`	`Vector3Like`	Start of the ray, the orbit pivot.
`to`	`Vector3Like`	Where the camera would like to be.

Returns

number | null

Distance from from to the hit, in metres, or null for a clear line.

EventMap

type EventMap = object;

Shape of an event map: an interface mapping event name to payload type.

Deliberately object rather than Record<string, unknown>: interfaces have no implicit index signature, and the whole point of EngineEventMap is that packages declaration-merge into it.

Listener

type Listener<T> = (payload) => void;

A handler for one event.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`payload`	`T`

Returns

void

RendererBackend

type RendererBackend = "auto" | "webgpu" | "webgl";

Which three.js backend the renderer should target.

Variables

DEFAULT_COLLISION_PADDING

const DEFAULT_COLLISION_PADDING: 0.15 = 0.15;

Default gap left between the camera and whatever the probe hit, in metres.

DEFAULT_EYE_HEIGHT

const DEFAULT_EYE_HEIGHT: 1.7 = 1.7;

Default eye height above the feet, in metres.

DEFAULT_FIXED_DT

const DEFAULT_FIXED_DT: number;

Default simulation rate: 60 Hz.

DEFAULT_MAX_PITCH

const DEFAULT_MAX_PITCH: number;

Default pitch limit: just short of straight up or down, in radians.

DEFAULT_MAX_STORAGE_BUFFERS_PER_SHADER_STAGE

const DEFAULT_MAX_STORAGE_BUFFERS_PER_SHADER_STAGE: 10 = 10;

Storage buffers per shader stage the engine asks for. The WebGPU default is 8.

DEFAULT_MAX_SUBSTEPS

const DEFAULT_MAX_SUBSTEPS: 5 = 5;

Default cap on fixed steps per frame.

DEFAULT_MIN_DISTANCE

const DEFAULT_MIN_DISTANCE: 0.4 = 0.4;

Default closest the arm may pull in, in metres.

DEFAULT_OVERLAY_HOTKEY

const DEFAULT_OVERLAY_HOTKEY: "F3" = 'F3';

KeyboardEvent.code that toggles the panel.

DEFAULT_OVERLAY_INTERVAL_MS

const DEFAULT_OVERLAY_INTERVAL_MS: 250 = 250;

How often the panel's text is rewritten, in milliseconds.

DEFAULT_PIVOT_HEIGHT

const DEFAULT_PIVOT_HEIGHT: 1.5 = 1.5;

Default height of the orbit pivot above the target, in metres.

DEFAULT_PIXEL_RATIO_CAP

const DEFAULT_PIXEL_RATIO_CAP: 2 = 2;

Default upper bound on devicePixelRatio.

DEFAULT_SAMPLE_COUNT

const DEFAULT_SAMPLE_COUNT: 120 = 120;

Frames kept in the window by default: two seconds at 60 Hz.

DEFAULT_TRANSFORM_CAPACITY

const DEFAULT_TRANSFORM_CAPACITY: 256 = 256;

Default number of entity slots a new store reserves.

NO_ENTITY

const NO_ENTITY: 0 = 0;

The entity id that means "no entity"; also the id of the root group.

PACKAGE

const PACKAGE: "@aosengine/core";

Package identity marker.

Example

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

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

Functions

candleFlicker()

function candleFlicker(seconds, index): number;

Deterministic, continuous candle gain in [0.58, 1.2], with a steady core and shallow draught dips.

Parameters

Parameter	Type	Description
`seconds`	`number`	Elapsed scene time in seconds.
`index`	`number`	Stable fixture seed; different fixtures flicker independently.

Returns

number

Intensity multiplier; no random state or frame allocation.

Example

light.intensity = 2.6 * candleFlicker(elapsed, 3);

createDebugOverlay()

function createDebugOverlay(options): DebugOverlay;

Build the debug overlay.

On a host with no document — Node, a worker, a test — this returns a working overlay whose element is null: the statistics still accumulate and can be read, nothing is mounted, and nothing throws.

Parameters

Parameter	Type	Description
`options`	`DebugOverlayOptions`	Renderer, backend label and panel settings.

Returns

DebugOverlay

The overlay.

Example

import { createDebugOverlay } from '@aosengine/core';
import { WebGPURenderer } from 'three/webgpu';

const renderer = new WebGPURenderer({ canvas: document.createElement('canvas') });
const overlay = createDebugOverlay({ renderer, backendName: 'webgpu' });
overlay.sample(16.6, performance.now()); // call once per frame

createEngine()

function createEngine(options): Promise<Engine>;

Boot an engine around a canvas.

Parameters

Parameter	Type	Description
`options`	`CreateEngineOptions`	Canvas, manifest, modules, loop rate and renderer settings.

Returns

Promise<Engine>

The booted engine. The loop is not running; call start().

Example

import { createEngine } from '@aosengine/core';

const canvas = document.querySelector('canvas')!;
const engine = await createEngine({
  canvas,
  manifest: '/assets/assets.json',
  modules: [],
  fixedHz: 60,
  renderer: { backend: 'auto' },
  debug: import.meta.env?.DEV === true,
});
engine.start();

createEvents()

function createEvents<M>(): Events<M>;

Build a typed event bus.

The type parameter is the event map. Packages extend the engine's map by declaration-merging into EngineEventMap; standalone buses pass their own.

Type Parameters

Type Parameter
`M` extends `object`

Returns

Events<M>

An empty bus.

Example

import { createEvents } from '@aosengine/core';

const events = createEvents<{ hit: { damage: number } }>();
const off = events.on('hit', (e) => console.log(e.damage));
events.emit('hit', { damage: 7 }); // logs 7
off();

createFirstPersonRig()

function createFirstPersonRig(options): FirstPersonRig;

Build a first-person rig.

The camera's Euler order is set to YXZ once, which is what makes yaw and pitch independent: yaw always turns about world up, pitch always about the camera's own right, and there is no roll.

Parameters

Parameter	Type	Description
`options`	`FirstPersonRigOptions`	Camera, eye height and pitch limit.

Returns

FirstPersonRig

The rig.

Example

import { createFirstPersonRig } from '@aosengine/core';
import { PerspectiveCamera } from 'three/webgpu';

const rig = createFirstPersonRig({ camera: new PerspectiveCamera(), eyeHeight: 1.7 });
rig.setPose({ x: 0, y: 0, z: 0 }, Math.PI, 0);
console.log(rig.camera.position.y); // 1.7

createFixedLoop()

function createFixedLoop(options?): FixedLoop;

Build a fixed-step loop.

The accumulator drains at most maxSubsteps times per frame. Anything left over is thrown away rather than carried, because carrying it is what turns a slow frame into a spiral of death: each frame owes more simulation than the last and the game never catches up. clamped in the returned FrameTiming says when that happened.

Parameters

Parameter	Type	Description
`options`	`FixedLoopOptions`	Step length, substep cap and the three callbacks.

Returns

FixedLoop

The loop. Nothing runs until you call step.

Example

import { createFixedLoop } from '@aosengine/core';

let ticks = 0;
const loop = createFixedLoop({ fixedUpdate: () => { ticks += 1; } });
loop.step(0);      // baseline: no fixed steps
loop.step(1000/30); // 33.3 ms buys two 60 Hz steps
console.log(ticks); // 2

createFpsCounter()

function createFpsCounter(engine, value): () => void;

Count rendered frames in a supplied HUD element; update twice a second. Resets on tab visibility changes and returns an idempotent cleanup callback. The caller owns markup and styling; no overlay is created unless requested.

Parameters

Parameter	Type	Description
`engine`	`Pick`<`EngineContext`, `"events"`>	Host event source.
`value`	`HTMLElement`	Element displaying only the numeric FPS value.

Returns

Cleanup callback; call when disposing the owning module.

() => void

Example

const dispose = createFpsCounter(engine, document.querySelector('#fps-value')!);

createFrameStats()

function createFrameStats(capacity?): FrameStats;

Build a frame-time window.

Parameters

Parameter	Type	Default value	Description
`capacity`	`number`	`DEFAULT_SAMPLE_COUNT`	Frames to keep. Defaults to `120`.

Returns

FrameStats

An empty window.

Example

import { createFrameStats } from '@aosengine/core';

const stats = createFrameStats(4);
for (const ms of [10, 20, 30, 40]) stats.push(ms);
console.log(stats.percentile(0.5)); // 20

createModuleRegistry()

function createModuleRegistry(): ModuleRegistry;

Build a module registry.

Returns

ModuleRegistry

An empty registry.

Example

import { createModuleRegistry } from '@aosengine/core';

const registry = createModuleRegistry();
registry.register({ id: 'clock', order: -10, init: () => ({ t: 0 }), dispose: () => {} });
console.log(registry.modules[0]?.id); // 'clock'

createThirdPersonRig()

function createThirdPersonRig(options): ThirdPersonRig;

Build a third-person rig.

Parameters

Parameter	Type	Description
`options`	`ThirdPersonRigOptions`	Camera, pivot height, arm limits and the collision probe.

Returns

ThirdPersonRig

The rig.

Example

import { createThirdPersonRig } from '@aosengine/core';
import { PerspectiveCamera } from 'three/webgpu';

const rig = createThirdPersonRig({ camera: new PerspectiveCamera(), pivotHeight: 1.5 });
rig.setTarget({ x: 0, y: 0, z: 0 });
rig.setOrbit(0, 0, 4);
console.log(rig.camera.position.z); // 4

createTime()

function createTime(fixedDt): MutableTime;

Build an engine clock.

Parameters

Parameter	Type	Description
`fixedDt`	`number`	Length of one fixed step, in seconds.

Returns

MutableTime

A clock at render frame 0, elapsed 0, timeScale 1.

Example

import { createTime } from '@aosengine/core';

const time = createTime(1 / 60);
time.timeScale = 0.5; // slow motion
console.log(time.fixedDt); // 0.016666…

initWebGPUPatches()

function initWebGPUPatches(options?): boolean;

Patch GPUAdapter.prototype.requestDevice so every device the page creates clears the engine's limits.

Idempotent. Calling it again does not wrap the method twice; it raises the requested limits if the new call asks for more. Safe to call on a host with no WebGPU at all, where it does nothing and returns false.

Must run before renderer.init(), and before anything else creates a device.

Parameters

Parameter	Type	Description
`options`	`WebGPUPatchOptions`	Limits to request, and the prototype to patch.

Returns

boolean

True when the patch is installed, false when the host has no WebGPU.

Example

import { initWebGPUPatches } from '@aosengine/core';
import { WebGPURenderer } from 'three/webgpu';

initWebGPUPatches({ maxStorageBuffersPerShaderStage: 10 });
const renderer = new WebGPURenderer({ canvas: document.createElement('canvas') });
await renderer.init();

isWebGPUBackend()

function isWebGPUBackend(renderer): boolean;

Whether a renderer ended up on a real WebGPU backend.

three sets isWebGPUBackend on WebGPUBackend and isWebGLBackend on the fallback, but neither class is exported from three/webgpu, so this is a duck-type check rather than an instanceof.

Parameters

Parameter	Type	Description
`renderer`	`WebGPURenderer`	An initialised renderer.

Returns

boolean

True on WebGPU, false on the WebGL fallback.

Example

import { isWebGPUBackend } from '@aosengine/core';
import { WebGPURenderer } from 'three/webgpu';

const renderer = new WebGPURenderer({ canvas: document.createElement('canvas') });
await renderer.init();
console.log(isWebGPUBackend(renderer));

isWebGPUPatched()

function isWebGPUPatched(target?): boolean;

Whether a prototype already carries the patch.

Parameters

Parameter	Type	Description
`target?`	`PatchableAdapterPrototype`	Prototype to check. Defaults to the global `GPUAdapter.prototype`.

Returns

boolean

True when initWebGPUPatches has run against it.

Example

import { initWebGPUPatches, isWebGPUPatched } from '@aosengine/core';

initWebGPUPatches();
console.log(isWebGPUPatched()); // true in a browser with WebGPU

resolveEngineConfig()

function resolveEngineConfig(options?): EngineConfig;

Apply the documented defaults to the engine options.

Exported for the unit tests; createEngine is the real entry point.

Parameters

Parameter	Type	Description
`options`	`Omit`<`CreateEngineOptions`, `"canvas"`>	Options as the caller wrote them.

Returns

EngineConfig

The resolved configuration.

Example

import { resolveEngineConfig } from '@aosengine/core';

const config = resolveEngineConfig({ fixedHz: 120 });
console.log(config.fixedDt); // 0.008333…

@aosengine/core ​

Classes ​

ModuleError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

Properties ​

moduleId ​

SceneGraph ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Properties ​

root ​

scene ​

Accessors ​

size ​

Get Signature ​

Returns ​

Methods ​

despawn() ​

Parameters ​

Returns ​

dispose() ​

Returns ​

get() ​

Parameters ​

Returns ​

idOf() ​

Parameters ​

Returns ​

ids() ​

Returns ​

setParent() ​

Parameters ​

Returns ​

spawn() ​

Parameters ​

Returns ​

Example ​

TransformStore ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Accessors ​

capacity ​

Get Signature ​

Returns ​

highWater ​

Get Signature ​

Returns ​

Methods ​

clear() ​

Parameters ​

Returns ​

commit() ​

Returns ​

ensure() ​

Parameters ​

Returns ​

getPosition() ​

Parameters ​

Returns ​

getQuaternion() ​

Parameters ​

Returns ​

has() ​

Parameters ​

Returns ​

isDirty() ​

Parameters ​

Returns ​

set() ​

Parameters ​

Returns ​

@aosengine/core

Classes

ModuleError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

moduleId

SceneGraph

Constructors

Constructor

Parameters

Returns

Properties

root

scene

Accessors

size

Get Signature

Returns

Methods

despawn()

Parameters

Returns

dispose()

Returns

get()

Parameters

Returns

idOf()

Parameters

Returns

ids()

Returns

setParent()

Parameters

Returns

spawn()

Parameters

Returns

Example

TransformStore

Constructors

Constructor

Parameters

Returns

Accessors

capacity

Get Signature

Returns

highWater

Get Signature

Returns

Methods

clear()

Parameters

Returns

commit()

Returns

ensure()

Parameters

Returns

getPosition()

Parameters

Returns

getQuaternion()

Parameters

Returns

has()

Parameters

Returns

isDirty()

Parameters

Returns

set()

Parameters

Returns