Skip to content

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.

48.6 KB
Raw Blame
// 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);
    }
}