@vgai/engine 0.5.0 → 0.5.2

package/dist/runtime/game.js

@@ -1,741 +0,0 @@
-/**
- * Game root — T7.1 slice 1 ("introduce Game internally") + slice 2 ("world
- * registry + ordered frame algorithm"), extended in T7.3 slice 1 with real
- * `'pixijs'`-kind `WorldInstance` support (`stage`/`physics2d`/`collisions2d`,
- * a real `pixiRoot()`) so `world2d/pixi-game-adapter.ts` can register its
- * world onto a real `Game` instead of driving its own loop, and in T7.3
- * slice 2 with a construction-time stage check (symmetric with the
- * threejs/scene check) and the two-world (threejs + pixijs) proof
- * (`test/game-three-plus-pixi.test.ts`). T6.2 slice 1 adds real `'react'`-kind
- * `WorldInstance` support (`container`, a real `reactRoot()`) — the DOM-root
- * world surface `runtime/create-runtime.ts`'s roots path now mounts (see
- * `docs/REACT-WORLD-DESIGN.md` §1.B); react roots host no `ComponentManager`
- * (D8 — components attaching to a react-kind manager already throw,
- * `ecs/component-manager.ts`), so `physics`/`collisions`/`camera`/`frame`
- * stay `undefined` for them exactly like an opaque/foreign mount.
- *
- * See `docs/GAME-ROOT-DESIGN.md` (D6), particularly §4 (the frame algorithm)
- * and §8 stage 2, for the full target shape. This file holds the Game/
- * WorldInstance shell, the NEW game-scoped `SystemRunner`, and the
- * host-facing `runFrame` frame executor. The public surface is NOT frozen
- * yet — do not add these exports to a barrel/index; only the in-scope
- * runtime/adapter files import this module directly. The `gpu` per-world
- * cache is the one remaining slice-1 omission.
- */
-import { formatAudioGateMessage, formatLoopGateMessage } from '../adapter/loop-gate-report';
-import { createSeededRandom, DEFAULT_SEEDED_RANDOM_SEED, registerSeededRandom, } from '../core/seeded-random';
-import { createSystemRunner } from '../core/system-runner';
-import { PHASE_ORDER, SystemPhase } from '../core/types';
-import { createPerformanceProfiler } from '../dev/performance-profiler';
-import { createDebugRegistry, DebugError, registerDebugRegistry, } from './debug-registry';
-import { createGameplayRngTrap, registerGameplayRngTrapControl } from './gameplay-rng-trap';
-import { createStateBridge } from './state-bridge';
-/**
- * Build a `WorldInstance` whose kind-narrowed accessors throw descriptively
- * on kind mismatch (GAME-ROOT-DESIGN §3). This is the one place that builds
- * `threeRoot`/`pixiRoot`, so every world (however it's constructed, in this
- * slice or later ones) gets identical throw behavior.
- */
-export function createWorldInstance(init) {
-    const { id, kind, pausable = true, adapter, mounted, scene, stage, container, physics, collisions, physics2d, collisions2d, camera, frame, } = init;
-    // A threejs world with no scene has nothing for `threeRoot()` to return —
-    // fail loudly HERE, at construction, rather than letting `threeRoot()`
-    // throw its generic "not a threejs world" message later for a world whose
-    // kind IS threejs (checklist item 5; a misleading error for this case).
-    if (kind === 'threejs' && !scene) {
-        throw new Error(`WorldInstance "${id}" (kind: threejs): a threejs world requires a scene — ` +
-            'pass `scene` in WorldInstanceInit.');
-    }
-    // Symmetric check for pixijs (T7.3 slice 2) — a pixijs world with no stage
-    // has nothing for `pixiRoot()` to return; fail loudly here, at
-    // construction, same as the threejs/scene check above.
-    if (kind === 'pixijs' && !stage) {
-        throw new Error(`WorldInstance "${id}" (kind: pixijs): a pixijs world requires a stage — ` +
-            'pass `stage` in WorldInstanceInit.');
-    }
-    // Symmetric check for react (T6.2 slice 1, docs/REACT-WORLD-DESIGN.md
-    // §1.B) — a react world with no container has nothing for `reactRoot()`
-    // to return; fail loudly here, at construction, same as the two checks
-    // above.
-    if (kind === 'react' && !container) {
-        throw new Error(`WorldInstance "${id}" (kind: react): a react world requires a container — ` +
-            'pass `container` in WorldInstanceInit.');
-    }
-    // Disposed-world guard (GAME-ROOT-DESIGN §8 stage 3 / T7.1 slice 3). There
-    // is no `unregisterWorld` (decision 4 — roots are manifest-declared; a
-    // whole Game is disposed, not one world out of its registry), so a caller
-    // that disposes ONE world's `mounted` directly (e.g. ending a sub-session)
-    // leaves that `WorldInstance` sitting in `Game.roots` — and `runFrame`
-    // would otherwise keep invoking its (now-torn-down) frame hooks every
-    // subsequent frame. `MountedGame` has no public "am I disposed" flag to
-    // read, so this wraps `mounted.dispose` in place (mutating the SAME mount
-    // object every holder of `mounted` shares — calling `mounted.dispose()`
-    // directly, exactly like calling `world.mounted.dispose()`, trips this)
-    // to flip a private flag, and wraps the frame hooks so they silently no-op
-    // once that flag is set. `runFrame` itself needs no knowledge of disposal
-    // — a disposed world is skipped by construction from the next call
-    // onward. (The opaque-world `mounted.update` fallback path is unaffected
-    // by this guard — no opaque-mount two-world scenario exists yet to need it.)
-    let disposed = false;
-    const originalDispose = mounted.dispose.bind(mounted);
-    mounted.dispose = () => {
-        disposed = true;
-        originalDispose();
-    };
-    const guardedFrame = frame
-        ? {
-            runPhase(phase, dt) {
-                if (disposed)
-                    return;
-                frame.runPhase(phase, dt);
-            },
-            endFrame() {
-                if (disposed)
-                    return;
-                frame.endFrame?.();
-            },
-        }
-        : undefined;
-    return {
-        id,
-        kind,
-        pausable,
-        adapter,
-        mounted,
-        physics,
-        collisions,
-        physics2d,
-        collisions2d,
-        camera,
-        frame: guardedFrame,
-        threeRoot() {
-            if (kind !== 'threejs' || !scene) {
-                throw new Error(`WorldInstance "${id}" (kind: ${kind}): threeRoot() requested but this world is not ` +
-                    'a threejs world');
-            }
-            return scene;
-        },
-        pixiRoot() {
-            // The `!stage` branch a pixijs world could hit here is now unreachable
-            // (T7.3 slice 2): construction above throws for `kind === 'pixijs'`
-            // with no `stage`, symmetric with `threeRoot()`'s `scene` guard.
-            if (kind !== 'pixijs' || !stage) {
-                throw new Error(`WorldInstance "${id}" (kind: ${kind}): pixiRoot() requested but this world is not ` +
-                    'a pixijs world');
-            }
-            return stage;
-        },
-        reactRoot() {
-            // The `!container` branch a react world could hit here is now
-            // unreachable (T6.2 slice 1): construction above throws for
-            // `kind === 'react'` with no `container`, symmetric with
-            // `threeRoot()`/`pixiRoot()`'s guards.
-            if (kind !== 'react' || !container) {
-                throw new Error(`WorldInstance "${id}" (kind: ${kind}): reactRoot() requested but this world is not ` +
-                    'a react world');
-            }
-            return container;
-        },
-    };
-}
-/**
- * Type guard for whether a `MountedGame` is a first-party
- * `VgaiSceneGameAdapter` mount (has a live `GameContext` at `.ctx`). Used to
- * decide whether a world's `physics`/`collisions`/`camera` (and, on `Game`,
- * `components`/`input`/`audio`) can be populated from it — an external
- * adapter's mount has none of these first-party handles.
- *
- * Checks the `firstParty: true` brand (checklist item 1), NOT `'ctx' in
- * mounted` — world2d's `MountedGame2D` (`world2d/pixi-game-adapter.ts`) also
- * has a `ctx` key (a `World2DContext`, unrelated to `GameContext`), so a
- * structural `'ctx' in mounted` check would misfire once T7.3 registers 2D
- * roots onto the same `Game`. The probe is a plain property read, not an
- * `instanceof`/value import of `vgai-scene-game-adapter.ts` — the
- * `VgaiMountedGame` import above stays type-only.
- */
-export function isFirstPartyMounted(mounted) {
-    return mounted.firstParty === true;
-}
-function describeMismatch(handle, world) {
-    return (`Game.${handle}: default world "${world.id}" (kind: ${world.kind}) is not a first-party ` +
-        "mount — hoisting these to true Game ownership is a later slice's work; available only " +
-        'via a first-party default world today');
-}
-/**
- * Construct the (host-internal) Game shell. Callers: `createGameRuntime`
- * builds this BEFORE mounting its one adapter, then registers the default
- * threejs world once mount resolves (see `registerThreeWorld` in
- * `create-runtime.ts`).
- */
-export function createGame(opts) {
-    const roots = [];
-    const profiler = createPerformanceProfiler();
-    const systems = createSystemRunner(profiler.systemObserver, 'game');
-    const stateBridge = createStateBridge();
-    // D15 (T-D15.1) — the game-scoped seeded-random surface every world's
-    // `ctx.random` aliases (see `vgai-scene-game-adapter.ts`'s `ctx.random =
-    // ...`, wired the same way `ctx.debug` is just below). Constructed
-    // unconditionally (cheap — a handful of closures) regardless of whether
-    // this project ever declares `determinism.seededRandom`; only the BOOT
-    // SEED and the enforcement (the burn-down scan, the trap right below) are
-    // conditional on that declaration.
-    const seededRandom = createSeededRandom(opts.seed ?? DEFAULT_SEEDED_RANDOM_SEED);
-    // D15 (T-D15.3) — the dev-mode `Math.random` phase trap. Constructed
-    // unconditionally too (disabled by default: `rngTrapEnabled` starts
-    // `false`, so `runFrameImpl`'s enable/disable calls below are no-ops) —
-    // the manifest-aware boot path flips `rngTrapControl.setEnabled(true)`
-    // once it resolves `manifest.determinism?.seededRandom` (mirrors
-    // `debugRegistry.setRoomDeclared` being flipped post-hoc from the same
-    // boot path for the very same "only the caller who read the manifest
-    // knows" reason).
-    const rngTrap = createGameplayRngTrap();
-    let rngTrapEnabled = false;
-    const rngTrapControl = {
-        setEnabled(enabled) {
-            rngTrapEnabled = enabled;
-        },
-        get enabled() {
-            return rngTrapEnabled;
-        },
-    };
-    // T1.2 (docs/SYNTHETIC-PLAYER-SPEC.md §3.1/§3.3): `tick` counts completed
-    // fixed substeps, `simT` accumulates their `dt` — both game-scoped, bumped
-    // ONLY where `stateBridge.bump()` is (guarded by `advanced`, `runFrame`'s
-    // tail below), so a paused/frozen frame never advances either. The debug
-    // registry reads them via suppliers (not by capturing the numbers now)
-    // so its built-in `time` provider always sees the CURRENT values.
-    let tick = 0;
-    let simT = 0;
-    const debugRegistry = createDebugRegistry({
-        getTick: () => tick,
-        getSimT: () => simT,
-        // D15/T-D15.5 — "the manifest's first/default world" for the per-world
-        // input-target resolution (`resolveInputWorldId`, `debug-registry.ts`):
-        // the SAME "first threejs world, else first world" rule
-        // `requireDefaultWorld` (declared just below — safe: this closure is
-        // only ever CALLED later, once at least one world has mounted) already
-        // defines for `Game.defaultWorld`/`Game.input` — so the debug bridge and
-        // the editor relay resolve the exact same world `Game.input` would.
-        getDefaultWorldId: () => (roots.length > 0 ? requireDefaultWorld().id : null),
-        // Issue #175 — the built-in `time` provider's `loopLiveness` field reads
-        // the REAL loop, not any UI-level play-state store: `opts.loop` is the
-        // SAME `GameLoop` this `Game`'s own `.loop` field exposes, so this
-        // registry can never disagree with `game.loop.liveness` about whether
-        // the loop is actually ticking.
-        getLoopLiveness: () => opts.loop.liveness,
-    });
-    function requireDefaultWorld() {
-        if (roots.length === 0) {
-            throw new Error('Game.defaultWorld: no roots registered yet');
-        }
-        return roots.find((w) => w.kind === 'threejs') ?? roots[0];
-    }
-    function requireFirstPartyCtx(handle) {
-        const world = requireDefaultWorld();
-        if (!isFirstPartyMounted(world.mounted)) {
-            throw new Error(describeMismatch(handle, world));
-        }
-        return world.mounted.ctx;
-    }
-    // --- Game.systemAdapters aggregation (§7.1-3, probe1) --------------------
-    // Warn-once-per-colliding-key state, scoped to this Game instance (a fresh
-    // Game gets a fresh warn history) — deliberately NOT reset by anything
-    // short of a new `createGame` call, matching `reportedGateShortfalls`
-    // above's "once per game instance" idiom.
-    const warnedSystemAdapterKeys = new Set();
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive merge-with-collision-report walk (per-world × per-key); splitting the collision-warn branch out would obscure that it's part of the same pass, not reduce real complexity
-    function computeSystemAdapters() {
-        // Debug is game-scoped: React hooks, probes, and the built-in time
-        // provider all register with the one registry created above, regardless
-        // of whether any mounted root happens to expose a `systems` object. A
-        // root may still publish this SAME adapter (the first-party Three/Pixi
-        // mounts do); the reference-equality branch below treats that as the
-        // intentional shared registration it is.
-        const result = { debug: debugRegistry.adapter };
-        const ownerWorldId = new Map([['debug', '(game)']]);
-        for (const world of roots) {
-            const adapters = world.mounted.systems;
-            if (!adapters)
-                continue;
-            for (const key of Object.keys(adapters)) {
-                if (adapters[key] === undefined)
-                    continue;
-                const existingOwner = ownerWorldId.get(key);
-                if (existingOwner !== undefined) {
-                    // Reference-equality short-circuit: two roots sharing the ONE
-                    // game-scoped debug registry's adapter (T1.1) both expose the SAME
-                    // object under `systems.debug` — that is by design, not a
-                    // collision, so it must never warn.
-                    if (result[key] === adapters[key])
-                        continue;
-                    if (!warnedSystemAdapterKeys.has(key)) {
-                        warnedSystemAdapterKeys.add(key);
-                        // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors this file's own reportGateShortfallOnce's deliberate direct console.warn just above
-                        console.warn(`[game] systemAdapters: "${key}" is registered by both world "${existingOwner}" and ` +
-                            `world "${world.id}" — the FIRST registration ("${existingOwner}") wins; the later ` +
-                            'one is shadowed (docs/GAME-ROOT-DESIGN.md §3: game-scoped system adapters).');
-                    }
-                    continue;
-                }
-                // biome-ignore lint/suspicious/noExplicitAny: SystemAdapters is a plain optional-field record; the per-key copy is correct by construction (same key on both sides), just not expressible without a cast
-                result[key] = adapters[key];
-                ownerWorldId.set(key, world.id);
-            }
-        }
-        return result;
-    }
-    // --- D10/T7.6 play-state (Game.play) -------------------------------------
-    let paused = false;
-    // Dedupe loop-gate/audio-gate shortfall warnings to ONCE per (world, kind)
-    // — `pause()` fans out over every world every call; without this a
-    // multi-second play session would re-log the same "can't gate" shortfall
-    // every time the user hits Pause.
-    const reportedGateShortfalls = new Set();
-    function reportGateShortfallOnce(kind, worldId, reason) {
-        const key = `${kind}:${worldId}`;
-        if (reportedGateShortfalls.has(key))
-            return;
-        reportedGateShortfalls.add(key);
-        const message = kind === 'loop'
-            ? formatLoopGateMessage({ worldId, reason })
-            : formatAudioGateMessage({ worldId, reason });
-        // Other native `console.warn`/`console.error` call sites in this file are
-        // unsuppressed and already counted in the lint baseline (see `runFrame`'s
-        // impl below); this one is a NEW site, so it's suppressed to keep this
-        // task's diff at zero NEW warnings (same reasoning as `overlay-report.ts`'s
-        // identical suppression).
-        // biome-ignore lint/suspicious/noConsole: see comment above
-        console.warn(message);
-    }
-    /** Fan out a loop-gate (self-driven roots) + audio-gate call over every
-     *  `pausable` world, reporting honestly (once) wherever the capability is
-     *  absent — shared by `pause()`/`resume()` below (same fan-out, opposite
-     *  boolean). */
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: fans out TWO independent capability gates (loop, audio) with the same "call it, else report once" shape per world — splitting the two gates into separate loops would duplicate the fan-out, not reduce real complexity
-    function setWorldGates(next) {
-        for (const world of roots) {
-            if (!world.pausable)
-                continue; // pausable:false roots are untouched by design
-            if (world.mounted.drivesOwnLoop) {
-                if (world.mounted.setPaused) {
-                    world.mounted.setPaused(next);
-                }
-                else if (next) {
-                    reportGateShortfallOnce('loop', world.id, 'self-driven world, adapter declares no setPaused capability');
-                }
-            }
-            const audio = world.mounted.systems?.audio;
-            if (audio) {
-                audio.setMuted(next);
-            }
-            else if (next) {
-                reportGateShortfallOnce('audio', world.id, 'no SystemAdapters.audio on this world');
-            }
-        }
-    }
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the frame algorithm (GAME-ROOT-DESIGN §4, now with D10's per-world pause gate + the onlyFrozen step()-only mode) is one cohesive nested loop over phases/roots — splitting it would obscure the ordering contract documented on GameInternal.runFrame
-    function runFrameImpl(dt, frameOpts) {
-        // D15 (T-D15.3) — brackets the ENTIRE frame body (every phase, every
-        // world, both the `onlyFrozen` and normal branches below converge on the
-        // single `profiler.endFrame()` at the tail) with zero reordering of the
-        // phase algorithm itself — a no-op pair of calls while
-        // `rngTrapEnabled` is false (the common case: most projects never
-        // declare `determinism.seededRandom`).
-        if (rngTrapEnabled)
-            rngTrap.enable();
-        profiler.beginFrame();
-        const ignorePause = frameOpts?.ignorePause ?? false;
-        // D15/T-D15.4: internal-only render-phase skip (not part of the public
-        // `GameInternal.runFrame` signature — no external caller sets it, mirroring
-        // `onlyFrozen` below) — `runTicks`'s `render: 'none'|'last'` fast-forward
-        // mode sets this on every tick it doesn't want to paint. See `runTicks`'s
-        // doc comment on `GameInternal` for the full contract.
-        const skipRenderPhases = frameOpts?.skipRenderPhases ?? false;
-        // `onlyFrozen` is internal-only (not part of the public `GameInternal.runFrame`
-        // signature — no external caller sets it) — `Game.play.step()` below is the
-        // one and only caller. It ticks EXACTLY the currently-frozen set (host-driven,
-        // `pausable`, and `paused`) through every phase + `endFrame`, with the REAL
-        // `dt` (not the render-phase's forced `0`), and touches no other world at all
-        // — §7.1-2 fix, probe4: the previous `ignorePause` full-frame re-run ticked
-        // EVERY host-driven world, double-ticking every already-running
-        // `pausable: false` world (D10's ordinary loop never stops ticking them).
-        const onlyFrozen = frameOpts?.onlyFrozen ?? false;
-        // Checklist item 7: snapshot the world count ONCE at entry and iterate
-        // by index in both loops below. A world registered mid-frame (e.g. from
-        // a game-scoped system's side effect) joins at the NEXT `runFrame` call,
-        // not this one — `for (const world of roots)` would otherwise pick up
-        // a world pushed during this very frame. This also drops the two
-        // per-phase `for...of` iterator allocations.
-        const n = roots.length;
-        // §7.1-11 fix (probe5): `stateBridge.bump()` must fire iff at least one
-        // world actually advanced this call — not unconditionally. `advanced`
-        // covers rule (a) below (host-driven roots this call actually ticked);
-        // rule (b): a self-driven world that is RUNNING — which is every
-        // self-driven world while not paused, and, while paused, the ones the
-        // gate can't reach (`pausable: false`, or no `setPaused` capability) —
-        // checked once, up front, over the same `roots` array (no extra
-        // allocation, matching every other loop here). Rule (b) is skipped in
-        // `onlyFrozen` mode: a `step()` call bumps iff it ticked a frozen world
-        // — self-driven notifications belong to the loop's own `runFrame`s.
-        let advanced = false;
-        if (!onlyFrozen) {
-            for (let i = 0; i < n; i++) {
-                const world = roots[i];
-                if (!world.mounted.drivesOwnLoop)
-                    continue;
-                if (!paused || !world.pausable || !world.mounted.setPaused) {
-                    advanced = true;
-                    break;
-                }
-            }
-        }
-        if (onlyFrozen) {
-            // step(): the frozen set is host-driven + pausable + currently paused.
-            // While NOT paused this set is empty by construction, so this whole
-            // branch is a natural no-op — `Game.play.step()`'s "no-op while
-            // running" behavior falls straight out of this, no separate guard
-            // needed.
-            for (const phase of PHASE_ORDER) {
-                profiler.beginPhase();
-                for (let i = 0; i < n; i++) {
-                    const world = roots[i];
-                    if (world.mounted.drivesOwnLoop)
-                        continue;
-                    if (!(paused && world.pausable))
-                        continue; // only the frozen set
-                    try {
-                        world.frame?.runPhase(phase, dt);
-                    }
-                    catch (err) {
-                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw ` +
-                            '(step()):', err);
-                    }
-                }
-                profiler.endPhase(phase);
-            }
-            for (let i = 0; i < n; i++) {
-                const world = roots[i];
-                if (world.mounted.drivesOwnLoop)
-                    continue;
-                if (!(paused && world.pausable))
-                    continue;
-                advanced = true;
-                if (world.frame) {
-                    try {
-                        world.frame.endFrame?.();
-                    }
-                    catch (err) {
-                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) endFrame() threw (step()):`, err);
-                    }
-                }
-                else {
-                    try {
-                        world.mounted.update?.(dt);
-                    }
-                    catch (err) {
-                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) update() threw (step()):`, err);
-                    }
-                }
-            }
-        }
-        else {
-            for (const phase of PHASE_ORDER) {
-                profiler.beginPhase();
-                // D15/T-D15.4: `runTicks`'s fast-forward skip — `preRender`/`render`
-                // are the ONLY phases ever skipped this way (every earlier gameplay
-                // phase, and `endFrame` below, always run) — see `skipRenderPhases`'s
-                // declaration above and `runTicks`'s doc comment on `GameInternal`.
-                const skipThisPhase = skipRenderPhases && (phase === SystemPhase.PRE_RENDER || phase === SystemPhase.RENDER);
-                if (!skipThisPhase) {
-                    systems.runPhase(phase, dt);
-                    for (let i = 0; i < n; i++) {
-                        const world = roots[i];
-                        if (world.mounted.drivesOwnLoop)
-                            continue;
-                        // D10/T7.6: a `pausable` world under an active (non-ignored) pause
-                        // skips every phase except `render` — its render still runs, every
-                        // substep, but with `dt` forced to `0` (deterministic: no
-                        // time-based render effect silently keeps animating a "frozen"
-                        // scene). A `pausable: false` world (or any world while
-                        // `ignorePause`) is unaffected.
-                        const frozen = !ignorePause && paused && world.pausable;
-                        if (frozen && phase !== SystemPhase.RENDER)
-                            continue;
-                        const phaseDt = frozen ? 0 : dt;
-                        // Checklist item 2: isolate each world's per-phase work — one
-                        // world's `runPhase` throwing must not starve sibling roots still
-                        // due this phase, nor abort the frame. Mirrors `runOne`'s style in
-                        // `core/system-runner.ts` (loud console.error, never swallowed).
-                        try {
-                            world.frame?.runPhase(phase, phaseDt);
-                        }
-                        catch (err) {
-                            console.error(`[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw:`, err);
-                        }
-                    }
-                }
-                profiler.endPhase(phase);
-            }
-            for (let i = 0; i < n; i++) {
-                const world = roots[i];
-                if (world.mounted.drivesOwnLoop)
-                    continue;
-                // A fully-frozen world gets no `endFrame`/opaque-`update` call either —
-                // there is nothing to "end the frame" of when nothing ran this substep.
-                const frozen = !ignorePause && paused && world.pausable;
-                if (frozen)
-                    continue;
-                advanced = true;
-                if (world.frame) {
-                    try {
-                        world.frame.endFrame?.();
-                    }
-                    catch (err) {
-                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) endFrame() threw:`, err);
-                    }
-                }
-                else {
-                    // Checklist item 2: same isolation for the opaque-world fallback —
-                    // one foreign mount's `update` throwing must not starve its
-                    // siblings' `endFrame`/`update` calls this same loop.
-                    try {
-                        world.mounted.update?.(dt);
-                    }
-                    catch (err) {
-                        console.error(`[game] world "${world.id}" (kind: ${world.kind}) update() threw:`, err);
-                    }
-                }
-            }
-        }
-        // T7.4 slice 1 (REACT-STATE-BRIDGE.md §2): bump + notify LAST, after
-        // every phase of every world and every world's endFrame/update above —
-        // subscribers must only ever observe post-frame state. Bumped at most
-        // once per completed `runFrame`/`step()` call, never per phase/world —
-        // and, per §7.1-11's fix, only when `advanced` (see above) is true: a
-        // fully-gated paused game produces no notifications at all.
-        if (advanced) {
-            stateBridge.bump();
-            tick++;
-            simT += dt;
-        }
-        profiler.endFrame();
-        if (rngTrapEnabled)
-            rngTrap.disable();
-    }
-    const gameInternal = {
-        loop: opts.loop,
-        assets: opts.assets,
-        profiler,
-        systems,
-        get roots() {
-            return roots;
-        },
-        world(id) {
-            return roots.find((w) => w.id === id) ?? null;
-        },
-        get defaultWorld() {
-            return requireDefaultWorld();
-        },
-        get systemAdapters() {
-            return computeSystemAdapters();
-        },
-        get components() {
-            return requireFirstPartyCtx('components').components;
-        },
-        get input() {
-            return requireFirstPartyCtx('input').input;
-        },
-        get audio() {
-            return requireFirstPartyCtx('audio').audio;
-        },
-        state: stateBridge,
-        play: {
-            get paused() {
-                return paused;
-            },
-            pause() {
-                if (paused)
-                    return;
-                paused = true;
-                setWorldGates(true);
-            },
-            resume() {
-                if (!paused)
-                    return;
-                paused = false;
-                setWorldGates(false);
-            },
-            step(dt = 1 / 60) {
-                // Self-driven pausable roots advance via their adapter's `step()`
-                // capability — but only the ones that are actually FROZEN: the game
-                // must be paused, and the world must have been gate-able in the
-                // first place (`setPaused` present — a world the gate couldn't reach
-                // never stopped, so "stepping" it would double-tick a still-running
-                // loop, the same §7.1-2 class as the host-driven fix below). While
-                // not paused, nothing here runs — step() is a whole-call no-op.
-                if (paused) {
-                    for (const world of roots) {
-                        if (!world.pausable || !world.mounted.drivesOwnLoop)
-                            continue;
-                        if (!world.mounted.setPaused)
-                            continue; // never gated — still running
-                        if (world.mounted.step) {
-                            world.mounted.step();
-                        }
-                        else {
-                            reportGateShortfallOnce('loop', world.id, 'self-driven world, adapter declares no step capability');
-                        }
-                    }
-                }
-                // §7.1-2 fix (probe4): tick EXACTLY the frozen (host-driven, pausable,
-                // paused) set — not `{ ignorePause: true }`, which re-ran a FULL
-                // extra frame for every host-driven world (including already-running
-                // `pausable: false` ones — a double-tick, since D10's ordinary loop
-                // never stops ticking them). See `runFrameImpl`'s `onlyFrozen` mode.
-                runFrameImpl(dt, { onlyFrozen: true });
-            },
-        },
-        queryByComponent(cls, opts) {
-            // Checklist item 8a: a `worldId` naming a world that doesn't exist is a
-            // caller error (typo'd id, wrong manifest) — degrade loudly, matching
-            // repo habit, rather than silently returning `[]`. A worldId that DOES
-            // exist but isn't first-party legitimately answers "no components"
-            // below (the loop's `!isFirstPartyMounted` `continue`), which stays
-            // silent — that's a real, not a mistaken, empty result.
-            if (opts?.worldId !== undefined && !roots.some((w) => w.id === opts.worldId)) {
-                throw new Error(`Game.queryByComponent: unknown worldId "${opts.worldId}"`);
-            }
-            const result = [];
-            for (const world of roots) {
-                if (!isFirstPartyMounted(world.mounted))
-                    continue;
-                if (opts?.worldId !== undefined && world.id !== opts.worldId)
-                    continue;
-                if (opts?.kind !== undefined && world.kind !== opts.kind)
-                    continue;
-                // Checklist item 8b: a plain for-loop push instead of
-                // `result.push(...arr)` — spread-as-arguments can hit engine/runtime
-                // argument-count limits once a world's instance count gets large.
-                const instances = world.mounted.ctx.components.queryByComponent(cls);
-                for (const inst of instances)
-                    result.push(inst);
-            }
-            return result;
-        },
-        registerWorld(world) {
-            if (roots.some((w) => w.id === world.id)) {
-                throw new Error(`Game.registerWorld: duplicate world id "${world.id}"`);
-            }
-            // Checklist item 6: the SAME `mounted` object registered under two
-            // world ids would be double-ticked by `runFrame` (its `frame.runPhase`/
-            // `endFrame` called once per registration) and double-dispose-wrapped
-            // (`createWorldInstance` wraps `mounted.dispose` in place — a second
-            // wrap would flip `disposed` and call through on ITS OWN wrapped
-            // `originalDispose`, which is harmless today only by accident of
-            // `VgaiSceneGameAdapter.dispose` being idempotent; a foreign adapter
-            // has no such guarantee). Reject it outright instead.
-            if (roots.some((w) => w.mounted === world.mounted)) {
-                throw new Error(`Game.registerWorld: world "${world.id}" shares its \`mounted\` object with an ` +
-                    `already-registered world ("${roots.find((w) => w.mounted === world.mounted).id}") — ` +
-                    'the same mount cannot be registered twice.');
-            }
-            roots.push(world);
-            // Notify state-bridge subscribers THE INSTANT the world list changes —
-            // not just at the next completed `runFrame`. Root-cause fix for the
-            // "roots: " (empty) hang in `36-r3f-first-party.spec.ts` on CI
-            // (docs/R3F-FIRST-PARTY-DESIGN.md W3, gate 4): `mountAllWorldSpecs`
-            // (`create-runtime.ts`) mounts roots SEQUENTIALLY, and a react world's
-            // `adapter.mount()` (`resolveDefaultReactAdapter`/`mountOneReactWorld`)
-            // renders its tree — synchronously in some React builds, but React 19's
-            // concurrent renderer does NOT guarantee a synchronous first commit
-            // (see `r3f-adapter.tsx`'s own doc comment on `onCreated`) — BEFORE the
-            // caller calls `registerWorld` for that very world. A `useGameState`
-            // selector reading `g.roots` can therefore render for the first time
-            // while `roots` is still missing entries that register moments later.
-            // Previously the ONLY way such a subscriber ever saw the corrected
-            // value was the state bridge's next `bump()`, which fires exclusively
-            // from `GameInternal.runFrame`'s tail — i.e. only once the host's loop
-            // has actually ticked (`started = true; loop.start()` in
-            // `create-runtime.ts`, itself gated on EVERY world finishing its
-            // mount). On a slow/contended host (CI's 4-core SwiftShader runners)
-            // that first tick can be delayed well past a test's assertion window,
-            // or — if the tab is ever backgrounded — not fire at all for a long
-            // stretch; the subscriber's cached snapshot then sits on its stale
-            // (possibly fully empty) first render for that whole time, matching
-            // the observed CI symptom exactly ("the HUD element IS mounted; the
-            // roots list is EMPTY"). Proven red-then-green by
-            // `packages/engine/test/state-bridge.test.ts`'s "registerWorld notifies
-            // subscribers immediately" case: a subscriber registered before a
-            // world, with `runFrame` NEVER called, only saw the update after this
-            // fix. `bump()` also advances `frameVersion` (the only invalidation
-            // key `createFrameSelectorCache`/`useGameState` understand — see
-            // `frame-selector-cache.ts`), so this doubles as "frameVersion is
-            // bumped once per completed runFrame OR once per world registered",
-            // documented on `GameStateBridge.frameVersion` below.
-            stateBridge.bump();
-            // T7.4 slice 2 (REACT-STATE-BRIDGE.md §4): a NON-first-party mount
-            // (an ingested/foreign world — first-party mounts are exempt, they're
-            // observed via `Game.state`/`useGameState` instead) with no `observe`
-            // has no state bridge at all — react HUDs cannot subscribe to it, and
-            // silently returning `undefined` forever would hide that. Report ONCE
-            // per mount, at registration time, matching this file's existing
-            // `[game] world "<id>" (kind: <kind>) ...` console idiom (see
-            // `runFrame` below).
-            //
-            // §7.1-15: a `kind: 'react'` world is ALSO exempt — it has no `observe`
-            // BY DESIGN (D8/REACT-WORLD-DESIGN.md: a react world's own mounted tree
-            // reads state via `Game.state`/`useGameState`, the SAME first-party
-            // bridge a threejs/pixijs world's HUD uses, never `WorldStateObserver`
-            // — that hook is scoped to the ingested/foreign-world case). Without
-            // this exemption every production react world logged a false-positive
-            // "no state bridge" warning at registration (probe: every real react
-            // world mount), eroding the signal for a genuinely un-observable
-            // ingested world.
-            if (!isFirstPartyMounted(world.mounted) && world.kind !== 'react' && !world.mounted.observe) {
-                console.warn(`[game] world "${world.id}" (kind: ${world.kind}, adapter: "${world.adapter.id}"): ` +
-                    'no state bridge — this mounted game has no `observe` (WorldStateObserver); ' +
-                    'react HUDs/useWorldObservation cannot subscribe to its state (docs/REACT-STATE-BRIDGE.md §4).');
-            }
-        },
-        runFrame(dt, frameOpts) {
-            runFrameImpl(dt, frameOpts);
-        },
-        runTicks(n, ticksOpts) {
-            if (!Number.isInteger(n) || n < 0) {
-                throw new RangeError(`Game.runTicks: n must be a non-negative integer, got ${n}`);
-            }
-            // Refuse while paused (D15 §2.b): stepping the frozen set is
-            // `Game.play.step()`'s contract, not this one's — see `runTicks`'s doc
-            // comment on `GameInternal` above.
-            if (paused) {
-                throw new DebugError('RUN_TICKS_PAUSED', 'Game.runTicks: refused — Game.play.paused is true; stepping the frozen set is ' +
-                    "Game.play.step()'s contract, not runTicks' (docs/D15-DETERMINISM-DESIGN.md §2.b)");
-            }
-            const render = ticksOpts?.render ?? 'last';
-            const fixedDt = opts.loop.fixedDt;
-            for (let i = 0; i < n; i++) {
-                const isFinalTick = i === n - 1;
-                const skipRenderPhases = render === 'all' ? false : render === 'none' ? true : !isFinalTick;
-                runFrameImpl(fixedDt, { skipRenderPhases });
-            }
-        },
-    };
-    // Filed AFTER the shell exists (the WeakMap keys on the Game object
-    // itself) so `getDebugRegistry(game)` — the react hooks' and any later
-    // consumer's reach-in — works from the moment `createGame` returns.
-    registerDebugRegistry(gameInternal, debugRegistry);
-    // D15/T-D15.4: wire the run-ticks target the instant the Game shell exists
-    // (unlike `setVirtualInputTarget`, which waits for a per-world mount, a
-    // Game's own `runTicks` needs nothing else) — this is what makes
-    // `window.__vgai.runTicks` (`debug-bridge.ts`) and the editor relay's
-    // `run-ticks` case reach the SAME implementation `game.runTicks` above is.
-    debugRegistry.setRunTicksTarget({ runTicks: gameInternal.runTicks });
-    // D15 (T-D15.1/.3) — same "file after the shell exists" ordering as the
-    // debug registry above: `getSeededRandom(game)`/`getGameplayRngTrapControl
-    // (game)` (per-world `ctx.random` wiring, and the manifest-aware boot
-    // path's post-hoc `setEnabled` call) both work from the moment
-    // `createGame` returns.
-    registerSeededRandom(gameInternal, seededRandom);
-    registerGameplayRngTrapControl(gameInternal, rngTrapControl);
-    return gameInternal;
-}