App

Accessors

compiledSystemCount

Get Signature

get compiledSystemCount(): number

How many compiled twins this App runs. Zero unless a build installed some, which is the whole of the mode policy — and the one number that tells a shipped AOT build apart from a shipped interpreted one from outside.

Returns

number

compiledSystems

Get Signature

get compiledSystems(): object

Defined in: app/app.ts:819

Which systems this App is running compiled, and how many twin calls have happened. installed without calls rising means the module loaded and nothing dispatched to it — which no differential can report, because the closure it replaced computes the same answer.

Returns

object

calls

readonly calls: number

installed

readonly installed: readonly string[]

isPhysicsReady

Get Signature

get isPhysicsReady(): boolean

Defined in: app/app.ts:708

Returns

boolean

pipeline

Get Signature

get pipeline(): RenderPipeline | null

Defined in: app/app.ts:683

Returns

RenderPipeline | null

sideModules

Get Signature

get sideModules(): SideModuleHost | null

Defined in: app/app.ts:269

The realm’s optional-native-module acquirer (physics, spine). Physics and spine pull their wasm from here, so a realm wires its transport once (fetch / inlined / WeChat) and every subsystem follows.

Returns

SideModuleHost | null

spineInitPromise

Get Signature

get spineInitPromise(): Promise<unknown> | undefined

Defined in: app/app.ts:691

Returns

Promise<unknown> | undefined

Set Signature

set spineInitPromise(p): void

Defined in: app/app.ts:695

Parameters

p

Promise<unknown> | undefined

Returns

void

subsystems

Get Signature

get subsystems(): SubsystemRegistry

Defined in: app/app.ts:262

Subsystem lifecycle registry (“which modules loaded/ready/stepping/errored”). Named plugins auto-register in addPlugin; async plugins (physics) drive their own initializing→ready/error transitions.

Returns

SubsystemRegistry

world

Get Signature

get world(): World

Defined in: app/app.ts:717

Returns

World

Methods

addEvent()

addEvent<T>(event): this

Defined in: app/app.ts:368

Type Parameters

T

T

Parameters

event

EventDef<T>

Returns

this

addPlugin()

addPlugin(plugin): this

Defined in: app/app.ts:285

Parameters

plugin

Plugin

Returns

this

addPlugins()

addPlugins(plugins): this

Defined in: app/app.ts:277

Parameters

plugins

Plugin[]

Returns

this

addStartupSystem()

addStartupSystem(system): this

Defined in: app/app.ts:487

Parameters

system

SystemDef

Returns

this

addSystem()

addSystem(system): this

Defined in: app/app.ts:457

Parameters

system

SystemDef

Returns

this

addSystemSet()

addSystemSet(set): this

Defined in: app/app.ts:611

Shortcut for addSystemSetToSchedule(Schedule.Update, set).

Parameters

set

SystemSet

Returns

this

addSystemSetToSchedule()

addSystemSetToSchedule(schedule, set): this

Defined in: app/app.ts:573

Register every system in set onto schedule. Each member gets the set’s runIf, and the set’s runBefore / runAfter edges on top of any it declared itself; members keep the order they were listed in. Other systems may reference the set’s name in their own ordering, and the scheduler expands those references to every member.

Parameters

schedule

Schedule

set

SystemSet

Returns

this

addSystemToSchedule()

addSystemToSchedule(schedule, system, options?): this

Defined in: app/app.ts:416

Register system onto schedule, adding ordering to its declared edges. profileDomain attributes systems registered after an async plugin build returns; otherwise the current build context supplies it.

Parameters

schedule

Schedule

system

SystemDef

options?

profileDomain?

string

runAfter?

string[]

runBefore?

string[]

runIf?

RunCondition

Returns

this

enableStats()

enableStats(): this

Defined in: app/app.ts:899

Returns

this

getEntityCount()

getEntityCount(): number

Defined in: app/app.ts:1002

Returns

number

getFixedTimestep()

getFixedTimestep(): number

Defined in: app/app.ts:836

The fixed-update timestep (seconds) — the FixedUpdate / physics cadence.

Returns

number

getFrameCosts()

getFrameCosts(): FrameCosts | null

Defined in: app/app.ts:938

This frame’s costs with the attribution a profile tree needs: which domain owns each system, which system each scope ran inside. Null when stats are off. Feed to buildFrameProfile, which is where the tree is derived.

Returns

FrameCosts | null

getFrameScopes()

getFrameScopes(): ReadonlyMap<string, number> | null

Defined in: app/app.ts:926

Sub-frame CPU scopes recorded this frame via measureFrameScope — the finer breakdown within a single system, keyed by scope name. Null when stats aren’t enabled. Sibling of getSystemTimings / getPhaseTimings; surfaces as the profiler’s js.* rows.

Returns

ReadonlyMap<string, number> | null

getFrameTiming()

getFrameTiming(): Readonly<{ frameMs: number; seq: number; }> | null

Defined in: app/app.ts:916

Completed frame interval before simulation speed or delta clamping.

Returns

Readonly<{ frameMs: number; seq: number; }> | null

getPhaseTimings()

getPhaseTimings(): ReadonlyMap<string, number> | null

Defined in: app/app.ts:911

Returns

ReadonlyMap<string, number> | null

getPlaySpeed()

getPlaySpeed(): number

Defined in: app/app.ts:891

Returns

number

getPlugin()

getPlugin<T>(ctor): T | undefined

Defined in: app/app.ts:255

Type Parameters

T

T extends Plugin

Parameters

ctor

new (…args) => T

Returns

T | undefined

getRegisteredResourceNames()

getRegisteredResourceNames(): string[]

Defined in: app/app.ts:1036

Returns

string[]

getResource()

getResource<T>(resource): T

Defined in: app/app.ts:1015

Type Parameters

T

T

Parameters

resource

ResourceDef<T>

Returns

T

getResourceByName()

getResourceByName(name): unknown

Defined in: app/app.ts:1023

Parameters

name

string

Returns

unknown

getResourceChangeTick()

getResourceChangeTick(name): number

Defined in: app/app.ts:1031

Parameters

name

string

Returns

number

getResourceEntries()

getResourceEntries(): [string, unknown][]

Defined in: app/app.ts:1045

Every resource this app holds, as [name, value] — what an inspector shows. Includes the slots only a read has materialised, which getRegisteredResourceNames (insert-only) does not.

Returns

[string, unknown][]

getSystemTimings()

getSystemTimings(): ReadonlyMap<string, number> | null

Defined in: app/app.ts:907

Returns

ReadonlyMap<string, number> | null

getTargetFrameRate()

getTargetFrameRate(): number

Defined in: app/app.ts:887

Returns

number

hasResource()

hasResource<T>(resource): boolean

Defined in: app/app.ts:1019

Type Parameters

T

T

Parameters

resource

ResourceDef<T>

Returns

boolean

holdExecution()

holdExecution(): () => void

Defined in: app/app.ts:1186

Hold frame execution without changing the game’s own pause state.

Returns

() => void

hotSwapSystems()

hotSwapSystems(incoming): boolean

Defined in: app/app.ts:504

Hot-swap the project’s (user-authored) system function bodies in place, keeping the live World/Registry/entities — the state-preserving hot-reload fast path (RC10 P3). incoming is the freshly re-imported bundle’s drained systems.

Returns false when the structure changed — a user system was added, removed, or renamed, or a schedule’s user-system count differs — because the running systems then no longer line up with the new code, so the caller must full-reload instead. Builtin/plugin systems (those with an owning subsystem) are never touched. The match validates fully before mutating, so a rejected swap leaves the scheduler untouched (no torn half-swap). Component identity is stable by name (see component.ts), so the new functions’ queries resolve to the live storage.

Parameters

incoming

readonly object[]

Returns

boolean

insertResource()

insertResource<T>(resource, value): this

Defined in: app/app.ts:1010

Type Parameters

T

T

Parameters

resource

ResourceDef<T>

value

T

Returns

this

installCompiledSystems()

installCompiledSystems(source, manifest): Promise<number>

Defined in: app/app.ts:1082

Install the compiled twins a build produced, and answer how many (docs/REARCH_AOT.md §9). Call it BEFORE any component exists — a twin reads rows in the ENGINE’s memory, and refuses rather than move rows already allocated elsewhere, or trust a module built for other offsets.

Parameters

source

string | BufferSource

manifest

AotManifest

Returns

Promise<number>

isExecutionHeld()

isExecutionHeld(): boolean

Defined in: app/app.ts:1213

Returns

boolean

isPaused()

isPaused(): boolean

Defined in: app/app.ts:869

Returns

boolean

measureFrameScope()

measureFrameScope<T>(name, fn, options?): T

Defined in: app/app.ts:969

Time fn as a named sub-frame scope (accumulated if the name repeats in a frame). A no-op passthrough when stats are off, so shipped games pay only a single branch. Use it to split a heavy system into attributable pieces.

remainder: 'wait' declares that whatever time is left under this scope once its native scopes are subtracted is CPU blocked, not work — the swapchain block a GPU submit absorbs, or an await. The profiler keeps such time out of every cost total instead of reporting it as a hotspot.

Type Parameters

T

T

Parameters

name

string

fn

() => T

options?

remainder?

ScopeRemainder

Returns

T

onError()

onError(handler): this

Defined in: app/app.ts:850

Parameters

handler

(error, systemName) => void

Returns

this

onExecutionChange()

onExecutionChange(callback): () => void

Defined in: app/app.ts:1216

Observe execution holds, including the initial state. Media/timer owners can cooperate here.

Parameters

callback

(held) => void

Returns

() => void

onFrameEnd()

onFrameEnd(fn): () => void

Defined in: app/app.ts:994

Observe the end of every frame, once its systems have run and its timings are final. Returns a disposer.

A broadcast, not a slot: a recorder and a game’s own budget alarm both watch without either taking the hook from the other.

Parameters

fn

(dtMs) => void

Returns

() => void

onSystemError()

onSystemError(handler): this

Defined in: app/app.ts:855

Parameters

handler

(error, systemName?) => "pause" | "continue"

Returns

this

onWasmError()

onWasmError(handler): this

Defined in: app/app.ts:860

Parameters

handler

(error, context) => void

Returns

this

quit()

quit(options?): void

Defined in: app/app.ts:1374

Parameters

options?

keepRenderer?

boolean

Returns

void

registerScene()

registerScene(config): this

Defined in: app/app.ts:1053

Parameters

config

SceneConfig

Returns

this

removeSystem()

removeSystem(systemId): boolean

Defined in: app/app.ts:615

Parameters

systemId

symbol

Returns

boolean

run()

run(): Promise<void>

Defined in: app/app.ts:1290

Returns

Promise<void>

scheduleAmbiguities()

scheduleAmbiguities(schedule): Ambiguity[]

Defined in: app/app.ts:1692

Pairs of systems in schedule that touch the same data with nothing saying which runs first, so their order is whatever registration and the sort happened to produce.

Parameters

schedule

Schedule

Returns

Ambiguity[]

scheduleBatches()

scheduleBatches(schedule): string[][]

Defined in: app/app.ts:1704

schedule grouped into batches that could run at the same time — how much of it is inherently sequential. A measurement: the schedule starts systems in sorted order, overlapping only what awaits. See parallelBatches.

Parameters

schedule

Schedule

Returns

string[][]

setFixedTimestep()

setFixedTimestep(timestep): this

Defined in: app/app.ts:830

Parameters

timestep

number

Returns

this

setInitialScene()

setInitialScene(name): this

Defined in: app/app.ts:1058

Parameters

name

string

Returns

this

setMaxDeltaTime()

setMaxDeltaTime(v): this

Defined in: app/app.ts:840

Parameters

v

number

Returns

this

setMaxFixedSteps()

setMaxFixedSteps(v): this

Defined in: app/app.ts:845

Parameters

v

number

Returns

this

setPaused()

setPaused(paused): void

Defined in: app/app.ts:865

Parameters

paused

boolean

Returns

void

setPipeline()

setPipeline(pipeline): void

Defined in: app/app.ts:687

Parameters

pipeline

RenderPipeline

Returns

void

setPlaySpeed()

setPlaySpeed(speed): void

Defined in: app/app.ts:878

Parameters

speed

number

Returns

void

setSideModules()

setSideModules(host): void

Defined in: app/app.ts:273

Parameters

host

SideModuleHost

Returns

void

setTargetFrameRate()

setTargetFrameRate(fps): void

Defined in: app/app.ts:882

Parameters

fps

number

Returns

void

stepFrame()

stepFrame(): void

Defined in: app/app.ts:873

Returns

void

stepFrames()

stepFrames(frames?, dt?): Promise<void>

Defined in: app/app.ts:1254

Advance exactly frames frames of exactly dt seconds, with the rAF loop held off for the duration — “let the game run a bit”, made reproducible.

The loop it replaces is wall-clock and browser-scheduled: a backgrounded tab is throttled to about one frame a second, so an observer that steps by waiting sees a frozen game and concludes the game is broken. Worse, there was no other door — a driver that needed the next 30 frames of simulation had to reach for runFrame_, and reaching for a private method is a thing that keeps working until the day it doesn’t.

A PAUSED app still steps here: advancing frame by frame is exactly what stepping a paused game means. The pause (and the loop) are restored afterwards, with the clock re-based so the first resumed frame is not handed the whole excursion as its delta.

Parameters

frames?

number = 1

dt?

number = ...

Returns

Promise<void>

tick()

tick(delta): Promise<void>

Defined in: app/app.ts:1174

Parameters

delta

number

Returns

Promise<void>

useCompiledSystems()

useCompiledSystems(opts): Promise<void>

Defined in: app/app.ts:729

Run the compiled twins a build produced instead of the systems’ closures. Call it BEFORE the world has any pooled component: the rows must be in the memory the module reads. Refuses rather than degrades — a module built for other offsets reads a different field, which is not an error.