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 runtimeLoader.ts
* @brief Runtime scene loader for builder targets (WeChat, Playable, etc.)
*/
import { SceneOwner } from '../ecs/component';
import { loadSceneData, updateCameraAspectRatio, sceneHasPrefabEntries, expandScenePrefabs, type SceneData } from '../scene/scene';
import { registerDeferredInstances } from '../scene/deferredInstances';
import { recordSceneOrigins, enableSceneOrigins } from '../scene/sceneOrigins';
import { defineResource } from '../ecs/resource';
import type { Entity } from '../types';
import type { PrefabData } from '../prefab/types';
import { switchTheme, resolveThemeTokens, type ThemeOverrides } from '../ui';
import { discoverSceneAssets } from '../asset/discoverAssets';
import type { ESEngineModule } from '../wasm';
import type { SpineWasmModule } from '../spine/SpineModuleLoader';
import type { SpineManager } from '../spine/SpineManager';
import type { PhysicsWasmModule } from '../physics/PhysicsModuleLoader';
import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { Physics3DWasmModule } from '../physics3d/Physics3DModule';
import { applyAudioProjectConfig, type AudioProjectConfig } from '../audio/AudioProjectConfig';
import type { App } from '../app/app';
import { Assets as AssetsClass } from '../asset/Assets';
import { Assets as AssetsResource } from '../asset/AssetPlugin';
import { bindAssetReferenceTracking } from '../asset/assetReferenceTracking';
import { basisTranscoderFor } from '../asset/basisWorkers';
import type { BasisTranscoder } from '../asset/compressed';
import type { TextureImportSettings } from '../asset/loaders/TextureLoader';
import { SceneManager, type SceneConfig } from '../scene/sceneManager';
import { readyMeshPrograms } from '../render/meshProgramReadiness';
import { shadersCompiled } from '../render/shaderWarmup';
import type { RenderReadiness } from '../render/renderReadiness';
import { WorldStreaming } from '../residency/WorldStreamer';
import { persistentEntityRows } from '../residency/identity';
import type { WorldManifest } from '../residency/cells';
import { DEFAULT_GRAVITY, DEFAULT_FIXED_TIMESTEP, applyBuildRuntimeConfig, type RuntimeBuildConfig } from '../defaults';
import { SpriteAnimation } from '../animation/SpriteAnimator';
import { Audio } from '../audio/Audio';
import { Achievements } from '../services/achievements';
import { getPlatform } from '../platform/base';
import { Localization, matchLocale } from '../i18n/Localization';
import { LocalizationPlugin } from '../i18n/LocalizationPlugin';
import { platformLanguage } from '../platform';
import { flushPendingRegistrations } from '../app/app';
import { installHotUpdateRebind } from '../hotUpdateRebind';
import { requireResourceManager } from '../wasm/resourceManager';
import { log } from '../util/logger';
import { startDebugChannel, attachDebugChannel } from './debugChannelHook';
import type { DebugChannelConfig } from './debugChannelProtocol';
import type { AotManifest } from '../ecs/aot/AotSystems';
import { type RuntimeAssetSource, type TextureParams } from './runtimeAssets';
import type { SpineAssetInfo } from '../spine/loadSpineScene';
import type { SceneAssetResult } from '../asset/Assets';
import type { DragonBonesManager } from '../dragonbones/DragonBonesManager';
import {
spineSupport, dragonBonesSupport, physicsSupport, physics3dSupport, videoSupport,
} from './sceneOptionals';
import type { DragonBonesAssetInfo } from '../dragonbones/loadDragonBonesScene';
import type { AddressableManifest, ManifestModel } from '../asset/AddressableManifest';
import type { Catalog } from '../asset/Catalog';
import { physics3dModuleId, type Physics3DBackend } from '../sideModules/registry';
import { physics3DInstallConfig, type Physics3DWorldConfig } from '../physics3d/worldConfig';
import { setWorldUnitsPerMeter, REFERENCE_UNITS_PER_METER } from '../ecs/worldUnits';
// =============================================================================
// Public Interface
// =============================================================================
// RuntimeAssetSource + createTextureFromPixels live in ./runtimeAssets so the
// spine scene loader can share them without importing this module.
export type { RuntimeAssetSource } from './runtimeAssets';
// =============================================================================
// Per-App runtime Assets channel
// =============================================================================
// Marks Assets instances built here and holds their merged per-scene texture
// import settings, so later scene loads extend the map instead of replacing
// the instance (and so `ensureRuntimeAssets` can tell its own instance apart
// from the default AssetPlugin one it must replace).
const runtimeImportSettings = new WeakMap<AssetsClass, Record<string, TextureImportSettings>>();
/**
* The per-App runtime `Assets`, loading through the single canonical asset
* channel driven by the realm's `RuntimeAssetSource`:
* - fetch (text/binary, incl. KTX2 containers) → `source.backend`
* - texture pixels → `source.decodePixels` (handles `estella://` / WeChat
* package files / inlined data-URLs that a URL `<img>` can't)
* - KTX2 transcode → the same self-gating Basis side-module the editor wires
* `source.resolveRef` is the single ref resolver, so refs resolve to their real
* (extension-bearing) build paths before KTX2 detection and fetch.
*
* Created ONCE per App and installed as the app resource, replacing the default
* AssetPlugin instance (whose HttpBackend/URL `<img>` decode can't read this
* realm's sources). Every later scene load reuses it, so caches, refcounts and
* the addressable manifest survive scene switches — `Assets.loadGroup` keeps
* working after the first scene, and re-entering a scene revives resident
* textures instead of re-decoding. The first scene load's `source` wins; one
* App is expected to keep one asset source for its lifetime. Reference tracking
* shares the same World observer as AssetPlugin, including native runtimes.
*/
function ensureRuntimeAssets(
app: App, module: ESEngineModule | null, source: RuntimeAssetSource, catalog?: Catalog,
): AssetsClass {
if (app.hasResource(AssetsResource)) {
const existing = app.getResource(AssetsResource);
if (runtimeImportSettings.has(existing)) return existing;
}
const assets = AssetsClass.create({
backend: source.backend,
module,
catalog,
getAudio: () => (app.hasResource(Audio) ? app.getResource(Audio) : null),
getSpriteAnimation: () => (app.hasResource(SpriteAnimation) ? app.getResource(SpriteAnimation) : null),
getLocalization: () => (app.hasResource(Localization) ? app.getResource(Localization) : null),
});
if (source.resolveRef) assets.setAssetRefResolver(source.resolveRef);
const loader = assets.getTextureLoader();
loader.setPixelDecoder((path, flip, maxEdge) => source.decodePixels(path, flip, maxEdge));
if (source.compressedTexture) loader.setCompressedSource((path) => source.compressedTexture!(path));
// KTX2 transcoder, self-gated off app.sideModules — identical wiring to
// AssetPlugin.build so eager + on-demand loads transcode the same way.
loader.setTranscoderProvider(() => basisTranscoderFor(app.sideModules));
// Two suppliers, one resolver, in precedence order:
// - the REALM's asset source describes the ASSET (the editor's database, a
// cooked build's manifest) and is authoritative;
// - the per-scene map below is the embedder's channel for a scene that
// carries its own `textureImporterSettings`.
// Asset-level wins: a stale copy inside a scene must not override what the
// asset actually says today.
const settings: Record<string, TextureImportSettings> = {};
assets.setTextureImportSettingsResolver(
(ref) => source.textureImportSettings?.(ref) ?? settings[ref],
);
runtimeImportSettings.set(assets, settings);
bindAssetReferenceTracking(app.world, assets,
() => app.hasResource(AssetsResource) ? app.getResource(AssetsResource) : null);
app.insertResource(AssetsResource, assets);
return assets;
}
/**
* Merge a scene's stored per-texture import settings (filter/wrap) into the
* runtime Assets' resolver map. Keys normalize through resolveRef so they match
* the resolved path the TextureLoader sees; the stored {filterMode,wrapMode}
* shape maps to the loader's {filter,wrap}. Merging (not replacing) keeps
* settings from previously loaded scenes live — the same texture carries the
* same .meta-derived settings in every scene, so last-wins is safe.
*/
function mergeSceneTextureImportSettings(
assets: AssetsClass, sceneData: SceneData, resolveRef: (ref: string) => string,
): void {
const settings = runtimeImportSettings.get(assets);
const rawSettings = (sceneData as { textureImporterSettings?: Record<string, TextureParams> })
.textureImporterSettings;
if (!settings || !rawSettings) return;
for (const [ref, s] of Object.entries(rawSettings)) {
settings[resolveRef(ref)] = {
filter: s.filterMode as TextureImportSettings['filter'],
wrap: s.wrapMode as TextureImportSettings['wrap'],
srgb: s.srgb,
};
}
}
/** Apply 9-slice borders to loaded textures. `textureHandles` is keyed by the
* resolved build path (Assets discovery resolves refs), so the metadata's
* stored ref is resolved the same way before lookup. */
function applyTextureMetadata(
sceneData: SceneData,
textureHandles: Map<string, number>,
resolveRef: (ref: string) => string,
): void {
if (!sceneData.textureMetadata) return;
const rm = requireResourceManager();
for (const [ref, metadata] of Object.entries(sceneData.textureMetadata)) {
const handle = textureHandles.get(resolveRef(ref));
if (handle && metadata?.sliceBorder) {
const b = metadata.sliceBorder;
rm.setTextureMetadata(handle, b.left, b.right, b.top, b.bottom);
}
}
}
// =============================================================================
// Public API
// =============================================================================
export interface LoadRuntimeSceneOptions {
/** Authored ids this scene may reference in ANOTHER document — the persistent
* rows a streamed cell names. See {@link SceneLoadOptions.externalEntities}. */
externalEntities?: ReadonlyMap<number, Entity>;
/** Where this load spent its time. See {@link SceneLoadOptions.onPhase}. */
onPhase?: (phase: string, ms: number) => void;
app: App;
/** The wasm module, or null on a native host — the engine core is arm64 there,
* so there is no Module to reach through. */
module: ESEngineModule | null;
sceneData: SceneData;
source: RuntimeAssetSource;
spineModule?: SpineWasmModule | null;
spineManager?: SpineManager | null;
physicsModule?: PhysicsWasmModule | null;
/** Project-declared physics world config (gravity, solver tuning, collision-layer
* masks, sleep/continuous toggles) — threaded from the editor's Project Settings. */
physicsConfig?: Physics2DPluginConfig;
/** The 3D physics backend; selects the side module the 3D world is acquired from. Absent ⇒ Jolt. */
physics3dBackend?: Physics3DBackend;
/** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */
physics3dWorld?: Partial<Physics3DWorldConfig>;
/** Project-declared physics enable (`.uproject` features analog) — installs
* physics even for runtime-spawned bodies the static scene doesn't show.
* OR-combined with a content scan. */
physicsEnabled?: boolean;
/** An already-resolved 3D physics module, for tests and headless hosts. */
physics3dModule?: Physics3DWasmModule;
/** Project-declared UI theme (Project Settings → UI). Dark is the default;
* 'light' switches the token set AND re-resolves already-instantiated
* ThemeStyle-tagged widgets (prefab instances carry dark baked values). */
uiTheme?: 'dark' | 'light';
/** Project-declared partial re-skin over the base theme (Project Settings →
* UI theme colors); merged via {@link resolveThemeTokens}. */
uiThemeOverrides?: ThemeOverrides;
sceneName?: string;
}
/** Component types whose presence means a scene needs the physics subsystem. */
const PHYSICS_COMPONENT_TYPES = new Set([
'RigidBody2D', 'BoxCollider2D', 'CircleCollider2D', 'CapsuleCollider2D',
'SegmentCollider2D', 'PolygonCollider2D', 'ChainCollider2D',
]);
/** The same question for the 3D world, which is a different module entirely. */
const PHYSICS3D_COMPONENT_TYPES = new Set([
'RigidBody3D', 'BoxCollider3D', 'SphereCollider3D', 'CapsuleCollider3D',
'MeshCollider3D', 'ConvexCollider3D', 'CharacterController3D',
'CompoundCollider3D', 'Ragdoll',
'PointJoint3D', 'HingeJoint3D', 'SliderJoint3D', 'DistanceJoint3D', 'FixedJoint3D', 'SwingTwistJoint3D', 'SixDOFJoint3D',
]);
/** True if any entity carries a 3D physics component. */
export function sceneUses3DPhysics(sceneData: SceneData): boolean {
for (const entity of sceneData.entities ?? []) {
for (const comp of entity.components ?? []) {
if (PHYSICS3D_COMPONENT_TYPES.has(comp.type)) return true;
}
}
return false;
}
/** True if any Text or TextInput hint binds to a localization key — the scene needs
* the Localization resource + the project's `.eslocale` tables to render as
* authored (an unbound key would show as the raw key string). */
export function sceneUsesI18n(sceneData: SceneData): boolean {
for (const entity of sceneData.entities ?? []) {
for (const comp of entity.components ?? []) {
const data = comp.data as { i18nKey?: unknown; placeholderI18nKey?: unknown } | undefined;
const key = comp.type === 'Text' ? data?.i18nKey
: comp.type === 'TextInput' ? data?.placeholderI18nKey : undefined;
if (typeof key === 'string' && key.length > 0) return true;
}
}
return false;
}
/**
* Subsystem installs already in flight for this app.
*
* Every self-gating install below is a check, then an await for the module, then
* an addPlugin — and two scenes arriving in one tick both pass the check. World
* streaming makes that ordinary rather than rare.
*/
const SubsystemInstalls = defineResource<Map<string, Promise<void>>>(null!, 'SubsystemInstalls');
/**
* Run `install` with no other caller for `key` inside it.
*
* The loop, rather than awaiting once: what finished was ANOTHER scene's
* install, and this one still has to decide against the world that left behind.
*/
async function installOnce(app: App, key: string, install: () => Promise<void>): Promise<void> {
if (!app.hasResource(SubsystemInstalls)) app.insertResource(SubsystemInstalls, new Map());
const inFlight = app.getResource(SubsystemInstalls);
let running = inFlight.get(key);
while (running) { await running; running = inFlight.get(key); }
const started = install().finally(() => { inFlight.delete(key); });
inFlight.set(key, started);
await started;
}
/** True if any entity carries a physics component, or a TilemapLayer that may spawn
* colliders at runtime — either baked collidable tile ids (legacy scenes) or a
* `.estileset` reference, whose collision shapes derive live at load and are
* invisible to a component scan. A visual-only tileset costs one unused physics
* module load; missing real tile colliders would break the scene. */
export function sceneUsesPhysics(sceneData: SceneData): boolean {
for (const entity of sceneData.entities ?? []) {
for (const comp of entity.components ?? []) {
if (PHYSICS_COMPONENT_TYPES.has(comp.type)) return true;
if (comp.type === 'TilemapLayer') {
const data = comp.data as Record<string, unknown> | undefined;
const ids = data?.collidableTileIds;
if (Array.isArray(ids) && ids.length > 0) return true;
if (typeof data?.tilesetAsset === 'string' && data.tilesetAsset !== '') return true;
}
}
}
return false;
}
/**
* A cell's load, done as far as it can go without the world seeing anything.
*
* Preparation may speculate about future residency and may own data and assets;
* only publication may create runtime entities. That is the whole contract, and
* it is what makes "prepared" impossible to observe: there is nothing to see.
*
* @experimental
*/
export interface PreparedRuntimeScene {
readonly name: string | undefined;
/** What publication still needs; nothing here is in the world. */
readonly options: LoadRuntimeSceneOptions;
readonly sceneData: SceneData;
readonly assetResult: SceneAssetResult;
readonly spineManager: SpineManager | null;
readonly spineAssetInfo: Map<string, SpineAssetInfo>;
readonly dragonBonesManager: DragonBonesManager | null;
readonly dragonBonesAssetInfo: Map<string, DragonBonesAssetInfo>;
readonly discovered: ReturnType<typeof discoverSceneAssets>;
}
/**
* Everything a scene load can do before the world can tell: fetch, expand,
* acquire, install the subsystems it needs. Creates no entities.
*
* The receipts are OWNED by what this returns — publishing moves them to the
* scene, discarding gives them back. Never both, never acquired twice.
*
* @experimental
*/
export async function prepareRuntimeScene(
options: LoadRuntimeSceneOptions,
): Promise<PreparedRuntimeScene> {
const { app, module, source, physicsConfig, physicsEnabled, uiTheme, uiThemeOverrides, sceneName } = options;
const onPhase = options.onPhase;
const timed = async <T>(phase: string, run: () => Promise<T> | T): Promise<T> => {
if (!onPhase) return run();
const began = performance.now();
try { return await run(); } finally { onPhase(phase, performance.now() - began); }
};
// The SpineManager is owned by SpinePlugin (built from the realm's
// app.sideModules host); read it from there so every realm — play / playable /
// wechat — loads spine assets through one manager. An explicit option still
// wins for headless/tests.
const spine = spineSupport();
const spineManager = options.spineManager ?? spine?.manager(app) ?? null;
// Expand prefab instances up front: an exported scene keeps them as a prefab
// ref + overrides (the cook does not flatten them), and the rest of this
// pipeline — discovery, preload, the synchronous loadSceneData spawn — operates
// on plain entities and skips a prefab entry. This is the same expansion
// loadSceneWithAssets runs for the editor's play realm, so a packaged game
// spawns prefab instances exactly as Play does (play == ship), instead of
// silently dropping them.
const runtimeAssets = ensureRuntimeAssets(app, module, source);
// A private copy: resolution below writes handles over the asset refs, and the
// document given here is the one a registered scene loads from every time. A
// reload of the mutated one found no ref to acquire and spawned the handles the
// outgoing scene had just released, so a restarted scene drew its images white.
let sceneData = JSON.parse(JSON.stringify(options.sceneData)) as SceneData;
if (sceneHasPrefabEntries(sceneData)) {
sceneData = await timed('prefab', () => expandScenePrefabs(sceneData, async (ref) => {
try {
return ((await runtimeAssets.loadPrefab(ref))?.data as PrefabData) ?? null;
} catch (e) {
log.warn('scene', `Failed to load prefab "${ref}": ${e instanceof Error ? e.message : String(e)}`);
return null;
}
}));
}
// Spine pairs (raw refs) for the two-phase spine load+apply below; every
// other asset type loads through the single canonical Assets channel.
const discoverBegan = onPhase ? performance.now() : 0;
const discovered = discoverSceneAssets(sceneData);
// Eager scene assets (textures / fonts / materials / anim-clips / tilemaps /
// audio) load through the single canonical Assets channel — one per-type
// loader implementation, shared with the editor — driven by this realm's
// source. The instance is per-App (installed as the app resource, so plugins
// that resolve `@uuid:` refs at runtime — e.g. the tilemap plugin — find the
// SAME resolver the preload keyed the caches with) and persists across scene
// loads. Spine stays a two-phase load+apply below (skipSpine).
const sceneAssets = runtimeAssets;
// Video source refs resolve through the SAME channel as every other asset
// (the editor's play realm wires this too) — a cooked build maps the
// authored logical ref (clip.mp4 / @uuid) to its staged .esv. The staged path
// then goes through the realm's backend, because what a video element needs is
// a URL it can open: identity for http/filesystem realms, the inlined data URL
// for the single-file playable (where there is no file to fetch at all).
if (source.resolveRef) {
const resolveRef = source.resolveRef;
const backend = source.backend;
videoSupport()?.setRefResolver(app, (ref) => backend.resolveUrl(resolveRef(ref)));
}
mergeSceneTextureImportSettings(sceneAssets, sceneData, source.resolveRef ?? ((r) => r));
// Two full walks of the document before a byte is fetched. Named because
// they scale with the cell and not with what it references, which is not
// what "asset discovery" sounds like it costs.
if (onPhase) onPhase('discover', performance.now() - discoverBegan);
const assetResult = await timed('assets',
() => sceneAssets.preloadSceneAssets(sceneData, undefined, { skipSpine: true }));
sceneAssets.resolveSceneAssetPaths(sceneData, assetResult);
applyTextureMetadata(sceneData, assetResult.textureHandles, source.resolveRef ?? ((ref) => ref));
// KTX2 atlas pages transcode through the realm's basis module, acquired the
// same lazy way the TextureLoader's provider does (AssetPlugin). Spine itself
// rides `app.sideModules` — a fetched wasm module on the web, the runtime
// compiled into the binary on a device — so what decides here is whether the
// realm has an acquirer at all, not whether it has a wasm engine module (the
// atlas upload takes bytes without one).
if (!app.sideModules && discovered.spines.length > 0) {
log.warn('scene', `${discovered.spines.length} spine asset(s) skipped — `
+ 'this realm has no optional-module host to load a Spine runtime from');
}
const transcoderProvider = (): Promise<BasisTranscoder | null> => basisTranscoderFor(app.sideModules);
const subsystemsBegan = onPhase ? performance.now() : 0;
// Prepared by the realm, owned by the scene: the receipts join the scope
// this scene gives back, and a second scene of one spine asset joins its era
// instead of uploading its pages again.
if (discovered.spines.length > 0 && !spine) {
log.warn('scene', `${discovered.spines.length} Spine asset(s) skipped — this build ships`
+ ' without the Spine runtime');
}
const spineAssetInfo = app.sideModules && spine
? await spine.load(module, source, spineManager, discovered.spines, transcoderProvider,
{ assets: sceneAssets, scope: assetResult.scope })
: new Map<string, SpineAssetInfo>();
// DragonBones, the same two phases. The manager is acquired only when the
// scene actually holds an armature — the plugin fetches its wasm on the first
// ask, so a scene without one costs nothing.
let dragonBonesManager: DragonBonesManager | null = null;
let dragonBonesAssetInfo = new Map<string, DragonBonesAssetInfo>();
if (discovered.dragonBones.length > 0) {
if (!app.sideModules) {
log.warn('scene', `${discovered.dragonBones.length} DragonBones asset(s) skipped — `
+ 'this realm has no optional-module host to load the DragonBones runtime from');
} else {
dragonBonesManager = (await dragonBonesSupport()?.acquire(app)) ?? null;
if (!dragonBonesManager) {
log.warn('scene', dragonBonesSupport()
? 'DragonBones assets present but the runtime could not be loaded'
: 'DragonBones assets present but this build ships without the runtime');
} else {
dragonBonesAssetInfo = await dragonBonesSupport()!.load(
module, source, discovered.dragonBones, transcoderProvider);
}
}
}
// Self-gating: install physics when the project declares it OR the scene uses
// it, so no runtime entry can forget to wire it. The module comes from the
// realm's side-module host (app.sideModules) — fetch / inlined / WeChat — or
// an explicit override for tests. Install once via addPlugin (also registers
// it in the observability surface).
let physicsModule = options.physicsModule ?? null;
const wantsPhysics = !!physicsEnabled || sceneUsesPhysics(sceneData);
if (!wantsPhysics) {
log.info('physics', 'not installed — not declared (features.physics) and scene has no physics components');
} else {
await installOnce(app, 'physics', async () => {
if (!physicsModule && app.sideModules) {
physicsModule = (await app.sideModules.acquire('physics')) as PhysicsWasmModule | null;
}
if (!physicsModule) {
log.warn('physics', `wanted (declared=${!!physicsEnabled}) but no module loaded — this realm has no side-module host or physics.wasm failed to load`);
} else if (!physicsSupport()) {
log.warn('physics', 'wanted, but this build ships without the 2D physics runtime');
} else if (!physicsSupport()!.installed(app)) {
const gravity = physicsConfig?.gravity ?? { ...DEFAULT_GRAVITY };
const config: Physics2DPluginConfig = {
gravity,
fixedTimestep: physicsConfig?.fixedTimestep ?? DEFAULT_FIXED_TIMESTEP,
subStepCount: physicsConfig?.subStepCount ?? 4,
contactHertz: physicsConfig?.contactHertz ?? 120,
contactDampingRatio: physicsConfig?.contactDampingRatio ?? 10,
contactSpeed: physicsConfig?.contactSpeed ?? 10,
};
// Pass through the remaining world config only when the project set it, so
// the plugin's own defaults still apply otherwise.
if (physicsConfig?.collisionLayerMasks) config.collisionLayerMasks = physicsConfig.collisionLayerMasks;
if (physicsConfig?.enableSleep !== undefined) config.enableSleep = physicsConfig.enableSleep;
if (physicsConfig?.enableContinuous !== undefined) config.enableContinuous = physicsConfig.enableContinuous;
physicsSupport()!.install(app, config, physicsModule);
log.info('physics', `installed (gravity ${gravity.x}, ${gravity.y})`);
}
});
}
// The 3D world gates itself the same way, on its own components and its own
// module: the two never share a solver, so a scene wanting one is not asking
// for the other.
if (sceneUses3DPhysics(sceneData)) {
await installOnce(app, 'physics3d', async () => {
const p3d = physics3dSupport();
if (!p3d) {
log.warn('physics3d', 'scene has 3D physics components but this build ships'
+ ' without the 3D physics runtime');
return;
}
if (p3d.installed(app)) return;
const module3d = options.physics3dModule
?? (app.sideModules
? (await app.sideModules.acquire(physics3dModuleId(options.physics3dBackend))) as Physics3DWasmModule | null
: null);
if (!module3d) {
log.warn('physics3d', 'scene has 3D physics components but no module loaded —'
+ ` this realm has no side-module host or the ${options.physics3dBackend ?? 'jolt'} module failed to load`);
return;
}
const config3d = physics3DInstallConfig(options.physics3dWorld, physicsConfig);
p3d.install(app, module3d, config3d);
log.info('physics3d', `installed (${config3d.pixelsPerUnit ?? 100} units per metre)`);
});
}
// Self-gating i18n, mirroring physics: a scene that binds Text.i18nKey needs
// the Localization resource + the shipped `.eslocale` tables — installed and
// loaded here so no runtime entry can forget. Tables come from the realm's
// OWN asset list (they're loaded by key, never referenced by the scene).
// Idempotent across scene switches: the resource persists, table loads hit
// the Assets cache, addCatalog merges. Awaited so the first frame renders
// words, not raw keys.
if (sceneUsesI18n(sceneData)) {
const autoInstalled = !app.hasResource(Localization);
if (autoInstalled) app.addPlugin(new LocalizationPlugin());
const tables = (source.listAssetPaths?.() ?? []).filter((p) => p.toLowerCase().endsWith('.eslocale'));
if (tables.length === 0) {
log.warn('i18n', 'scene binds a localization key but this realm lists no .eslocale tables — keys will render raw');
} else {
await Promise.all(tables.map((p) => sceneAssets.loadLocaleTable(p).catch((e: unknown) => {
log.error('i18n', `locale table ${p} failed to load: ${e instanceof Error ? e.message : String(e)}`);
})));
log.info('i18n', `installed — ${tables.length} locale table(s)`);
}
if (autoInstalled) {
// Auto-installed ⇒ nobody configured a locale: follow the player's
// system language when a shipped table matches. A game that installs
// the plugin itself (or calls setLocale later) is never overridden.
const i18n = app.getResource(Localization);
const picked = matchLocale(platformLanguage(), i18n.availableLocales());
if (picked) i18n.setLocale(picked);
}
}
// Loading the runtimes a cell's content needs, and the tables it binds. All
// of it self-gating and installed once, so the first cell of a world pays
// for the world and the ones after it pay for their own content only.
if (onPhase) onPhase('subsystems', performance.now() - subsystemsBegan);
// The one place a packaged scene's entities come into being. `externalEntities`
// is what lets a streamed cell name the persistent world: without it a cross
// document reference resolves to nothing, quietly.
return {
name: sceneName, options, sceneData, assetResult,
spineManager, spineAssetInfo, dragonBonesManager, dragonBonesAssetInfo, discovered,
};
}
/**
* Bring a prepared scene into the world.
*
* The publication boundary: before this returns no system has seen a single one
* of the cell's entities, because none of them existed. Nothing downstream has
* to learn to ignore a half-arrived cell.
*
* @experimental
*/
export async function publishRuntimeScene(
prepared: PreparedRuntimeScene,
// Resolved HERE and not at preparation: between the two the target may have
// gone, the world may have switched, a generation may have moved. A prepared
// scene holding a runtime handle would be holding a guess.
now?: { externalEntities?: ReadonlyMap<number, Entity> },
): Promise<void> {
const { sceneData, assetResult, spineManager, spineAssetInfo,
dragonBonesManager, dragonBonesAssetInfo, discovered } = prepared;
const options = now?.externalEntities
? { ...prepared.options, externalEntities: now.externalEntities }
: prepared.options;
const { app, module, uiTheme, uiThemeOverrides, sceneName } = options;
const onPhase = options.onPhase;
const timed = async <T>(phase: string, run: () => Promise<T> | T): Promise<T> => {
if (!onPhase) return run();
const began = performance.now();
try { return await run(); } finally { onPhase(phase, performance.now() - began); }
};
/**
* The synchronous sibling of `timed`, for the steps that ARE synchronous.
*
* `timed` is `async`, so measuring these with it opens a microtask gap per
* step through which another cell's publication could interleave — an
* instrument that changed the thing it measures.
*/
const mark = <T>(phase: string, run: () => T): T => {
if (!onPhase) return run();
const began = performance.now();
try { return run(); } finally { onPhase(phase, performance.now() - began); }
};
void discovered;
const entityMap = await timed('spawn',
() => loadSceneData(app.world, sceneData, options.externalEntities, onPhase));
app.getResource(AssetsResource).trackSceneAssetReferences(sceneData, entityMap);
registerDeferredInstances(app.world, sceneData.deferredInstances, entityMap);
// Which document row each entity came from, when someone is keeping track
// (an editor inspecting its own running game). No-op otherwise.
mark('origins', () => recordSceneOrigins(app, entityMap));
// Apply the project theme over the freshly instantiated scene: prefabs bake
// the default dark palette, so a light base or any token override re-resolves
// every ThemeStyle tag.
if (uiTheme === 'light' || uiThemeOverrides) {
mark('theme', () => switchTheme(app.world, resolveThemeTokens(uiTheme ?? 'dark', uiThemeOverrides)));
}
const cppRegistry = app.world.getCppRegistry();
// Fold the loaded transforms into world matrices once, before the first frame.
// Native hosts run their own TransformSystem each frame instead.
if (cppRegistry && module) {
mark('transform', () => module.transform_update(cppRegistry));
}
const spine = spineSupport();
if (spineManager && cppRegistry && spine) {
await timed('spine', () => spine.apply({ spineManager, sceneData, entityMap, registry: cppRegistry, assetInfo: spineAssetInfo }));
}
if (dragonBonesManager) {
mark('dragonbones', () => dragonBonesSupport()!.apply({
manager: dragonBonesManager, sceneData, entityMap, assetInfo: dragonBonesAssetInfo,
}));
}
if (sceneName && app.hasResource(SceneManager)) {
// Adopt into the SceneManager's instance set so unload/switchTo actually
// despawns these entities — SceneOwner alone is only the persistence tag.
const ctx = app.getResource(SceneManager).getScene(sceneName);
mark('adopt', () => {
for (const entity of entityMap.values()) {
if (ctx) ctx.adopt(entity);
else app.world.insert(entity, SceneOwner, { scene: sceneName, persistent: false });
}
// The RECEIPTS, not the paths: after a hot update a path-addressed
// release gives back the oldest era, which belongs to whoever loaded
// before the update.
ctx?.trackAssetScope(assetResult.scope);
});
}
}
/**
* Prepare a scene and publish it. What every caller outside residency wants, and
* the shape the two halves are defined against.
*/
export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promise<void> {
await publishRuntimeScene(await prepareRuntimeScene(options));
}
export function createRuntimeSceneConfig(
name: string,
sceneData: SceneData | undefined,
options: Omit<LoadRuntimeSceneOptions, 'sceneData' | 'sceneName'>,
scenePath?: string,
): SceneConfig {
// Built first and closed over, so whoever sets `externalEntities` / `onPhase`
// on the CONFIG is honoured here too: declared in one place and read in
// another, a cell's reference to the persistent world resolved to nothing.
// Held by the config, which IS the per-scene object: a prepared cell has one
// place to live and one owner to release it.
let prepared: PreparedRuntimeScene | null = null;
const readied = async (): Promise<PreparedRuntimeScene> => {
let data = sceneData;
if (!data) {
// Lazy scene: fetched by path through the per-App runtime Assets, so
// the data arrives via the realm's own backend — http on web, wx fs
// on WeChat — and only when something asks for the scene.
if (!scenePath) throw new Error(`scene "${name}" registered with neither data nor path`);
const began = performance.now();
data = await options.app.getResource(AssetsResource).fetchJson<SceneData>(scenePath);
config.onPhase?.('fetch', performance.now() - began);
}
return prepareRuntimeScene({
...options, sceneData: data, sceneName: name, onPhase: config.onPhase,
});
};
const config: SceneConfig = {
name,
async prepare() {
if (prepared === null) prepared = await readied();
},
// The second obligation. It runs on what `prepare` decoded, so the mesh
// references are already handles; readying from an unprepared scene would
// describe requirements for geometry nothing has acquired.
async readyRenderPrograms() {
if (prepared === null) return { applicable: false } as RenderReadiness;
const readied = readyMeshPrograms(options.module, prepared.sceneData);
// Queued compiles are not ready programs: where shaders compile in the background, the claim waits for them.
if (readied.applicable) await shadersCompiled(options.module);
return readied;
},
discardPrepared() {
// Speculation is not authority: what nobody asked for is given back,
// receipts included, rather than published because it was ready.
const owed = prepared?.assetResult.scope.size ?? 0;
prepared?.assetResult.scope.releaseAll();
prepared = null;
return owed;
},
async setup() {
const ready = prepared ?? await readied();
prepared = null;
await publishRuntimeScene(ready, { externalEntities: config.externalEntities?.() });
},
};
return config;
}
export interface RuntimeInitConfig {
app: App;
/** The wasm module, or null on a native host (see LoadRuntimeSceneOptions). */
module: ESEngineModule | null;
source: RuntimeAssetSource;
/**
* Addressable manifest for the app's Assets, enabling `Assets.loadGroup`
* (on-demand groups / subpackages) from game code. Set here — on the
* per-App runtime instance — rather than on whatever Assets resource
* existed before initRuntime, which the runtime instance replaces.
*/
manifest?: AddressableManifest | ManifestModel | null;
/** CDN root that `remote`-group assets resolve against ({@link Assets.setRemoteRoot}) —
* enables hot-update delivery from a remote origin. */
remoteRoot?: string;
/** Storage key an applied hot-update persists the manifest under. When set,
* initRuntime restores any manifest a prior run persisted there — a returning
* player boots on the updated content ({@link Assets.restorePersistedUpdate}). */
persistUpdateKey?: string;
/**
* Logical-path → build-path catalog for cooked builds (content-addressed
* staging renames physical files): loaders route their inner text refs (a
* material's shader path) through Catalog.getBuildPath, which is identity
* without one. Applied when the per-App runtime Assets is first created.
*/
catalog?: Catalog;
/** Every scene the game can switch to. `data` loads eagerly at register
* time; `path` registers a lazy scene fetched through the runtime Assets
* on first {@link SceneManagerState.switchTo}/load. One of the two. */
scenes: Array<{ name: string; data?: SceneData; path?: string }>;
/**
* Cooked worlds the build carries. The one belonging to `firstScene` is
* adopted by the streamer after that scene is up — its cells are content
* residency brings in, so they are deliberately not in `scenes`.
*/
worlds?: WorldManifest[];
/**
* Cell name → its document, for a host that already holds them: an editor
* Play session cuts the unsaved scene in memory and has nowhere to fetch a
* cell FROM. A package leaves this out and every cell arrives by its path;
* the manifest is the same either way, cell paths included.
*/
cellDocuments?: ReadonlyMap<string, SceneData>;
firstScene: string;
spineModule?: SpineWasmModule | null;
spineManager?: SpineManager | null;
physicsModule?: PhysicsWasmModule | null;
/** Project-declared physics world config (gravity, solver tuning, collision-layer
* masks, sleep/continuous toggles) — threaded from the editor's Project Settings. */
physicsConfig?: Physics2DPluginConfig;
/** The 3D physics backend; selects the side module the 3D world is acquired from. Absent ⇒ Jolt. */
physics3dBackend?: Physics3DBackend;
/** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */
physics3dWorld?: Partial<Physics3DWorldConfig>;
/** Project-declared physics enable; see {@link LoadRuntimeSceneOptions.physicsEnabled}. */
physicsEnabled?: boolean;
/** Project-declared mixer state (bus volumes / custom buses / effects / duck
* rules) — threaded from the editor's audio config, applied once at boot. */
audioConfig?: AudioProjectConfig;
/** The project's runtime tuning (scene transition, frame limits, asset timeouts, cache budgets). Applied before anything loads, so the
* first asset already runs under it. */
runtime?: RuntimeBuildConfig;
/** Project-declared UI theme; see {@link LoadRuntimeSceneOptions.uiTheme}. */
uiTheme?: 'dark' | 'light';
/** Project-declared theme token overrides; see {@link LoadRuntimeSceneOptions.uiThemeOverrides}. */
uiThemeOverrides?: ThemeOverrides;
/** The design resolution and camera fit. A desktop window opens at the design
* size; the fit itself is applied by createWebApp/createNativeApp. */
screenFit?: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number };
/** The achievement ids the project declares — the set an unlock is checked
* against, since a store would take an unknown one and do nothing. */
achievements?: string[];
/** The Steam application id; present ⇒ try to bring a Steam client up and let
* it answer for achievements. Absent or unavailable keeps the local one. */
steamAppId?: number;
aspectRatio?: number;
/**
* The compiled twins a build produced (docs/REARCH_AOT.md): bytes, because
* fetching them is the transport's job — http here, `wx` there. Installed
* before the first scene registers, the only moment where no component
* exists yet to be left behind in the wrong memory.
*/
aot?: { module: string | BufferSource; manifest: AotManifest };
debugChannel?: DebugChannelConfig;
}
export async function initRuntime(config: RuntimeInitConfig): Promise<void> {
const { app, firstScene, aspectRatio } = config;
flushPendingRegistrations(app);
// Before any scene: what a component's default fills in is in the project's units (ecs/worldUnits.ts).
setWorldUnitsPerMeter(config.physics3dWorld?.unitsPerMeter ?? REFERENCE_UNITS_PER_METER);
// First: the asset timeouts and cache budgets are read by the very first load below.
if (config.runtime) applyBuildRuntimeConfig(app, config.runtime);
// After the project's components are registered (the manifest names them)
// and before any exists (its rows must be in the memory the module reads).
// A module that disagrees with this engine or project throws here.
if (config.aot) {
const installed = await app.installCompiledSystems(config.aot.module, config.aot.manifest);
log.info('runtime', `AOT: ${installed} compiled system(s) installed`);
}
if (config.debugChannel) startDebugChannel(config.debugChannel);
// Install the per-App runtime Assets up front (scene loads reuse it) and
// hand it the manifest so on-demand loadGroup works from the first frame.
// The catalog rides the same first-creation moment (later ensure calls
// return the existing instance).
const assets = ensureRuntimeAssets(app, config.module, config.source, config.catalog);
if (config.manifest) assets.setManifest(config.manifest);
if (config.remoteRoot) assets.setRemoteRoot(config.remoteRoot);
// A persisted update (from a prior applyUpdate) supersedes the shipped manifest
// + root, so a returning player boots straight onto the already-updated content.
if (config.persistUpdateKey) assets.restorePersistedUpdate(config.persistUpdateKey);
// Once the content it runs is known, so the editor is told which revision it is.
attachDebugChannel(app);
// Built-in rebinder: on a hot update, swap the changed texture into live
// sprites/meshes automatically — a scene @uuid ref updates with no game code.
installHotUpdateRebind(app, assets);
if (config.audioConfig && app.hasResource(Audio)) {
applyAudioProjectConfig(app.getResource(Audio), config.audioConfig);
}
// A desktop window opens at the project's design resolution. The host cannot
// read it for itself — the window exists before any JS does, and the host has
// no JSON parser — so this is where the two meet.
if (config.screenFit) {
getPlatform().setWindowSize?.(config.screenFit.designWidth, config.screenFit.designHeight);
}
// The declared achievement ids, so an unlock outside the set is refused here
// rather than accepted by a store and silently dropped.
app.getResource(Achievements)?.setKnown(config.achievements ?? null);
// A store, if there is one behind this build. Everything about the game's code
// is the same either way — what changes is whether Steam also hears.
if (config.steamAppId) {
const provider = getPlatform().steamAchievements?.(config.steamAppId);
if (provider) app.getResource(Achievements)?.setProvider(provider);
}
const sceneOpts: Omit<LoadRuntimeSceneOptions, 'sceneData' | 'sceneName'> = {
app: config.app,
module: config.module,
source: config.source,
spineModule: config.spineModule,
spineManager: config.spineManager,
physicsModule: config.physicsModule,
physicsConfig: config.physicsConfig,
physics3dBackend: config.physics3dBackend,
physics3dWorld: config.physics3dWorld,
physicsEnabled: config.physicsEnabled,
uiTheme: config.uiTheme,
uiThemeOverrides: config.uiThemeOverrides,
};
const mgr = app.getResource(SceneManager);
for (const scene of config.scenes) {
mgr.register(createRuntimeSceneConfig(scene.name, scene.data, sceneOpts, scene.path));
}
// Identity before the world exists: a streamed entity's authored id is what
// survives its cell leaving, and the table only records what loads after this.
const world = (config.worlds ?? []).find((candidate) => candidate.scene === firstScene) ?? null;
for (const other of config.worlds ?? []) {
if (other !== world) {
log.warn('residency', `world "${other.scene}" is cooked but only the entry scene's is adopted`);
}
}
if (world) enableSceneOrigins(app);
if (firstScene) {
mgr.setInitial(firstScene);
await mgr.load(firstScene);
}
if (world && app.hasResource(WorldStreaming)) {
// A cell loads the way every other scene in this build does, and resolves
// the persistent rows the cook said it names — freshly each time, because
// the entities behind those rows are only the ones alive right now.
const streamer = app.getResource(WorldStreaming);
// Read out here: inside the callback `config` is the scene's, not this one's.
const documents = config.cellDocuments;
await streamer.loadManifest(world, (cell) => {
// Set ON the config, not spread into a copy of it: the setup that
// loads the cell closes over the object this returns, so a copy
// carries the fields somewhere nothing reads them.
const config = createRuntimeSceneConfig(
cell.name, documents?.get(cell.name), sceneOpts, cell.path,
);
config.externalEntities = () => persistentEntityRows(app, world);
config.onPhase = (phase, ms) => streamer.recordPhase(cell.name, phase, ms);
return config;
});
}
if (aspectRatio !== undefined) {
updateCameraAspectRatio(app.world, aspectRatio);
}
}