A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file app.ts
* @brief Application builder and web platform integration
*/
import { World } from '../ecs/world';
import { applyAppOptions, applyColorSpace, applyFrameOptions } from './renderOptions';
import type { QualityConfig } from '../render/quality';
import { Schedule, SystemDef, SystemRunner, SystemSet, mergeOrderingEdges, rescopeSystem, type RunCondition } from '../ecs/system';
import { builtinResource, declaredResource, ResourceStorage, Time, TimeData, type ResourceDef } from '../ecs/resource';
import { Speculation, SpeculationInstance } from '../ecs/speculation';
import { prepareAot, type AotHost } from '../ecs/aot/installAot';
import { installNativeAot, nativeAotBindings } from '../ecs/aot/installNativeAot';
import { createNativeHeap } from '../ecs/bridge/nativeHeap';
import type { AotManifest } from '../ecs/aot/AotSystems';
import type { AotRuntime } from '../ecs/aot/AotRuntime';
import { EventRegistry, eventNamed, type EventDef } from '../ecs/event';
import type { ESEngineModule, CppRegistry } from '../wasm';
import type { OutputTransform } from '../postprocess';
import type { BridgeConnectOptions } from '../ecs/bridge/BuiltinBridge';
import { UICameraInfo } from '../ui/core/ui-camera-info';
import { ScreenLayout } from '../ui/core/screen-layout';
import { ScreenOverlay, defaultScreenOverlay } from '../ui/core/screen-overlay';
import { inputPlugin, Input, setInputExecutionHeld } from '../input/input';
import { assetPlugin } from '../asset';
import { prefabsPlugin } from '../prefab/prefabServer';
import { breakablePlugin } from '../breakable/breakable';
import { setWasmErrorHandler } from '../wasm/wasmError';
import { corePlugin, DEFAULT_UI_CAMERA_INFO } from './corePlugin';
import {
ancestors,
dependencyEdges,
detectAmbiguities,
parallelBatches,
type Ambiguity,
type ResolveTargets,
} from './ambiguity';
import { accessOf, conflicts, type SystemAccess } from './access';
import { platformNow } from '../platform';
import { RenderPipeline } from '../render/renderPipeline';
import type { SceneConfig } from '../scene/sceneManager';
import { SceneManager } from '../scene/sceneManager';
import { sceneManagerPlugin } from '../scene/scenePlugin';
import { getDefaultContext } from '../ecs/context';
import { seedEngineComponents, type AnyComponentDef } from '../ecs/component';
import { cameraPlugin } from '../camera/CameraPlugin';
import type { ScreenScalingData } from '../camera/ScreenScaling';
import { Physics2DRuntime } from '../physics/Physics2DRuntime';
import { SubsystemRegistry } from './subsystems';
import { DOMAIN_SCRIPTS, DOMAIN_UNATTRIBUTED, type ScopeCost, type ScopeRemainder, type SystemCost } from './frameProfile';
import type { SideModuleHost } from '../sideModules/host';
import { watchWebGPUDeviceLoss } from '../render/renderer';
import { log } from '../util/logger';
const hostPauseOwners = new WeakMap<App, Set<object>>();
/** Internal host pause ownership, independent of the game's setPaused intent. */
export function setAppHostPaused(app: App, owner: object, paused: boolean): void {
if (paused) {
let owners = hostPauseOwners.get(app);
if (!owners) hostPauseOwners.set(app, owners = new Set());
owners.add(owner);
} else {
const owners = hostPauseOwners.get(app);
owners?.delete(owner);
if (!owners?.size) hostPauseOwners.delete(app);
}
}
// =============================================================================
// Plugin Interface
// =============================================================================
export type PluginDependency = string | ResourceDef<any>;
export interface Plugin {
name?: string;
dependencies?: PluginDependency[];
before?: string[];
after?: string[];
/** Cost domain the profiler files this plugin's systems under. Defaults to
* `name`; declare it where the two differ, as `camera` producing `render`. */
profileDomain?: string;
/**
* The components this plugin's work is about: while no entity has any of them,
* its systems are not run — a game that never places water pays nothing for the
* water plugin each frame. They keep running for one frame after the last one
* goes, so a plugin can release what it held. Absent: always run.
*/
activeWhen?: readonly AnyComponentDef[];
build(app: App): void;
finish?(app: App): void;
/** Releases acquired resources on quit or a failed build; must tolerate a
* partially completed build. */
cleanup?(app?: App): void;
}
// =============================================================================
// System Entry
// =============================================================================
export type { RunCondition };
/** One frame's costs, attributed. The input `buildFrameProfile` folds. */
export interface FrameCosts {
systems: SystemCost[];
scopes: ScopeCost[];
}
/**
* @experimental What the loop's own clock read for one completed frame. The one
* place frame time is measured: the profiler, the debug channel and the quality
* controller all take it from here instead of each keeping a clock.
*/
export interface FrameTiming {
/** Counts completed frames, so a reader can tell a new one from the last. */
seq: number;
/** Interval since the previous frame, before simulation speed or delta clamping. */
frameMs: number;
/**
* How long this frame's own run took, first system to last; -1 where there is
* no clock. What is left of `frameMs` is time the loop waited for its next
* turn, so a frame that came late with this inside the budget was not held up
* by its systems.
*/
busyMs: number;
}
/** A system still running, and what decides who may start beside it. */
interface InflightSystem {
/** Its position in the sorted list — how a dependant recognises it. */
index: number;
access: SystemAccess;
done: Promise<void>;
}
/** One plugin's {@link Plugin.activeWhen}, decided once a frame for all its systems. */
interface ActivityGate {
readonly components: readonly AnyComponentDef[];
frame: number;
open: boolean;
/** Whether any of them existed when last decided: the frame after the last goes still runs. */
present: boolean;
}
interface SystemEntry {
startupInvoked?: boolean;
/** Skipped while the owning plugin's components are absent (see Plugin.activeWhen). */
gate?: ActivityGate;
system: SystemDef;
runBefore?: string[];
runAfter?: string[];
runIf?: RunCondition;
/** The subsystem (owning plugin name) this system belongs to — pets that
* subsystem's liveness watchdog when it runs (observability). */
subsystem?: string;
/** Came through the project bundle's pending-systems drain — the set hot
* reload may swap. "No owning subsystem" is NOT that set: engine systems
* registered lazily outside a plugin build (the physics event bridge, the
* hot-update rebind) carry no subsystem either, and mistaking them for
* user systems vetoed every hot swap in any project that had physics. */
fromBundle?: boolean;
/** Cost domain, from the building plugin or the door it came through. */
domain: string;
}
/**
* How a rejected schedule reads back to whoever wrote it. The two mistakes that
* get here look nothing alike in the source and identically at runtime, so the
* message has to tell them apart: a member that does not exist arrives as
* `undefined`, and swapped arguments arrive as the system itself.
*/
function describeSchedule(value: unknown): string {
if (value === undefined) return 'undefined (no such Schedule member?)';
if (value === null) return 'null';
if (typeof value === 'number' || typeof value === 'string') return JSON.stringify(value);
const name = (value as { _name?: unknown } | null)?._name;
if (typeof name === 'string') return `the system "${name}" (arguments the wrong way round?)`;
return Object.prototype.toString.call(value);
}
// =============================================================================
// App
// =============================================================================
/** How early a capped frame may land and still count as on time: vsync jitter. */
const CAP_JITTER_MS = 1;
export class App {
private readonly world_: World;
private readonly resources_: ResourceStorage;
private readonly systems_ = new Map<Schedule, SystemEntry[]>();
private runner_: SystemRunner | null = null;
/** Whether the once-per-app boot work has run. Not `runner_ !== null`: a
* compiled-systems install needs the runner BEFORE the first tick, and
* reading the boot from its existence would then skip that work forever. */
private booted_ = false;
/** The compiled twins a build installed, or null where it made none. */
private aot_: AotRuntime | null = null;
private systemCounter_ = 0;
private readonly templateToRuntime_ = new Map<symbol, symbol>();
/** Set name -> runtime system names registered under that set, for dep expansion. */
private readonly setMembership_ = new Map<string, string[]>();
private running_ = false;
private readonly executionHolds_ = new Set<object>();
private executionEpoch_ = 0;
private readonly executionObservers_: Array<(held: boolean) => void> = [];
private loopVersion_ = 0;
private queuedFrame_: number | null = null;
/** Whether {@link queuedFrame_} is a timer (hidden + runInBackground) rather than a rAF id. */
private queuedOnTimer_ = false;
private runInBackground_ = false;
private onVisibility_: (() => void) | null = null;
private frameInFlight_: Promise<void> | null = null;
private frameTiming_: FrameTiming | null = null;
private lastTime_ = 0;
private fixedTimestep_ = 1 / 60;
private fixedAccumulator_ = 0;
private maxDeltaTime_ = 0.25;
private maxFixedSteps_ = 8;
// Spiral-of-death guard: cap wall time spent on fixed-step catch-up per frame.
// A sim too heavy to run real-time (e.g. thousands of bodies) then degrades to
// slow motion instead of freezing — the frame stays responsive. The first step
// always runs (the check is after a step), so the sim always advances.
private fixedStepBudgetMs_ = 8;
private targetFrameInterval_ = 0;
private nextCapFrameAt_ = 0;
private module_: ESEngineModule | null = null;
private ownedCppRegistry_: CppRegistry | null = null;
private pipeline_: RenderPipeline | null = null;
private spineInitPromise_?: Promise<unknown>;
private compiledInstallTail_: Promise<void> = Promise.resolve();
private readonly installed_plugins_: Plugin[] = [];
private readonly installedPluginSet_ = new Set<Plugin>();
private readonly installedPluginNames_ = new Set<string>();
// Per-App (per-realm) so isolated realms never alias; not a shared resource default.
private readonly subsystems_ = new SubsystemRegistry();
/** The plugin currently in build(), so systems it adds inherit its name for
* liveness reporting. Null outside a build. */
private buildingPlugin_: string | null = null;
/** The cost domain of that plugin, which is its name unless it declared one. */
private buildingDomain_: string | null = null;
private buildingGate_: ActivityGate | null = null;
/** Registration undo actions for the current build; nested builds own theirs. */
private buildRollback_: Array<() => void> | null = null;
private addingBundleSystems_ = false;
// The realm's acquirer for optional native modules (physics, spine). Set once
// at app creation; physics/spine self-gate off it. Null in headless/test apps.
private sideModules_: SideModuleHost | null = null;
/** This App made the host, so quitting disposes it; one handed in is its maker's to end. */
private ownsSideModules_ = false;
private pluginsFinished_ = false;
private readonly eventRegistry_ = new EventRegistry();
private readonly sortedSystemsCache_ = new Map<Schedule, SystemEntry[]>();
/** Transitive ordering, per schedule. Invalidated with the sort it follows. */
private readonly dependencyCache_ = new Map<Schedule, Set<number>[]>();
private error_handler_: ((error: unknown, systemName: string) => void) | null = null;
private system_error_handler_: ((error: Error, systemName?: string) => 'continue' | 'pause') | null = null;
private statsEnabled_ = false;
private phaseTimings_: Map<string, number> | null = null;
// Sub-frame CPU scopes inside a single system (e.g. the render system's
// resolveCameras / submit split) — the JS-side sibling of the engine's C++
// ES_PROFILE_SCOPE. Null unless stats are on; same per-frame lifecycle as
// phaseTimings_ (cleared at tick start, read after the tick).
private frameScopes_: Map<string, ScopeCost> | null = null;
/** The system being run, so a scope opened inside one is filed under it. */
private currentSystem_ = '';
private readonly openScopes_: string[] = [];
private readonly frameObservers_: Array<(dtMs: number) => void> = [];
private frame_paused_ = false;
private user_paused_ = false;
private step_pending_ = false;
private steppedFrames_ = 0;
private play_speed_ = 1.0;
private constructor() {
this.world_ = new World();
this.resources_ = new ResourceStorage();
for (const s of Object.values(Schedule)) {
if (typeof s === 'number') {
this.systems_.set(s, []);
}
}
}
static new(): App {
return new App();
}
// =========================================================================
// Plugins
// =========================================================================
getPlugin<T extends Plugin>(ctor: new (...args: any[]) => T): T | undefined {
return this.installed_plugins_.find((p): p is T => p instanceof ctor);
}
/** Subsystem lifecycle registry ("which modules loaded/ready/stepping/errored").
* Named plugins auto-register in {@link addPlugin}; async plugins (physics)
* drive their own initializing→ready/error transitions. */
get subsystems(): SubsystemRegistry {
return this.subsystems_;
}
/** 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. */
get sideModules(): SideModuleHost | null {
return this.sideModules_;
}
/**
* `owned` says the host was made for this App alone: quitting then disposes
* it, with the workers and module instances tied to it. A host shared with
* anything else is left as it is, and whoever made it disposes it.
*/
setSideModules(host: SideModuleHost, options?: { owned?: boolean }): void {
this.sideModules_ = host;
this.ownsSideModules_ = options?.owned === true;
}
addPlugins(plugins: Plugin[]): this {
const sorted = this.sortPlugins(plugins);
for (const plugin of sorted) {
this.addPlugin(plugin);
}
return this;
}
addPlugin(plugin: Plugin): this {
if (this.quitting_) throw new Error('Cannot install plugins while App.quit is running');
if (this.installedPluginSet_.has(plugin)) return this;
if (plugin.dependencies) {
for (const dep of plugin.dependencies) {
if (typeof dep === 'string') {
if (!this.installedPluginNames_.has(dep)) {
throw new Error(
`Plugin "${plugin.name ?? 'unknown'}" requires plugin "${dep}" which has not been installed`
);
}
} else {
if (!this.hasResource(dep)) {
throw new Error(
`Plugin "${plugin.name ?? 'unknown'}" requires resource "${dep._name}" which has not been registered`
);
}
}
}
}
this.installedPluginSet_.add(plugin);
this.installed_plugins_.push(plugin);
if (plugin.name) {
this.installedPluginNames_.add(plugin.name);
// Observable from frame zero; string deps give the status UI cascade context.
this.subsystems_.register(plugin.name, {
dependsOn: plugin.dependencies?.filter(
(d): d is string => typeof d === 'string',
),
});
}
const prevBuilding = this.buildingPlugin_;
const prevDomain = this.buildingDomain_;
const prevGate = this.buildingGate_;
const prevRollback = this.buildRollback_;
const rollback: Array<() => void> = [];
const buildEpoch = this.quitEpoch_;
this.buildRollback_ = rollback;
this.buildingPlugin_ = plugin.name ?? null;
this.buildingDomain_ = plugin.profileDomain ?? plugin.name ?? null;
this.buildingGate_ = plugin.activeWhen?.length
? { components: plugin.activeWhen, frame: -1, open: true, present: true } : null;
try {
plugin.build(this);
// Sync plugin: live once build() returns → promote. An async plugin
// (physics) already moved itself off `registered`, so this skips it.
if (plugin.name && this.subsystems_.phaseOf(plugin.name) === 'registered') {
this.subsystems_.transition(plugin.name, 'ready');
}
// A child installed inside this build remains provisional until the
// enclosing build commits. Pre-existing plugins never reach here.
prevRollback?.push(() => this.rollbackPluginBuild_(plugin, rollback, buildEpoch,
'Enclosing plugin build failed'));
} catch (e) {
this.buildRollback_ = null;
this.rollbackPluginBuild_(plugin, rollback, buildEpoch, e instanceof Error ? e.message : String(e));
throw e;
} finally {
this.buildingPlugin_ = prevBuilding;
this.buildingDomain_ = prevDomain;
this.buildingGate_ = prevGate;
this.buildRollback_ = prevRollback;
}
return this;
}
private rollbackPluginBuild_(plugin: Plugin, rollback: Array<() => void>, epoch: number, reason: string): void {
this.installedPluginSet_.delete(plugin);
const index = this.installed_plugins_.indexOf(plugin);
if (index >= 0) this.installed_plugins_.splice(index, 1);
if (plugin.name) {
if (!this.installed_plugins_.some(p => p.name === plugin.name)) this.installedPluginNames_.delete(plugin.name);
this.subsystems_.markError(plugin.name, reason);
}
// Child resources are released before their parent's, matching quit.
// Withdraw systems even if resource cleanup throws.
for (let i = rollback.length - 1; i >= 0 && this.quitEpoch_ === epoch; i--) {
try { rollback[i](); } catch (rollbackError) {
log.error('app', 'Failed plugin registration rollback error', rollbackError);
}
}
// Already removed above: a cleanup that quits cannot clean this twice.
try { if (index >= 0) plugin.cleanup?.(this); } catch (cleanupError) {
log.error('app', 'Failed plugin build cleanup error', cleanupError);
}
}
addEvent<T>(event: EventDef<T>): this {
this.eventRegistry_.register(event);
return this;
}
// =========================================================================
// Systems
// =========================================================================
/**
* The entry list for `schedule`, or a refusal that says what was wrong.
*
* Every valid schedule gets its list in the constructor, so a miss means the
* caller passed something that is not a Schedule — a member that does not
* exist (`Schedule.LateUpdate` evaluates to `undefined`), or the two
* arguments the wrong way round. Neither is caught before it runs: the
* editor and the mini-game exporters bundle project code with esbuild, which
* strips types without checking them, so a registration TypeScript would
* have rejected reaches the App intact.
*
* It used to be `systems_.get(schedule)!`, which turned both into "Cannot
* read properties of undefined (reading 'push')" thrown from inside a
* minified bundle, naming neither the system nor the value.
*/
/** Whether a plugin's systems run this frame: some entity has one of its components, or had last frame. */
private gateOpen_(gate: ActivityGate): boolean {
const frame = this.hasResource(Time) ? this.getResource(Time).frameCount : 0;
if (gate.frame === frame) return gate.open;
const world = this.world;
let present = false;
for (const c of gate.components) {
// A cached query: unchanged structure answers without walking anything.
// A core that cannot answer for the component (compiled out) is not a
// reason to stop the plugin: it runs as it did before there was a gate.
try {
if (world.queryEntities([c]).length > 0) { present = true; break; }
} catch {
present = true;
break;
}
}
gate.open = present || gate.present;
gate.present = present;
gate.frame = frame;
return gate.open;
}
private registeringDomain_(): string {
if (this.buildingDomain_) return this.buildingDomain_;
return this.addingBundleSystems_ ? DOMAIN_SCRIPTS : DOMAIN_UNATTRIBUTED;
}
private scheduleBucket_(schedule: Schedule, systemName: string): SystemEntry[] {
const bucket = this.systems_.get(schedule);
if (bucket) return bucket;
const valid = Object.entries(Schedule)
.filter(([, v]) => typeof v === 'number')
.map(([k, v]) => `${k} (${String(v)})`)
.join(', ');
throw new Error(
`addSystemToSchedule("${systemName}"): ${describeSchedule(schedule)} is not a schedule. `
+ `Expected one of: ${valid}. `
+ `Check the Schedule member exists, and that the schedule comes before the system.`,
);
}
/**
* 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.
*/
addSystemToSchedule(
schedule: Schedule,
system: SystemDef,
options?: {
runBefore?: string[]; runAfter?: string[]; runIf?: RunCondition; profileDomain?: string;
/** This system alone, gated as Plugin.activeWhen gates a whole plugin: skipped while no
* entity has any of these, and run one frame past the last. Takes precedence over the
* building plugin's gate. */
activeWhen?: readonly AnyComponentDef[];
}
): this {
const name = system._name || `System_${++this.systemCounter_}`;
const scoped = rescopeSystem(system, name);
this.registerSystemEntry_(schedule, system._id, {
system: scoped,
runBefore: mergeOrderingEdges(system._runBefore, options?.runBefore),
runAfter: mergeOrderingEdges(system._runAfter, options?.runAfter),
runIf: options?.runIf,
subsystem: this.buildingPlugin_ ?? undefined,
fromBundle: this.addingBundleSystems_ || undefined,
domain: options?.profileDomain ?? this.registeringDomain_(),
...(options?.activeWhen?.length
? { gate: { components: options.activeWhen, frame: -1, open: true, present: true } }
: this.buildingGate_ ? { gate: this.buildingGate_ } : {}),
});
this.sortedSystemsCache_.delete(schedule);
this.dependencyCache_.delete(schedule);
return this;
}
private registerSystemEntry_(schedule: Schedule, templateId: symbol, entry: SystemEntry): void {
const bucket = this.scheduleBucket_(schedule, entry.system._name);
const previous = this.templateToRuntime_.get(templateId);
this.templateToRuntime_.set(templateId, entry.system._id);
bucket.push(entry);
this.buildRollback_?.push(() => {
const live = this.systems_.get(schedule);
const index = live?.indexOf(entry) ?? -1;
if (index >= 0) live!.splice(index, 1);
this.sortedSystemsCache_.delete(schedule);
this.dependencyCache_.delete(schedule);
this.runner_?.evict(entry.system._id);
// A successful nested plugin may have registered the same template.
if (this.templateToRuntime_.get(templateId) === entry.system._id) {
if (previous === undefined) this.templateToRuntime_.delete(templateId);
else this.templateToRuntime_.set(templateId, previous);
}
});
}
addSystem(system: SystemDef): this {
return this.addSystemToSchedule(Schedule.Update, system);
}
/**
* Register systems drained from the PROJECT BUNDLE, marking them as the set
* hot reload may swap. The bundle drain is the one boundary that separates
* user-authored systems from everything the engine registers — plugin
* builds tag themselves, but lazily-added engine systems are told apart
* from user code only by which door they came through.
* @internal
*/
addBundleSystems(entries: ReadonlyArray<{ schedule: number; system: SystemDef | SystemSet }>): this {
this.addingBundleSystems_ = true;
try {
for (const e of entries) {
// A set expands to its members here, so everything downstream —
// hot reload included — still sees a flat list of user systems.
if ((e.system as SystemSet)._kind === 'set') {
this.addSystemSetToSchedule(e.schedule as Schedule, e.system as SystemSet);
} else {
this.addSystemToSchedule(e.schedule as Schedule, e.system as SystemDef);
}
}
} finally {
this.addingBundleSystems_ = false;
}
return this;
}
addStartupSystem(system: SystemDef): this {
return this.addSystemToSchedule(Schedule.Startup, system);
}
/**
* 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.
*/
hotSwapSystems(incoming: ReadonlyArray<{ schedule: number; system: SystemDef }>): boolean {
const bySchedule = new Map<Schedule, SystemDef[]>();
for (const e of incoming) {
const arr = bySchedule.get(e.schedule as Schedule);
if (arr) arr.push(e.system);
else bySchedule.set(e.schedule as Schedule, [e.system]);
}
const userEntries = (s: Schedule): SystemEntry[] =>
(this.systems_.get(s) ?? []).filter((entry) => entry.fromBundle === true);
// Startup is exempt from matching in both directions: its entries are
// CONSUMED when they run (flushStartupSystems truncates the list), so the
// live side is always empty while a re-imported bundle always queues them
// again — requiring a match would veto hot swap for every project that
// uses addStartupSystem. There is nothing to swap either way: a startup
// body can only run on a cold start, so an edited one takes effect on the
// next full reload, which is the only time it could.
// Each rejection names the mismatch: "the structure changed" alone reads
// as a hot reload that arbitrarily lost the World.
for (const [schedule, defs] of bySchedule) {
if (schedule === Schedule.Startup) continue;
const live = userEntries(schedule);
if (live.length !== defs.length) {
log.info('hotReload', `structure: schedule ${Schedule[schedule]} has ${live.length} live user system(s) [${live.map((e) => e.system._name).join(', ')}] vs ${defs.length} incoming [${defs.map((d) => d._name || '(unnamed)').join(', ')}]`);
return false;
}
for (let i = 0; i < live.length; i++) {
if (!App.systemNamesCompatible(live[i].system._name, defs[i]._name)) {
log.info('hotReload', `structure: schedule ${Schedule[schedule]} system #${i} renamed "${live[i].system._name}" -> "${defs[i]._name || '(unnamed)'}"`);
return false;
}
}
}
// A schedule that had user systems the new bundle didn't re-add is structural.
for (const [schedule, entries] of this.systems_) {
if (schedule === Schedule.Startup) continue;
if (!bySchedule.has(schedule) && entries.some((e) => e.fromBundle === true)) {
log.info('hotReload', `structure: schedule ${Schedule[schedule]} lost its user systems in the new bundle`);
return false;
}
}
for (const [schedule, defs] of bySchedule) {
if (schedule === Schedule.Startup) continue;
const live = userEntries(schedule);
for (let i = 0; i < live.length; i++) {
const cur = live[i].system;
live[i].system = { _id: cur._id, _params: defs[i]._params, _fn: defs[i]._fn, _name: cur._name };
}
this.sortedSystemsCache_.delete(schedule);
this.dependencyCache_.delete(schedule);
}
return true;
}
/** A live (scoped) system name and a re-imported raw name refer to the same system
* if the live one is an explicit name that matches, or both are auto-named (the
* live `System_N` placeholder ⇔ an unnamed re-import). */
private static systemNamesCompatible(liveName: string, rawName: string): boolean {
return /^System_\d+$/.test(liveName) ? rawName === '' : rawName === liveName;
}
/**
* 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.
*/
addSystemSetToSchedule(schedule: Schedule, set: SystemSet): this {
const members: string[] = [];
for (const sys of set._systems) {
const name = sys._name || `System_${String(++this.systemCounter_)}`;
members.push(name);
const mergedRunBefore = mergeOrderingEdges(sys._runBefore, set._runBefore);
const mergedRunAfter = mergeOrderingEdges(sys._runAfter, set._runAfter);
const setCondition = set._runIf;
const runIf: RunCondition | undefined = setCondition ? (() => setCondition()) : undefined;
// Use the scoped system name the App would generate so ordering
// lookups match. Mirrors addSystemToSchedule's naming path.
const scoped = rescopeSystem(sys, name);
this.registerSystemEntry_(schedule, sys._id, {
system: scoped,
runBefore: mergedRunBefore,
runAfter: mergedRunAfter,
runIf,
subsystem: this.buildingPlugin_ ?? undefined,
domain: this.registeringDomain_(),
});
}
this.sortedSystemsCache_.delete(schedule);
this.dependencyCache_.delete(schedule);
const existing = this.setMembership_.get(set._name);
const membership = existing ? [...existing, ...members] : members;
this.setMembership_.set(set._name, membership);
this.buildRollback_?.push(() => {
if (this.setMembership_.get(set._name) !== membership) return;
if (existing) this.setMembership_.set(set._name, existing);
else this.setMembership_.delete(set._name);
});
return this;
}
/** Shortcut for `addSystemSetToSchedule(Schedule.Update, set)`. */
addSystemSet(set: SystemSet): this {
return this.addSystemSetToSchedule(Schedule.Update, set);
}
removeSystem(systemId: symbol): boolean {
const runtimeId = this.templateToRuntime_.get(systemId) ?? systemId;
let removed = false;
for (const [schedule, entries] of this.systems_) {
const filtered = entries.filter(e => e.system._id !== runtimeId);
if (filtered.length !== entries.length) {
this.systems_.set(schedule, filtered);
this.sortedSystemsCache_.delete(schedule);
this.dependencyCache_.delete(schedule);
removed = true;
}
}
if (removed) {
this.runner_?.evict(runtimeId);
this.templateToRuntime_.delete(systemId);
}
return removed;
}
// =========================================================================
// C++ Integration
// =========================================================================
/**
* Bind the app to an engine core. Part of the embedding contract, which is
* `esengine/wasm` — a host builds the module and calls this; a game is
* handed an App that is already connected.
* `ownedRegistry` transfers a newly constructed instance to this App after
* the connection guards pass; failed verification releases it too. Omit
* it for a registry whose lifetime belongs to the embedding host.
*
* @internal
*/
connectCpp(
cppRegistry: CppRegistry,
module?: ESEngineModule,
options?: BridgeConnectOptions & { ownedRegistry?: boolean },
): this {
if (this.quitting_) throw new Error('Cannot connect a registry while App.quit is releasing it');
if (this.ownedCppRegistry_ && this.ownedCppRegistry_ !== cppRegistry) {
throw new Error('Quit the App before replacing its owned registry');
}
// Factories transfer their newly constructed embind instance here.
// External connections borrow by default. A failed connection must
// release the transferred instance, preserving the original diagnostic.
try { this.world_.connectCpp(cppRegistry, module, options); }
catch (error) {
if (options?.ownedRegistry && this.ownedCppRegistry_ !== cppRegistry) {
this.world_.disconnectCpp();
try { cppRegistry.delete(); }
catch (releaseError) { log.warn('app', 'Failed registry connection release error', releaseError); }
}
throw error;
}
if (options?.ownedRegistry) this.ownedCppRegistry_ = cppRegistry;
if (module) {
this.module_ = module;
}
return this;
}
/** @internal */
get wasmModule(): ESEngineModule | null {
return this.module_;
}
get pipeline(): RenderPipeline | null {
return this.pipeline_;
}
setPipeline(pipeline: RenderPipeline): void {
this.pipeline_ = pipeline;
}
get spineInitPromise(): Promise<unknown> | undefined {
return this.spineInitPromise_;
}
set spineInitPromise(p: Promise<unknown> | undefined) {
this.spineInitPromise_ = p;
}
async waitForPhysics(): Promise<void> {
if (!this.hasResource(Physics2DRuntime)) {
log.warn('app', 'No Physics2DPlugin installed, waitForPhysics() is a no-op');
return;
}
const promise = this.getResource(Physics2DRuntime).initPromise;
if (promise) await promise;
}
get isPhysicsReady(): boolean {
return this.hasResource(Physics2DRuntime)
&& this.getResource(Physics2DRuntime).module != null;
}
// =========================================================================
// World Access
// =========================================================================
get world(): World {
return this.world_;
}
/**
* 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.
*
* @experimental
*/
async useCompiledSystems(opts: {
readonly host: AotHost;
readonly manifest: AotManifest;
readonly wasm: BufferSource;
}): Promise<void> {
const installation = this.reserveCompiledInstall_();
await installation.ready;
try {
const epoch = installation.epoch;
this.checkCompiledInstallEpoch_(epoch);
this.ensureTime_();
const runtime = await prepareAot({
world: this.world_,
host: opts.host,
manifest: opts.manifest,
wasm: opts.wasm,
beforeCommit: () => this.checkCompiledInstallEpoch_(epoch),
resourceFields: (name) => {
const def = builtinResource(name) ?? this.resources_.getByName(name) ?? declaredResource(name);
if (def === undefined) return undefined;
const value = this.resources_.get(def);
return typeof value === 'object' && value !== null ? Object.keys(value) : [];
},
// A manifest carries event NAMES; the registry answers for the ones
// some system has asked for a reader or a writer of.
events: (name) => {
// Through the DEFINITION, so the bus exists whether or not an
// interpreted system has asked for one yet: a twin sending into
// a bus nobody had made would drop its payloads and say nothing.
const def = eventNamed(name);
if (def === undefined) return undefined;
const bus = this.eventRegistry_.getBus(def);
return { read: () => bus.getReadBuffer(), send: (payload) => bus.send(payload) };
},
resources: (name) => {
// The engine's own by name, and the PROJECT's through the
// storage's own name registry — a compiled system reads either.
const def = builtinResource(name) ?? this.resources_.getByName(name) ?? declaredResource(name);
// `get`, not `has` then `get`: a slot holding a materialised
// default is what an INTERPRETED system reads, and a twin has to
// see the same world or the two stop being the same program.
return def === undefined
? undefined
: this.resources_.get(def) as Readonly<Record<string, unknown>>;
},
});
if (epoch !== this.quitEpoch_) {
runtime.dispose?.();
throw new Error('Compiled systems installation was cancelled by App.quit');
}
this.commitCompiledRuntime_(runtime, epoch);
} finally {
installation.done();
}
}
private reserveCompiledInstall_(): { ready: Promise<void>; done(): void; epoch: number } {
const ready = this.compiledInstallTail_;
let done!: () => void;
this.compiledInstallTail_ = new Promise<void>(resolve => { done = resolve; });
return { ready, done, epoch: this.quitEpoch_ };
}
private checkCompiledInstallEpoch_(epoch: number): void {
if (this.quitting_ || epoch !== this.quitEpoch_) {
throw new Error('Compiled systems installation was cancelled by App.quit');
}
}
private commitCompiledRuntime_(runtime: AotRuntime, epoch: number): void {
const previous = this.aot_;
try { this.runner_?.useAot(runtime); }
catch (error) {
try { this.runner_?.useAot(previous); } catch (restoreError) { log.warn('app', 'Compiled dispatch restore error', restoreError); }
try { runtime.dispose?.(); } catch (releaseError) { log.warn('app', 'Compiled installation cleanup error', releaseError); }
throw error;
}
this.aot_ = runtime;
try { previous?.dispose?.(); } catch (releaseError) { log.warn('app', 'Compiled runtime replacement cleanup error', releaseError); }
this.checkCompiledInstallEpoch_(epoch);
}
/**
* 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.
*
* @experimental
*/
get compiledSystems(): { readonly installed: readonly string[]; readonly calls: number } {
return {
installed: this.aot_?.systems.names() ?? [],
calls: this.aot_?.systems.calls ?? 0,
};
}
// =========================================================================
// Configuration
// =========================================================================
setFixedTimestep(timestep: number): this {
this.fixedTimestep_ = timestep;
return this;
}
/** The fixed-update timestep (seconds) — the FixedUpdate / physics cadence. */
getFixedTimestep(): number {
return this.fixedTimestep_;
}
setMaxDeltaTime(v: number): this {
this.maxDeltaTime_ = v;
return this;
}
setMaxFixedSteps(v: number): this {
this.maxFixedSteps_ = v;
return this;
}
onError(handler: (error: unknown, systemName: string) => void): this {
this.error_handler_ = handler;
return this;
}
onSystemError(handler: (error: Error, systemName?: string) => 'continue' | 'pause'): this {
this.system_error_handler_ = handler;
return this;
}
onWasmError(handler: (error: unknown, context: string) => void): this {
setWasmErrorHandler(handler);
return this;
}
/** Pause simulation time and ordinary systems; presentation opt-ins and Last still run. */
setPaused(paused: boolean): void {
this.user_paused_ = paused;
}
isPaused(): boolean {
return this.user_paused_ || !!hostPauseOwners.get(this)?.size;
}
stepFrame(): void {
if (this.isExecutionHeld()) return;
this.step_pending_ = true;
}
setPlaySpeed(speed: number): void {
this.play_speed_ = Math.max(0.1, Math.min(4.0, speed));
}
setTargetFrameRate(fps: number): void {
this.targetFrameInterval_ = fps > 0 ? 1000 / fps : 0;
this.nextCapFrameAt_ = 0;
// A native host steps the app from its own display-driven loop, not from mainLoop above, so the cap
// is the host's to hold (and to tell the OS, so the panel settles on a rate the game can keep).
(globalThis as { es_setTargetFrameRate?: (fps: number) => void }).es_setTargetFrameRate?.(fps > 0 ? fps : 0);
}
/**
* Keep simulating while the page is hidden — a window behind others, a
* minimized one, or one never shown (an editor driven by automation).
*
* A browser stops `requestAnimationFrame` for a hidden document, so without
* this the game holds still there: what a shipped game wants, since nobody is
* watching and the battery is. An editor's Play wants the opposite; Unity
* calls the same switch `Application.runInBackground`. While hidden the loop
* runs on a timer at the frame cap (60 fps when uncapped).
*/
setRunInBackground(on: boolean): void {
this.runInBackground_ = on;
if (typeof document === 'undefined') return;
if (on && !this.onVisibility_) {
// A rAF queued just before the page hid never fires: move it to the timer.
this.onVisibility_ = () => {
if (this.queuedFrame_ === null || this.queuedOnTimer_ || document.visibilityState !== 'hidden') return;
if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this.queuedFrame_);
this.queuedFrame_ = null;
this.queueLoopFrame_();
};
document.addEventListener('visibilitychange', this.onVisibility_);
} else if (!on && this.onVisibility_) {
document.removeEventListener('visibilitychange', this.onVisibility_);
this.onVisibility_ = null;
}
}
getRunInBackground(): boolean {
return this.runInBackground_;
}
getTargetFrameRate(): number {
return this.targetFrameInterval_ > 0 ? 1000 / this.targetFrameInterval_ : 0;
}
getPlaySpeed(): number {
return this.play_speed_;
}
// =========================================================================
// Stats
// =========================================================================
enableStats(): this {
this.statsEnabled_ = true;
this.phaseTimings_ = new Map();
this.frameScopes_ = new Map();
this.runner_?.setTimingEnabled(true);
return this;
}
getSystemTimings(): ReadonlyMap<string, number> | null {
return this.runner_?.getTimings() ?? null;
}
getPhaseTimings(): ReadonlyMap<string, number> | null {
return this.phaseTimings_;
}
/** @experimental The last completed frame's clock readings; see {@link FrameTiming}. */
getFrameTiming(): Readonly<FrameTiming> | null {
return this.frameTiming_;
}
/** Frames requested by stepping controls, excluded from wall-clock FPS windows. */
getSteppedFrameCount(): number {
return this.steppedFrames_;
}
/**
* Sub-frame CPU scopes recorded this frame via {@link measureFrameScope} —
* the finer breakdown within a single system, keyed by scope name. Null when
* stats aren't enabled. Sibling of {@link getSystemTimings} /
* {@link getPhaseTimings}; surfaces as the profiler's `js.*` rows.
*/
getFrameScopes(): ReadonlyMap<string, number> | null {
if (!this.frameScopes_) return null;
const flat = new Map<string, number>();
for (const [name, scope] of this.frameScopes_) flat.set(name, scope.ms);
return flat;
}
/**
* 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.
*/
getFrameCosts(): FrameCosts | null {
if (!this.frameScopes_) return null;
const timings = this.runner_?.getTimings();
const domains = new Map<string, string>();
for (const entries of this.systems_.values()) {
for (const entry of entries) domains.set(entry.system._name, entry.domain);
}
const queryCosts = this.runner_?.getQueryCosts();
const systems: SystemCost[] = [];
for (const [name, ms] of timings ?? []) {
const query = queryCosts?.get(name);
systems.push({
name,
ms,
domain: domains.get(name) ?? DOMAIN_UNATTRIBUTED,
...(query ? { query } : {}),
});
}
return { systems, scopes: [...this.frameScopes_.values()] };
}
/**
* 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.
*/
measureFrameScope<T>(name: string, fn: () => T, options?: { remainder?: ScopeRemainder }): T {
const scopes = this.frameScopes_;
if (!scopes) return fn();
const parent = this.openScopes_[this.openScopes_.length - 1];
this.openScopes_.push(name);
const t0 = performance.now();
try {
return fn();
} finally {
const elapsed = performance.now() - t0;
this.openScopes_.pop();
const prev = scopes.get(name);
scopes.set(name, {
name,
ms: (prev?.ms ?? 0) + elapsed,
system: prev?.system ?? this.currentSystem_,
remainder: options?.remainder ?? 'work',
...(parent !== undefined ? { parent } : {}),
});
}
}
/**
* 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.
*/
onFrameEnd(fn: (dtMs: number) => void): () => void {
this.frameObservers_.push(fn);
return () => {
const i = this.frameObservers_.indexOf(fn);
if (i >= 0) this.frameObservers_.splice(i, 1);
};
}
getEntityCount(): number {
return this.world_.entityCount();
}
// =========================================================================
// Resource Access
// =========================================================================
insertResource<T>(resource: ResourceDef<T>, value: T): this {
this.resources_.insert(resource, value);
return this;
}
getResource<T>(resource: ResourceDef<T>): T {
return this.resources_.get(resource);
}
hasResource<T>(resource: ResourceDef<T>): boolean {
return this.resources_.has(resource);
}
getResourceByName(name: string): unknown | undefined {
// The storage learns a name on INSERT; a declared one `get` materialises
// at its default, which is what an interpreted system reads on its first
// frame. Without this the AOT handshake refused a resource that was there.
const def = builtinResource(name) ?? this.resources_.getByName(name) ?? declaredResource(name);
return def ? this.resources_.get(def) : undefined;
}
getResourceChangeTick(name: string): number {
const def = this.resources_.getByName(name);
return def ? this.resources_.getChangeTick(def) : 0;
}
getRegisteredResourceNames(): string[] {
return this.resources_.getRegisteredNames();
}
/**
* Every resource this app holds, as `[name, value]` — what an inspector
* shows. Includes the slots only a read has materialised, which
* {@link getRegisteredResourceNames} (insert-only) does not.
*/
getResourceEntries(): Array<[string, unknown]> {
return this.resources_.entries();
}
// =========================================================================
// Scene Management
// =========================================================================
registerScene(config: SceneConfig): this {
this.getResource(SceneManager).register(config);
return this;
}
setInitialScene(name: string): this {
this.getResource(SceneManager).setInitial(name);
return this;
}
// =========================================================================
// Compiled systems (AOT)
// =========================================================================
/**
* 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.
*/
get compiledSystemCount(): number {
return this.aot_?.systems.size ?? 0;
}
/**
* 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.
*/
async installCompiledSystems(
source: string | BufferSource, manifest: AotManifest,
): Promise<number> {
const installation = this.reserveCompiledInstall_();
await installation.ready;
try {
const epoch = installation.epoch;
this.checkCompiledInstallEpoch_(epoch);
// Which road is a fact about the HOST, not about the caller: a host
// that loads a library packs the rows itself, and an address there is a
// pointer nothing here can hold.
const native = this.installNative_(source, manifest);
if (native !== null) return native;
const wasm = source;
const module = this.module_;
if (!module) {
throw new Error('installCompiledSystems: this App has no engine module, and a compiled '
+ 'system reads the memory of one');
}
const memory = module.wasmMemory;
// An engine built as plain JavaScript (wasm2js, for a host without
// WebAssembly) has an ArrayBuffer where the Memory would be, and a
// compiled system is a wasm module that cannot import it. Not an error:
// every system keeps running interpreted, which is the no-cliff rule.
if (memory && (typeof WebAssembly === 'undefined' || !(memory instanceof WebAssembly.Memory))) {
log.info('runtime', 'AOT: this engine runs without WebAssembly, so its compiled systems stay interpreted');
return 0;
}
if (!memory) {
throw new Error('installCompiledSystems: this engine artifact does not export '
+ "'wasmMemory', so there is no memory for the module to import — rebuild the engine");
}
// Read through to the module rather than captured: emscripten REPLACES
// the heap view when the heap grows, and a snapshot taken here would be
// detached by the first allocation that grows it.
const host: AotHost = {
allocatorIdentity: module,
memory,
_malloc: (size: number) => module._malloc(size),
_free: (ptr: number) => module._free(ptr),
get HEAPU8(): Uint8Array { return module.HEAPU8; },
};
this.ensureTime_();
const runtime = await prepareAot({
world: this.world_,
host,
manifest,
wasm,
beforeCommit: () => this.checkCompiledInstallEpoch_(epoch),
resources: (name: string) => this.getResourceByName(name) as
Readonly<Record<string, unknown>> | undefined,
});
if (epoch !== this.quitEpoch_) {
runtime.dispose?.();
throw new Error('Compiled systems installation was cancelled by App.quit');
}
this.ensureRunner_();
this.commitCompiledRuntime_(runtime, epoch);
return runtime.systems.size;
} finally {
installation.done();
}
}
/**
* The same, where the host loads a library. Null when this is not such a
* host, which is every host but a native one — and then the caller falls
* through to the module road above.
*/
private installNative_(module: string | BufferSource, manifest: AotManifest): number | null {
if (typeof module !== 'string') return null;
const bindings = nativeAotBindings();
const heap = createNativeHeap();
if (bindings === null || heap === null) return null;
this.ensureTime_();
const epoch = this.quitEpoch_;
const runtime = installNativeAot({
world: this.world_,
runner: this.ensureRunner_(),
modulePath: module,
manifest,
heap,
bindings,
resources: (name: string) => this.getResourceByName(name) as
Readonly<Record<string, unknown>> | undefined,
});
if (runtime === null) return 0;
if (epoch !== this.quitEpoch_) {
runtime.dispose?.();
this.runner_?.useAot(this.aot_);
throw new Error('Compiled systems installation was cancelled by App.quit');
}
this.commitCompiledRuntime_(runtime, epoch);
return runtime.systems.size;
}
// =========================================================================
// Run
// =========================================================================
async tick(delta: number): Promise<void> {
if (this.isExecutionHeld()) return;
const epoch = this.executionEpoch_;
this.frame_paused_ = false;
this.boot_();
await this.flushStartupSystems_();
if (epoch !== this.executionEpoch_ || this.isExecutionHeld()) return;
await this.runFrame_(delta);
}
/** Hold frame execution without changing the game's own pause state. */
holdExecution(): () => void {
const owner = {}, quitEpoch = this.quitEpoch_;
const first = this.executionHolds_.size === 0;
this.executionHolds_.add(owner);
if (first) {
this.executionEpoch_++;
this.frame_paused_ = true;
this.invalidateLoop_();
if (this.hasResource(Input)) setInputExecutionHeld(this.getResource(Input), this, true);
this.notifyExecution_();
}
return () => {
if (quitEpoch !== this.quitEpoch_ || !this.executionHolds_.delete(owner) || this.executionHolds_.size) return;
if (this.hasResource(Input)) setInputExecutionHeld(this.getResource(Input), this, false);
this.notifyExecution_();
if (this.isExecutionHeld()) return;
const version = this.loopVersion_;
// An interrupted asynchronous frame settles before another frame starts.
void (this.frameInFlight_ ?? Promise.resolve()).then(() => {
if (!this.running_ || this.isExecutionHeld() || version !== this.loopVersion_) return;
this.lastTime_ = platformNow();
if (typeof requestAnimationFrame === 'function') this.queueLoopFrame_();
else void this.mainLoop();
});
};
}
isExecutionHeld(): boolean { return this.executionHolds_.size > 0; }
/** Observe execution holds, including the initial state. Media/timer owners can cooperate here. */
onExecutionChange(callback: (held: boolean) => void): () => void {
this.executionObservers_.push(callback);
this.callExecutionObserver_(callback);
return () => {
const index = this.executionObservers_.indexOf(callback);
if (index >= 0) this.executionObservers_.splice(index, 1);
};
}
private notifyExecution_(): void {
for (const callback of [...this.executionObservers_]) {
this.callExecutionObserver_(callback);
}
}
private callExecutionObserver_(callback: (held: boolean) => void): void {
try {
const result: unknown = callback(this.isExecutionHeld());
if (result instanceof Promise) void result.catch(error => log.error('app', 'Execution observer error', error));
} catch (error) { log.error('app', 'Execution observer error', error); }
}
/**
* 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.
*/
async stepFrames(frames = 1, dt = 1 / 60): Promise<void> {
if (this.isExecutionHeld()) return;
const executionEpoch = this.executionEpoch_, quitEpoch = this.quitEpoch_;
const previousStep = this.step_pending_;
const wasRunning = this.running_;
const wasPaused = this.user_paused_;
this.invalidateLoop_();
const version = this.loopVersion_;
this.running_ = false;
try {
await this.frameInFlight_;
this.user_paused_ = false;
for (let i = 0; i < frames; i++) {
if (this.isExecutionHeld() || executionEpoch !== this.executionEpoch_) break;
this.step_pending_ = true; await this.tick(dt);
}
} finally {
if (quitEpoch === this.quitEpoch_) {
this.user_paused_ = wasPaused;
if (executionEpoch !== this.executionEpoch_ || this.isExecutionHeld()) this.step_pending_ = previousStep;
}
if (wasRunning && quitEpoch === this.quitEpoch_
&& (version === this.loopVersion_ || executionEpoch !== this.executionEpoch_)) {
this.lastTime_ = platformNow();
this.running_ = true;
// Resumed on the next animation frame, not by starting one here:
// a frame begun inside this call's own microtask drain swallows
// the input edge a caller injects the moment it returns.
if (!this.isExecutionHeld()) {
if (typeof requestAnimationFrame === 'function') this.queueLoopFrame_();
else void this.mainLoop();
}
}
}
}
async run(): Promise<void> {
if (this.running_) {
return;
}
this.running_ = true;
if (this.isExecutionHeld()) return;
const version = this.loopVersion_;
this.frame_paused_ = false;
this.boot_();
await this.flushStartupSystems_();
if (!this.running_ || this.isExecutionHeld() || version !== this.loopVersion_) return;
this.lastTime_ = platformNow();
this.mainLoop();
}
private invalidateLoop_(): void {
this.loopVersion_++;
if (this.queuedFrame_ !== null) {
if (this.queuedOnTimer_) clearTimeout(this.queuedFrame_);
else if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this.queuedFrame_);
}
this.queuedFrame_ = null;
}
private queueLoopFrame_(): void {
if (this.isExecutionHeld() || this.queuedFrame_ !== null) return;
if (typeof requestAnimationFrame !== 'function') return;
const version = this.loopVersion_;
const hidden = typeof document !== 'undefined' && document.visibilityState === 'hidden';
if (hidden && this.runInBackground_) {
// No rAF arrives for a hidden document; a timer at the frame cadence does.
this.queuedOnTimer_ = true;
this.queuedFrame_ = setTimeout(() => {
if (version !== this.loopVersion_) return;
this.queuedFrame_ = null;
void this.mainLoop(platformNow(), version);
}, this.targetFrameInterval_ > 0 ? this.targetFrameInterval_ : 1000 / 60) as unknown as number;
return;
}
this.queuedOnTimer_ = false;
this.queuedFrame_ = requestAnimationFrame((time) => {
if (version !== this.loopVersion_) return;
this.queuedFrame_ = null;
return this.mainLoop(time, version);
});
}
private mainLoop = async (rafTime?: number, version = this.loopVersion_): Promise<void> => {
if (!this.running_ || this.isExecutionHeld() || version !== this.loopVersion_) {
return;
}
// The frame clock is the rAF timestamp — the vsync being drawn for — not
// callback entry, whose jitter would enter delta twice and judder motion.
// A host that passes no timestamp keeps the old measurement.
const currentTime = typeof rafTime === 'number' && rafTime > 0 ? rafTime : platformNow();
const deltaMs = currentTime - this.lastTime_;
// A cadence, not a minimum gap: a cap of two vsyncs measured frame to frame
// loses to jitter half the time and waits a third (30 fps on 60 Hz ran at 24).
if (this.targetFrameInterval_ > 0) {
if (currentTime < this.nextCapFrameAt_ - CAP_JITTER_MS) {
this.queueLoopFrame_();
return;
}
// More than a frame behind (a stall, a hidden page): the cadence restarts here.
this.nextCapFrameAt_ = currentTime - this.nextCapFrameAt_ > this.targetFrameInterval_
? currentTime + this.targetFrameInterval_
: this.nextCapFrameAt_ + this.targetFrameInterval_;
}
this.lastTime_ = currentTime;
// Never negative: two clocks with different origins meet on the first frame
// after run()/stepFrames seeds lastTime_ from platformNow(), and time running
// backwards is worse than a frame that stands still.
const rawDelta = Math.max(0, Math.min(deltaMs / 1000, this.maxDeltaTime_));
const delta = rawDelta * this.play_speed_;
this.frame_paused_ = false;
this.boot_();
await this.flushStartupSystems_();
if (!this.running_ || this.isExecutionHeld() || version !== this.loopVersion_) return;
const frame = this.runFrame_(delta, Math.max(0, deltaMs));
this.frameInFlight_ = frame;
try { await frame; }
finally { if (this.frameInFlight_ === frame) this.frameInFlight_ = null; }
if (this.running_ && version === this.loopVersion_) this.queueLoopFrame_();
};
private quitting_ = false;
private quitEpoch_ = 0;
quit(options?: { keepRenderer?: boolean }): void {
if (this.quitting_) return;
this.quitting_ = true;
this.quitEpoch_++;
try { this.quit_(options); }
finally { this.quitting_ = false; }
}
private quit_(options?: { keepRenderer?: boolean }): void {
this.executionEpoch_++;
this.executionHolds_.clear();
if (this.hasResource(Input)) setInputExecutionHeld(this.getResource(Input), this, false);
this.invalidateLoop_();
this.setRunInBackground(false);
this.running_ = false;
for (let i = this.installed_plugins_.length - 1; i >= 0; i--) {
try { this.installed_plugins_[i].cleanup?.(this); } catch (e) {
log.error('app', 'Plugin cleanup error', e);
}
}
this.installed_plugins_.length = 0;
this.executionObservers_.length = 0;
this.installedPluginSet_.clear();
this.installedPluginNames_.clear();
for (const entity of this.world_.getAllEntities()) {
try { this.world_.despawn(entity); } catch (e) { log.warn('app', 'Shutdown despawn error', e); }
}
const aot = this.aot_;
this.aot_ = null;
this.runner_?.useAot(null);
try { aot?.dispose?.(); }
catch (e) { log.warn('app', 'Shutdown compiled-runtime release error', e); }
try { this.world_.releaseScriptPools(); }
catch (e) { log.warn('app', 'Shutdown script-pool release error', e); }
this.world_.disconnectCpp();
const ownedRegistry = this.ownedCppRegistry_;
this.ownedCppRegistry_ = null;
try { ownedRegistry?.delete(); }
catch (e) { log.warn('app', 'Shutdown registry release error', e); }
// After the plugins, which may still have asked it for something on their way out.
const modules = this.ownsSideModules_ ? this.sideModules_ : null;
this.ownsSideModules_ = false;
try { modules?.dispose?.(); }
catch (e) { log.warn('app', 'Shutdown module-host release error', e); }
for (const [, entries] of this.systems_) {
entries.length = 0;
}
this.sortedSystemsCache_.clear();
this.dependencyCache_.clear();
this.templateToRuntime_.clear();
this.systemCounter_ = 0;
this.pipeline_ = null;
this.runner_ = null;
this.booted_ = false;
this.aot_ = null;
// Tear down the C++ engine context too: previously quit() only cleared
// JS state and dropped the module reference, so the EstellaContext was
// never shut down — it leaked its GPU subsystems + WebGL context, and a
// later init silently reused the stale (still-"initialized") singleton.
// shutdownRenderer is null-safe (no-op if no renderer was initialized).
// `keepRenderer` skips it: hot-reload rebuilds the App but reuses the live
// module + GL + renderer (EstellaContext::shutdown destroys the WebGL
// context), so only a full quit tears the renderer down.
if (!options?.keepRenderer) {
this.module_?.shutdownRenderer?.();
this.module_ = null;
}
}
// =========================================================================
// Internal
// =========================================================================
/**
* The runner, made on demand. Making one is free and decides nothing — what
* has to happen exactly once before a frame is in `boot_`, so a caller that
* needs the runner early (a compiled-systems install) does not consume the
* boot by asking.
*/
private ensureRunner_(): SystemRunner {
if (!this.runner_) {
this.runner_ = new SystemRunner(this.world_, this.resources_, this.eventRegistry_);
// Twins prepared before there was a runner. `useCompiledSystems` can be
// called on a fresh App, and its `runner_?.useAot` would drop them for
// good — a compiled build that silently runs its closures instead.
if (this.aot_) {
this.runner_.useAot(this.aot_);
}
if (this.statsEnabled_) {
this.runner_.setTimingEnabled(true);
}
}
return this.runner_;
}
/**
* The clock, before anything asks for it. Installing compiled systems is one
* such thing and it runs BEFORE the first frame: a twin declaring `Res(Time)`
* is refused outright if this App cannot yet say what Time's fields are.
*/
private ensureSpeculation_(): void {
if (this.resources_.has(Speculation)) return;
this.resources_.insert(Speculation, new SpeculationInstance(this.world, this.resources_, this.eventRegistry_));
}
private ensureTime_(): void {
if (this.resources_.has(Time)) return;
this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });
this.ensureSpeculation_();
}
/** Once per app, on the way into the first frame: the clock every system
* reads, and the plugins' last chance to add one. */
private boot_(): void {
this.ensureRunner_();
if (this.booted_) return;
this.booted_ = true;
this.ensureTime_();
this.finishPlugins_();
}
private async runFrame_(delta: number, frameMs = delta * 1000): Promise<void> {
if (this.isExecutionHeld()) return;
const executionEpoch = this.executionEpoch_;
const current = () => !this.isExecutionHeld() && executionEpoch === this.executionEpoch_;
const frameClock = typeof performance !== 'undefined' && typeof performance.now === 'function' ? performance : null;
const frameStart = frameClock ? frameClock.now() : 0;
this.runner_?.clearTimings();
this.phaseTimings_?.clear();
this.frameScopes_?.clear();
this.eventRegistry_.swapAll();
this.world_.advanceTick();
this.updateTime(delta);
this.world_.resetQueryPool();
this.frame_paused_ = false;
if (this.isPaused() && !this.step_pending_) {
await this.runSchedule(Schedule.First, executionEpoch, true);
await this.runSchedule(Schedule.PreUpdate, executionEpoch, true);
await this.runSchedule(Schedule.Update, executionEpoch, true);
await this.runSchedule(Schedule.PostUpdate, executionEpoch, true);
await this.runSchedule(Schedule.Last, executionEpoch);
} else {
await this.runSchedule(Schedule.First, executionEpoch);
if (!current()) return;
// The SCALED delta, so Time.scale = 0 stops the fixed steps too —
// otherwise physics would keep stepping through a paused world.
this.fixedAccumulator_ += this.resources_.get(Time).delta;
let fixedSteps = 0;
// Fixed steps read the input edge mirrors (which persist across frames
// until a step consumes them) so a press on a sub-timestep frame isn't
// lost and a catch-up frame doesn't replay it. Null when no input plugin
// is installed (headless / bare App).
const input = this.resources_.has(Input) ? this.resources_.get(Input) : null;
// Direct performance.now() (not platformNow) so the budget guard needs
// no platform init (unit tests call tick() without it) and degrades to a
// no-op where performance is absent — the maxFixedSteps cap still applies.
const perf = typeof performance !== 'undefined' && typeof performance.now === 'function' ? performance : null;
const fixedStart = perf ? perf.now() : 0;
while (this.fixedAccumulator_ >= this.fixedTimestep_ && fixedSteps < this.maxFixedSteps_) {
this.fixedAccumulator_ -= this.fixedTimestep_;
// Every system inside one fixed step sees the same tick number
// (1-based) — the simulation time axis netcode stamps packets with.
this.resources_.get(Time).fixedTick++;
input?.beginFixedStep();
await this.runSchedule(Schedule.FixedPreUpdate, executionEpoch);
await this.runSchedule(Schedule.FixedUpdate, executionEpoch);
await this.runSchedule(Schedule.FixedPostUpdate, executionEpoch);
input?.endFixedStep();
if (!current()) return;
fixedSteps++;
// Stop catching up once this frame's fixed steps blow the time
// budget — drop the backlog below so we don't spiral.
if (perf && perf.now() - fixedStart >= this.fixedStepBudgetMs_) break;
}
// Hit the step cap or the time budget with a step still pending → the
// sim can't keep real-time; drop the backlog so the accumulator can't
// grow unbounded (graceful slow motion instead of a death spiral).
if (this.fixedAccumulator_ >= this.fixedTimestep_) {
this.fixedAccumulator_ = 0;
}
// Remainder fraction into the current fixed step — render-time systems
// (physics interpolation) lerp prev→current by this for smooth motion.
this.resources_.get(Time).fixedAlpha =
this.fixedTimestep_ > 0 ? this.fixedAccumulator_ / this.fixedTimestep_ : 0;
await this.runSchedule(Schedule.PreUpdate, executionEpoch);
await this.runSchedule(Schedule.Update, executionEpoch);
await this.runSchedule(Schedule.PostUpdate, executionEpoch);
await this.runSchedule(Schedule.Last, executionEpoch);
if (this.step_pending_) {
this.step_pending_ = false;
}
}
if (!current()) return;
this.frameTiming_ = {
seq: (this.frameTiming_?.seq ?? 0) + 1, frameMs,
busyMs: frameClock ? frameClock.now() - frameStart : -1,
};
for (const observe of this.frameObservers_) {
try { observe(frameMs); } catch (e) {
log.error('app', 'Frame observer error', e);
}
}
}
private finishPlugins_(): void {
if (this.pluginsFinished_) return;
this.pluginsFinished_ = true;
for (const plugin of this.installed_plugins_) {
try { plugin.finish?.(this); } catch (e) {
log.error('app', `Plugin "${plugin.name ?? 'unknown'}" finish error`, e);
}
}
}
private sortPlugins(plugins: Plugin[]): Plugin[] {
if (plugins.length <= 1) return plugins;
const nameToIndex = new Map<string, number>();
for (let i = 0; i < plugins.length; i++) {
const name = plugins[i].name;
if (name) {
if (nameToIndex.has(name)) {
log.warn('app', `Duplicate plugin name "${name}" at indices ${nameToIndex.get(name)} and ${i}`);
}
nameToIndex.set(name, i);
}
}
const edges = new Map<number, Set<number>>();
for (let i = 0; i < plugins.length; i++) {
edges.set(i, new Set());
}
for (let i = 0; i < plugins.length; i++) {
const plugin = plugins[i];
if (plugin.dependencies) {
for (const dep of plugin.dependencies) {
if (typeof dep !== 'string') continue;
const depIndex = nameToIndex.get(dep);
if (depIndex !== undefined) {
edges.get(i)!.add(depIndex);
}
}
}
if (plugin.after) {
for (const target of plugin.after) {
const targetIndex = nameToIndex.get(target);
if (targetIndex !== undefined) {
edges.get(i)!.add(targetIndex);
}
}
}
if (plugin.before) {
for (const target of plugin.before) {
const targetIndex = nameToIndex.get(target);
if (targetIndex !== undefined) {
edges.get(targetIndex)!.add(i);
}
}
}
}
const sorted: Plugin[] = [];
const visited = new Set<number>();
const visiting = new Set<number>();
const path: number[] = [];
const visit = (index: number): void => {
if (visited.has(index)) return;
if (visiting.has(index)) {
const cycleStart = path.indexOf(index);
const cycle = path.slice(cycleStart).concat(index);
const names = cycle.map(i => plugins[i].name ?? `<index ${i}>`);
throw new Error(`Circular plugin dependency: ${names.join(' -> ')}`);
}
visiting.add(index);
path.push(index);
for (const dep of edges.get(index)!) {
visit(dep);
}
path.pop();
visiting.delete(index);
visited.add(index);
sorted.push(plugins[index]);
};
for (let i = 0; i < plugins.length; i++) {
visit(i);
}
return sorted;
}
/**
* Expands an ordering name to the indices it refers to — a system, or every
* member of a set that is also in this schedule. A name matching neither
* resolves to nothing, which is how ordering against a system that was never
* registered stays a no-op rather than an error.
*/
private resolverFor(systems: readonly SystemEntry[]): ResolveTargets {
const nameToIndex = new Map<string, number>();
for (let i = 0; i < systems.length; i++) {
nameToIndex.set(systems[i].system._name, i);
}
return (name: string): number[] => {
const direct = nameToIndex.get(name);
if (direct !== undefined) return [direct];
const members = this.setMembership_.get(name);
if (!members) return [];
const out: number[] = [];
for (const m of members) {
const idx = nameToIndex.get(m);
if (idx !== undefined) out.push(idx);
}
return out;
};
}
/**
* 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.
*
* @beta
*/
scheduleAmbiguities(schedule: Schedule): Ambiguity[] {
const systems = this.systems_.get(schedule) ?? [];
return detectAmbiguities(systems, this.resolverFor(systems));
}
/**
* `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 {@link parallelBatches}.
*
* @beta
*/
scheduleBatches(schedule: Schedule): string[][] {
const systems = this.systems_.get(schedule) ?? [];
return parallelBatches(systems, this.resolverFor(systems));
}
private sortSystems(systems: SystemEntry[]): SystemEntry[] {
if (systems.length <= 1) {
return systems;
}
const resolveTargets = this.resolverFor(systems);
// `adj[i]` lists indices that must run *before* system `i` — the same
// edges the ambiguity check reads, so what orders a schedule and what
// judges its order can never be two answers.
const adj = dependencyEdges(systems, resolveTargets);
// DFS topological sort with path-aware cycle reporting.
// color: 0 = unvisited, 1 = in the current DFS stack (GRAY), 2 = done.
const GRAY = 1, BLACK = 2;
const color = new Uint8Array(systems.length);
const stack: number[] = [];
const sorted: SystemEntry[] = [];
const visit = (index: number): void => {
if (color[index] === BLACK) return;
if (color[index] === GRAY) {
const cycleStart = stack.indexOf(index);
const path = stack.slice(cycleStart).map(i => systems[i].system._name);
path.push(systems[index].system._name);
throw new Error(`Circular system dependency: ${path.join(' → ')}`);
}
color[index] = GRAY;
stack.push(index);
for (const dep of adj[index]) visit(dep);
stack.pop();
color[index] = BLACK;
sorted.push(systems[index]);
};
for (let i = 0; i < systems.length; i++) visit(i);
return sorted;
}
private startupInFlight_: Promise<void> | null = null;
private async flushStartupSystems_(): Promise<void> {
const startup = this.systems_.get(Schedule.Startup)!;
const executionEpoch = this.executionEpoch_;
while (startup.length && !this.isExecutionHeld() && !this.frame_paused_ && executionEpoch === this.executionEpoch_) {
if (!this.startupInFlight_) {
this.startupInFlight_ = Promise.resolve().then(async () => {
await this.runSchedule(Schedule.Startup, executionEpoch);
for (let index = startup.length - 1; index >= 0; index--) {
if (startup[index].startupInvoked) startup.splice(index, 1);
}
this.sortedSystemsCache_.delete(Schedule.Startup);
this.dependencyCache_.delete(Schedule.Startup);
}).finally(() => { this.startupInFlight_ = null; });
}
await this.startupInFlight_;
}
}
private async runSchedule(schedule: Schedule, executionEpoch = this.executionEpoch_, pausedOnly = false): Promise<void> {
const rawSystems = this.systems_.get(schedule);
if (!rawSystems || !this.runner_ || this.frame_paused_ || this.isExecutionHeld() || executionEpoch !== this.executionEpoch_) {
return;
}
let systems = this.sortedSystemsCache_.get(schedule);
if (!systems) {
if (rawSystems.some(s => s.runBefore || s.runAfter)) {
systems = this.sortSystems(rawSystems);
} else {
systems = rawSystems;
}
this.sortedSystemsCache_.set(schedule, systems);
}
const t0 = this.phaseTimings_ ? performance.now() : 0;
// Systems that returned a promise and have not settled. A synchronous
// system runs to completion the moment it starts, so this is empty for a
// schedule of synchronous systems and the loop below is the old one.
const inflight: InflightSystem[] = [];
const settle = async (): Promise<void> => {
const waiting = inflight.map((f) => f.done);
inflight.length = 0;
await Promise.all(waiting);
};
for (let i = 0; i < systems.length; i++) {
const entry = systems[i];
if (this.frame_paused_ || this.isExecutionHeld() || executionEpoch !== this.executionEpoch_) break;
if (schedule === Schedule.Startup && entry.startupInvoked) continue;
if (pausedOnly && !entry.system._runWhenPaused) continue;
if (entry.runIf && !entry.runIf()) { if (schedule === Schedule.Startup) entry.startupInvoked = true; continue; }
if (entry.gate && schedule !== Schedule.Startup && !this.gateOpen_(entry.gate)) continue;
// Where the declarations are spent rather than reported: a system
// starts beside an unfinished one only when it neither depends on it
// nor touches what it touches — undeclared conflicts with everything.
if (inflight.length > 0) {
const dependsOn = this.dependenciesFor(schedule, systems)[i];
const access = accessOf(entry.system);
const blocked = inflight.some(
(f) => dependsOn.has(f.index) || conflicts(access, f.access),
);
if (blocked) await settle();
}
if (this.frame_paused_ || this.isExecutionHeld() || executionEpoch !== this.executionEpoch_) break;
if (schedule === Schedule.Startup) entry.startupInvoked = true;
try {
this.currentSystem_ = entry.system._name;
const result = this.runner_.run(entry.system);
if (result instanceof Promise) {
inflight.push({
index: i,
access: accessOf(entry.system),
done: result.then(
() => { this.markSystemStepped(entry); },
(e) => { this.reportSystemError(e, entry.system._name); },
),
});
} else {
this.markSystemStepped(entry);
}
} catch (e) {
this.reportSystemError(e, entry.system._name);
} finally {
// Only meaningful for the synchronous stretch: a system parked at
// an await has no claim on it while someone else runs.
this.currentSystem_ = '';
}
}
await settle();
if (this.phaseTimings_) {
this.phaseTimings_.set(Schedule[schedule], performance.now() - t0);
}
}
/**
* What must finish before each system of `systems` may start, transitively.
*
* Ordering edges are a stronger statement than access: two systems that touch
* nothing in common may still have been ordered on purpose, and starting the
* second beside the first would silently ignore that.
*/
private dependenciesFor(schedule: Schedule, systems: readonly SystemEntry[]): Set<number>[] {
let deps = this.dependencyCache_.get(schedule);
if (!deps) {
deps = ancestors(dependencyEdges(systems, this.resolverFor(systems)));
this.dependencyCache_.set(schedule, deps);
}
return deps;
}
/** Liveness: a system ran, so its owning subsystem stepped this frame. */
private markSystemStepped(entry: SystemEntry): void {
if (entry.subsystem) this.subsystems_.markStepped(entry.subsystem);
}
/**
* Report one system's failure. Pausing stops the schedule from STARTING
* anything else; what is already in flight still has to be waited for, since
* a promise cannot be taken back.
*/
private reportSystemError(e: unknown, name: string): void {
log.error('app', `System "${name}" threw an error`, e);
if (this.error_handler_) {
this.error_handler_(e, name);
}
if (this.system_error_handler_) {
const err = e instanceof Error ? e : new Error(String(e));
if (this.system_error_handler_(err, name) === 'pause') {
this.frame_paused_ = true;
}
}
}
private updateTime(delta: number): void {
const time = this.resources_.get(Time);
const scale = time.scale >= 0 ? time.scale : 0;
time.unscaledDelta = delta;
time.delta = this.isPaused() && !this.step_pending_ ? 0 : delta * scale;
time.elapsed += time.delta;
time.frameCount++;
if (this.step_pending_) this.steppedFrames_++;
time.fixedDelta = this.fixedTimestep_;
}
}
// =============================================================================
// Web App Factory
// =============================================================================
/**
* How the host provides the render surface the C++ renderer binds to — the single
* seam every platform's renderer init flows through:
* - `gl-context`: an emscripten-registered WebGL2 context handle (web/desktop/WeChat).
* - `webgpu`: the host acquired a GPUDevice (navigator.gpu) and passed it as the
* module factory's `preinitializedWebGPUDevice` before instantiation; the engine
* owns the swapchain, resolving the canvas via `canvasSelector` (default '#canvas',
* via document.querySelector — so the canvas must be in the DOM).
* - `default`: the module resolves its own surface (module.initRenderer()).
*
* Native (wasm-on-JSC, no DOM): the host injects the device AND an already-built
* CAMetalLayer/ANativeWindow surface, so `{ kind: 'webgpu' }` omits `canvasSelector`
* and must not reach the '#canvas' fallback.
*/
export type RenderSurfaceSource =
| {
readonly kind: 'gl-context';
readonly handle: number;
/** The context is WeChat's EmscriptenGLX one, whose GL calls the linked
* library issues natively rather than through the JS glue. */
readonly glx?: boolean;
}
| {
readonly kind: 'webgpu';
readonly canvasSelector?: string;
/** Configure the swapchain so the engine can read its own frames back
* (`captureFrame`). Fixed at surface configuration, hence here. */
readonly readback?: boolean;
}
| { readonly kind: 'default' };
export interface WebAppOptions {
getViewportSize?: () => { width: number; height: number };
/**
* How the host provides the render surface (WebGL2 context handle / WebGPU
* device + swapchain / headless default). See {@link RenderSurfaceSource}.
* Omitted ⇒ `{ kind: 'default' }` (module.initRenderer resolves its own).
*/
renderSurface?: RenderSurfaceSource;
plugins?: Plugin[];
/** The realm's optional-native-module acquirer; set before plugins build so
* SpinePlugin (and later physics) can pull from it. See {@link App.sideModules}. */
sideModules?: SideModuleHost;
/** `sideModules` was made for this App alone, so quitting disposes it. See {@link App.setSideModules}. */
ownsSideModules?: boolean;
/**
* Bitmask of render layers (bits 0..31) that sort by world Y within the
* layer — top-down occlusion (lower on screen draws on top). Project-level
* setting (Project Settings → Rendering); change later via Renderer.setYSortLayers.
*/
ySortLayers?: number;
/**
* Bitmask of render layers (bits 0..31) that resolve by real depth instead of
* painter's order — the 2.5D opt-in. Opaque draws in such a layer write the
* depth buffer and sort front-to-back; blended ones test without writing and
* stay back-to-front. A layer that also y-sorts keeps y-sorting.
* Project-level setting (Project Settings → Rendering).
*/
depthLayers?: number;
/**
* Project color space (Project Settings → Rendering). 'linear' renders in
* linear light: sRGB decode on sample, linear blending in sRGB-format
* intermediates, and an explicit linear→sRGB encode in the final blit.
* Must be declared at app creation — shaders compile against it.
*/
colorSpace?: 'gamma' | 'linear';
/**
* The curve the frame applies on its way to the display, once and last. `aces`
* engages the capture the way an effect does, so a scene that asks for one goes
* through the graph even with an empty stack. Declared by the host for now — it
* is not yet a field of the project manifest. See {@link OutputTransform}.
*/
outputTransform?: OutputTransform;
/**
* Scene-target multisampling (Project Settings → Rendering). 1 turns it off;
* 4 is the default and what a browser gives its own drawing buffer. The
* device clamps it, so this is what the project WANTS, not what it gets.
*/
msaaSamples?: number;
quality?: QualityConfig;
/**
* Seed the engine's randomness so this run reproduces — a replay, a bug
* report, a pixel assertion. Absent, every run differs, which is what a
* player wants of particles.
*/
randomSeed?: number;
/**
* Project camera fit (Project Settings → Display). When set with a real
* scaleMode (≥ 0), the MAIN scene camera letterboxes this design resolution
* into the actual aspect regardless of any UI Canvas; omitted / scaleMode = -1
* keeps the legacy behavior (Canvas fit when present, else raw orthoSize). See
* {@link ScreenScaling}.
*/
screenFit?: ScreenScalingData;
}
/** The graphics API a web app's renderer draws through, as a connected device reports it. */
export type GraphicsPath = 'WebGPU' | 'WebGL2' | 'EmscriptenGLX';
interface AppSurface {
graphics: GraphicsPath | null;
size: (() => { width: number; height: number }) | null;
}
const surfaces = new WeakMap<App, AppSurface>();
/** Null for an app whose module resolved its own surface. */
export function graphicsPathOf(app: App): GraphicsPath | null {
return surfaces.get(app)?.graphics ?? null;
}
/**
* Tell @p app the size its host draws at — what a host that builds its App
* without {@link createWebApp} (the native core) does, so frame read-back and
* anything else asking {@link surfaceSizeOf} gets the same answer on every core.
* @internal
*/
export function setAppSurfaceSize(app: App, size: () => { width: number; height: number }): void {
surfaces.set(app, { graphics: surfaces.get(app)?.graphics ?? null, size });
}
/** The size the engine draws at, as its host reports it; null when the host did not say. */
export function surfaceSizeOf(app: App): { width: number; height: number } | null {
return surfaces.get(app)?.size?.() ?? null;
}
export function graphicsPathFor(surface: RenderSurfaceSource): GraphicsPath | null {
switch (surface.kind) {
case 'webgpu': return 'WebGPU';
case 'gl-context': return surface.glx ? 'EmscriptenGLX' : 'WebGL2';
case 'default': return null;
}
}
export function createWebApp(module: ESEngineModule, options?: WebAppOptions): App {
// Restore any engine components a prior project hot-reload's clearUserComponents
// wiped, so the scene about to load can still resolve them (no-op before the SDK
// entry snapshots the baseline — e.g. in unit tests that never load it).
seedEngineComponents();
const app = App.new();
if (options?.sideModules) app.setSideModules(options.sideModules, { owned: options.ownsSideModules });
const cppRegistry = new module.Registry() as unknown as CppRegistry;
try {
app.connectCpp(cppRegistry, module, { strict: true, ownedRegistry: true });
// BEFORE renderer init: shader compilation reads the color-space global.
applyColorSpace(module, options);
if (options?.randomSeed !== undefined) module.engine_setRandomSeed?.(options.randomSeed >>> 0);
const surface: RenderSurfaceSource = options?.renderSurface ?? { kind: 'default' };
switch (surface.kind) {
case 'webgpu': {
const size = options?.getViewportSize?.() ?? { width: 800, height: 600 };
// The canvas' own preference: configuring anything else makes the
// browser copy the whole frame on every present.
const preferBGRA = (navigator as unknown as {
gpu?: { getPreferredCanvasFormat?(): string };
}).gpu?.getPreferredCanvasFormat?.() === 'bgra8unorm';
if (!module.initRendererWebGPU(
surface.canvasSelector ?? '#canvas', size.width, size.height,
surface.readback === true, preferBGRA)) {
throw new Error(
'WebGPU renderer initialization failed — the module needs a ' +
'preinitializedWebGPUDevice and a WebGPU-enabled engine build.');
}
watchWebGPUDeviceLoss(module);
break;
}
case 'gl-context':
if (!module.initRendererWithContext(surface.handle)) {
throw new Error(`WebGL2 renderer initialization failed for context ${surface.handle}.`);
}
break;
case 'default':
if (!module.initRenderer()) {
throw new Error('WebGL2 renderer initialization failed for the default canvas.');
}
break;
}
surfaces.set(app, { graphics: graphicsPathFor(surface), size: options?.getViewportSize ?? null });
applyFrameOptions(module, options);
app.addPlugin(corePlugin);
app.setPipeline(new RenderPipeline());
app.insertResource(UICameraInfo, { ...DEFAULT_UI_CAMERA_INFO });
app.insertResource(ScreenLayout, { ...ScreenLayout._default });
app.insertResource(ScreenOverlay, defaultScreenOverlay());
app.addPlugin(cameraPlugin(options?.getViewportSize));
app.addPlugin(assetPlugin);
app.addPlugin(prefabsPlugin);
app.addPlugin(breakablePlugin);
app.addPlugin(inputPlugin);
app.addPlugin(sceneManagerPlugin);
if (options?.plugins) {
app.addPlugins(options.plugins);
}
applyAppOptions(app, options);
return app;
} catch (error) {
try { app.quit({ keepRenderer: true }); }
catch (releaseError) { log.warn('app', 'Failed web App construction cleanup error', releaseError); }
throw error;
}
}
/**
* Install a {@link Plugin} from a project bundle — the module-level twin of
* {@link App.addPlugin}, and the door a plugin PACKAGE is installed through: a
* bundle is imported before an App exists.
*
* @experimental
*/
export function addPlugin(plugin: Plugin): void {
getDefaultContext().pendingPlugins.push(plugin);
}
/**
* Install everything a project bundle registered at module level. One door, so a
* host cannot drain half of it — plugins first, because a project's own system
* may read a resource one of them inserts.
*
* @experimental
*/
export function flushPendingRegistrations(app: App): void {
const context = getDefaultContext();
for (const plugin of context.drainPendingPlugins()) app.addPlugin(plugin as Plugin);
app.addBundleSystems(context.drainPendingSystems() as ReadonlyArray<{ schedule: number; system: SystemDef }>);
}