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:676

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:604

Returns

boolean

pipeline

Get Signature

get pipeline(): RenderPipeline | null

Defined in: app/app.ts:579

Returns

RenderPipeline | null

sideModules

Get Signature

get sideModules(): SideModuleHost | null

Defined in: app/app.ts:232

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:587

Returns

Promise<unknown> | undefined

Set Signature

set spineInitPromise(p): void

Defined in: app/app.ts:591

Parameters

p

Promise<unknown> | undefined

Returns

void

subsystems

Get Signature

get subsystems(): SubsystemRegistry

Defined in: app/app.ts:225

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:613

Returns

World

Methods

addEvent()

addEvent<T>(event): this

Defined in: app/app.ts:305

Type Parameters

T

T

Parameters

event

EventDef<T>

Returns

this

addPlugin()

addPlugin(plugin): this

Defined in: app/app.ts:248

Parameters

plugin

Plugin

Returns

this

addPlugins()

addPlugins(plugins): this

Defined in: app/app.ts:240

Parameters

plugins

Plugin[]

Returns

this

addStartupSystem()

addStartupSystem(system): this

Defined in: app/app.ts:406

Parameters

system

SystemDef

Returns

this

addSystem()

addSystem(system): this

Defined in: app/app.ts:376

Parameters

system

SystemDef

Returns

this

addSystemSet()

addSystemSet(set): this

Defined in: app/app.ts:526

Shortcut for addSystemSetToSchedule(Schedule.Update, set).

Parameters

set

SystemSet

Returns

this

addSystemSetToSchedule()

addSystemSetToSchedule(schedule, set): this

Defined in: app/app.ts:492

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:353

Register system onto schedule. Ordering given here is added to whatever the definition already declared, so a system can carry its own edges and still be constrained further at the registration site.

Parameters

schedule

Schedule

system

SystemDef

options?

runAfter?

string[]

runBefore?

string[]

runIf?

RunCondition

Returns

this

enableStats()

enableStats(): this

Defined in: app/app.ts:754

Returns

this

getEntityCount()

getEntityCount(): number

Defined in: app/app.ts:852

Returns

number

getFixedTimestep()

getFixedTimestep(): number

Defined in: app/app.ts:693

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

Returns

number

getFrameCosts()

getFrameCosts(): FrameCosts | null

Defined in: app/app.ts:788

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:776

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

getPhaseTimings()

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

Defined in: app/app.ts:766

Returns

ReadonlyMap<string, number> | null

getPlaySpeed()

getPlaySpeed(): number

Defined in: app/app.ts:746

Returns

number

getPlugin()

getPlugin<T>(ctor): T | undefined

Defined in: app/app.ts:218

Type Parameters

T

T extends Plugin

Parameters

ctor

(…args) => T

Returns

T | undefined

getRegisteredResourceNames()

getRegisteredResourceNames(): string[]

Defined in: app/app.ts:886

Returns

string[]

getResource()

getResource<T>(resource): T

Defined in: app/app.ts:865

Type Parameters

T

T

Parameters

resource

ResourceDef<T>

Returns

T

getResourceByName()

getResourceByName(name): unknown

Defined in: app/app.ts:873

Parameters

name

string

Returns

unknown

getResourceChangeTick()

getResourceChangeTick(name): number

Defined in: app/app.ts:881

Parameters

name

string

Returns

number

getSystemTimings()

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

Defined in: app/app.ts:762

Returns

ReadonlyMap<string, number> | null

getTargetFrameRate()

getTargetFrameRate(): number

Defined in: app/app.ts:742

Returns

number

hasResource()

hasResource<T>(resource): boolean

Defined in: app/app.ts:869

Type Parameters

T

T

Parameters

resource

ResourceDef<T>

Returns

boolean

hotSwapSystems()

hotSwapSystems(incoming): boolean

Defined in: app/app.ts:423

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:860

Type Parameters

T

T

Parameters

resource

ResourceDef<T>

value

T

Returns

this

installCompiledSystems()

installCompiledSystems(source, manifest): Promise<number>

Defined in: app/app.ts:923

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>

isPaused()

isPaused(): boolean

Defined in: app/app.ts:726

Returns

boolean

measureFrameScope()

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

Defined in: app/app.ts:819

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:707

Parameters

handler

(error, systemName) => void

Returns

this

onFrameEnd()

onFrameEnd(fn): () => void

Defined in: app/app.ts:844

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:712

Parameters

handler

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

Returns

this

onWasmError()

onWasmError(handler): this

Defined in: app/app.ts:717

Parameters

handler

(error, context) => void

Returns

this

quit()

quit(options?): void

Defined in: app/app.ts:1084

Parameters

options?

keepRenderer?

boolean

Returns

void

registerScene()

registerScene(config): this

Defined in: app/app.ts:894

Parameters

config

SceneConfig

Returns

this

removeSystem()

removeSystem(systemId): boolean

Defined in: app/app.ts:530

Parameters

systemId

symbol

Returns

boolean

run()

run(): Promise<void>

Defined in: app/app.ts:1038

Returns

Promise<void>

scheduleAmbiguities()

scheduleAmbiguities(schedule): Ambiguity[]

Defined in: app/app.ts:1365

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:1377

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:687

Parameters

timestep

number

Returns

this

setInitialScene()

setInitialScene(name): this

Defined in: app/app.ts:899

Parameters

name

string

Returns

this

setMaxDeltaTime()

setMaxDeltaTime(v): this

Defined in: app/app.ts:697

Parameters

v

number

Returns

this

setMaxFixedSteps()

setMaxFixedSteps(v): this

Defined in: app/app.ts:702

Parameters

v

number

Returns

this

setPaused()

setPaused(paused): void

Defined in: app/app.ts:722

Parameters

paused

boolean

Returns

void

setPipeline()

setPipeline(pipeline): void

Defined in: app/app.ts:583

Parameters

pipeline

RenderPipeline

Returns

void

setPlaySpeed()

setPlaySpeed(speed): void

Defined in: app/app.ts:734

Parameters

speed

number

Returns

void

setSideModules()

setSideModules(host): void

Defined in: app/app.ts:236

Parameters

host

SideModuleHost

Returns

void

setTargetFrameRate()

setTargetFrameRate(fps): void

Defined in: app/app.ts:738

Parameters

fps

number

Returns

void

stepFrame()

stepFrame(): void

Defined in: app/app.ts:730

Returns

void

stepFrames()

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

Defined in: app/app.ts:1015

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:992

Parameters

delta

number

Returns

Promise<void>

useCompiledSystems()

useCompiledSystems(opts): Promise<void>

Defined in: app/app.ts:625

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.