@vgai/engine 0.5.5 → 0.5.7

package/dist/runtime/game.js

@@ -0,0 +1,1003 @@
+/**
+ * Game root — T7.1 slice 1 ("introduce Game internally") + slice 2 ("world
+ * registry + ordered frame algorithm"), extended in T7.3 slice 1 with real
+ * `'canvas'`-kind `RootInstance` support (`stage`/`physics2d`, a real
+ * `pixiStage()`) so a canvas adapter 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 three/scene check).
+ * T6.2 slice 1 adds real `'react'`-kind
+ * `RootInstance` support (`container`, a real `reactRoot()`) — the DOM-root
+ * world surface `runtime/create-runtime.ts`'s roots path now mounts, with
+ * `physics`/`collisions`/`camera`/`frame` `undefined` for them exactly
+ * like an opaque/foreign mount.
+ *
+ * (D6), particularly §4 (the frame algorithm) and §8 stage 2, for the full
+ * target shape. This file holds the Game/ RootInstance 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 { createSimClock, registerSimClock } from '../core/sim-clock';
+import { createSystemRunner } from '../core/system-runner';
+import { PHASE_ORDER, SystemPhase } from '../core/types';
+import { createPerformanceProfiler } from '../dev/performance-profiler';
+import { hasUserData } from '../ecs/user-data';
+import { InputManager } from '../input/input-manager';
+import { createDebugRegistry, DebugError, registerDebugRegistry, } from './debug-registry';
+import { createGameplayRngTrap, registerGameplayRngTrapControl } from './gameplay-rng-trap';
+import { createStateBridge } from './state-bridge';
+/**
+ * WO-P13 — the tail of `PHASE_ORDER` that presents rather than simulates, and
+ * therefore runs once per DISPLAY frame (`runRenderFrameImpl`) rather than
+ * once per fixed substep. The same two phases `runTicks`' `skipRenderPhases`
+ * fast-forward skips and `render-control.ts`'s `renderOnce()` drives — one
+ * definition of "the render phases" across all three, kept in `PHASE_ORDER`'s
+ * own order.
+ */
+const DISPLAY_RATE_PHASES = PHASE_ORDER.filter((phase) => phase === SystemPhase.PRE_RENDER || phase === SystemPhase.RENDER);
+/**
+ * Build a `RootInstance` whose kind-narrowed accessors throw descriptively
+ * on kind mismatch. This is the one place that builds
+ * `threeScene`/`pixiStage`, so every world (however it's constructed, in this
+ * slice or later ones) gets identical throw behavior.
+ */
+export function createRootInstance(init) {
+    const { id, kind, pausable = true, adapter, mounted, scene, stage, container, physics, collisions, physics2d, camera, frame, } = init;
+    // A three world with no scene has nothing for `threeScene()` to return —
+    // fail loudly HERE, at construction, rather than letting `threeScene()`
+    // throw its generic "not a three world" message later for a world whose
+    // kind IS three (checklist item 5; a misleading error for this case).
+    if (kind === 'three' && !scene) {
+        throw new Error(`RootInstance "${id}" (kind: three): a three world requires a scene — ` +
+            'pass `scene` in RootInstanceInit.');
+    }
+    // Symmetric check for canvas (T7.3 slice 2) — a canvas world with no stage
+    // has nothing for `pixiStage()` to return; fail loudly here, at
+    // construction, same as the three/scene check above.
+    if (kind === 'canvas' && !stage) {
+        throw new Error(`RootInstance "${id}" (kind: canvas): a canvas world requires a stage — ` +
+            'pass `stage` in RootInstanceInit.');
+    }
+    // Symmetric check for react (T6.2 slice 1) — 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 === 'dom' && !container) {
+        throw new Error(`RootInstance "${id}" (kind: react): a react world requires a container — ` +
+            'pass `container` in RootInstanceInit.');
+    }
+    // Disposed-world guard (T7.1 slice 3). There
+    // is no `unregisterRoot` (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 `RootInstance` sitting in `Game.roots` — and `runFrame`
+    // would otherwise keep invoking its (now-torn-down) frame hooks every
+    // subsequent frame. `MountedThreeRoot` 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,
+        camera,
+        frame: guardedFrame,
+        threeScene() {
+            if (kind !== 'three' || !scene) {
+                throw new Error(`RootInstance "${id}" (kind: ${kind}): threeScene() requested but this world is not ` +
+                    'a three world');
+            }
+            return scene;
+        },
+        pixiStage() {
+            // The `!stage` branch a canvas world could hit here is now unreachable
+            // (T7.3 slice 2): construction above throws for `kind === 'canvas'`
+            // with no `stage`, symmetric with `threeScene()`'s `scene` guard.
+            if (kind !== 'canvas' || !stage) {
+                throw new Error(`RootInstance "${id}" (kind: ${kind}): pixiStage() requested but this world is not ` +
+                    'a canvas 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 === 'dom'` with no `container`, symmetric with
+            // `threeScene()`/`pixiStage()`'s guards.
+            if (kind !== 'dom' || !container) {
+                throw new Error(`RootInstance "${id}" (kind: ${kind}): reactRoot() requested but this world is not ` +
+                    'a react world');
+            }
+            return container;
+        },
+    };
+}
+/**
+ * Type guard for whether a `MountedThreeRoot` is a first-party
+ * `SetupThreeRootAdapter` mount (has a live `GameContext` at `.ctx`). Used to
+ * decide whether a world's `physics`/`collisions`/`camera` (and, on `Game`,
+ * `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` — a foreign mount may carry an unrelated `ctx` key, so a
+ * structural `'ctx' in mounted` check would misfire. The probe is a plain property read, not an
+ * `instanceof`/value import of `setup-three-root-adapter.ts` — the
+ * `MountedSetupThreeRoot` import above stays type-only.
+ */
+export function isFirstPartyMounted(mounted) {
+    return mounted.firstParty === true;
+}
+/**
+ * Read an owner's Rapier handles, treating an absent pair as "this owner holds
+ * no rigid bodies" — the honest reading for a world (R3F, or a bare
+ * `ComponentManager`-only owner) that builds no first-party physics runtime.
+ */
+function readRapierHandles(owner) {
+    const { physics, rapierWorld } = owner;
+    if (!physics || !rapierWorld)
+        return null;
+    return { physics, rapierWorld };
+}
+/**
+ * P3 — what `SimClock.disposeAfter` actually does. `core/sim-clock.ts` knows
+ * only *when*; this is the *what*, and it lives here because it is the runtime
+ * that knows about Rapier and shared geometry.
+ *
+ * The order mirrors `adapter/setup-three-root-adapter.ts`'s world teardown for
+ * ONE subtree. Within the physics step,
+ * `rapierWorld.removeRigidBody(body)` comes BEFORE `physics.remove(node)`: the
+ * registry's `remove()` only drops index entries, so reversing the two leaks
+ * the Rapier body.
+ *
+ * `owners` is every world that could own part of the subtree — `createGame`
+ * passes all of its first-party three roots as their `GameContext`, a bare
+ * adapter mount passes its own ctx. `physics.get` is a no-op for a node the
+ * owner does not own, so offering the subtree to each is safe.
+ *
+ * Safe on an object already removed or already disposed: `removeFromParent` on
+ * a parentless `Object3D` is a no-op and three's `dispose()` calls are
+ * idempotent.
+ */
+export function disposeDebrisSubtree(obj, owners) {
+    const nodes = [];
+    obj.traverse((node) => nodes.push(node));
+    for (const owner of owners) {
+        const rapier = readRapierHandles(owner);
+        if (!rapier)
+            continue;
+        for (const node of nodes) {
+            const refs = rapier.physics.get(node);
+            if (!refs)
+                continue;
+            rapier.rapierWorld.removeRigidBody(refs.body);
+            rapier.physics.remove(node);
+        }
+    }
+    obj.removeFromParent();
+    for (const node of nodes) {
+        // Duck-typed rather than `instanceof THREE.Mesh` so this module keeps its
+        // TYPE-ONLY three import (it is surface-neutral — it also hosts pixi
+        // roots). Covers Points/Line/Sprite debris too, which a Mesh check would
+        // silently leak.
+        const drawable = node;
+        if (!hasUserData(node, '__sharedGeometry'))
+            drawable.geometry?.dispose();
+        const material = drawable.material;
+        if (Array.isArray(material)) {
+            for (const m of material)
+                m.dispose();
+        }
+        else {
+            material?.dispose();
+        }
+    }
+}
+/**
+ * The {@link DebrisOwner}s one registered world contributes: its `GameContext`
+ * when the mount is first-party, else nothing. Written as a standalone function
+ * so `createGame`'s clock disposer is one line and the "which mounts count"
+ * rule has exactly one home.
+ */
+function debrisOwnersOf(world) {
+    return isFirstPartyMounted(world.mounted) ? [world.mounted.ctx] : [];
+}
+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
+ * three world once mount resolves (see `registerThreeRoot` in
+ * `create-runtime.ts`).
+ */
+export function createGame(opts) {
+    const roots = [];
+    const profiler = createPerformanceProfiler();
+    const systems = createSystemRunner(profiler.systemObserver, 'game');
+    const input = new InputManager();
+    const stateBridge = createStateBridge();
+    // D15 (T-D15.1) — the game-scoped seeded-random surface every world's
+    // `ctx.random` aliases (see `setup-three-root-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;
+        },
+    };
+    // `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;
+    // WO-P13 — the display-rate half. `renderAlpha` is the last alpha
+    // `runRenderFrameImpl` presented at (0 until a host drives one); the set is
+    // the `RenderStepped`-shaped registry `Game.onRenderStep` feeds. Deliberately
+    // NOT beside `tick`/`simT` in meaning: neither of these ever advances sim
+    // state, which is exactly what makes running them at the monitor's rate safe.
+    let renderAlpha = 0;
+    const renderStepCallbacks = new Set();
+    // P3 — the ONE sim clock this Game owns, declared beside the accumulator it
+    // is bound to (`flush(simT)` runs at the tail of `runFrameImpl`, inside the
+    // same `advanced` guard as the two bumps above, so a paused/frozen frame
+    // fires no timers). Every world's `ctx.clock` is THIS instance, reached the
+    // same way `ctx.random`/`ctx.debug` reach their game-scoped singletons —
+    // `getSimClock(host.game)` over the WeakMap filed below.
+    //
+    // The disposer is supplied HERE rather than inside the clock because
+    // `core/sim-clock.ts` deliberately knows nothing about Rapier or shared
+    // geometry. It mirrors `setup-three-root-adapter.ts`'s world teardown
+    // ordering for ONE subtree.
+    const simClock = createSimClock({
+        // Every mount that could own part of the subtree is offered it:
+        // `physics.get` is a no-op for a node the mount does not own, so this is
+        // correct with several three roots on one Game and needs no ownership
+        // bookkeeping.
+        dispose: (obj) => disposeDebrisSubtree(obj, roots.flatMap(debrisOwnersOf)),
+    });
+    const debugRegistry = createDebugRegistry({
+        getTick: () => tick,
+        getSimT: () => simT,
+        // D15/T-D15.5 — "the manifest's first/default world" for the debug
+        // registry's world-addressed input-target compatibility surface. Every
+        // first-party root now registers the SAME game-owned InputManager, but the
+        // stable default id still keeps explicit/implicit debug routing coherent.
+        // Use the SAME "first three world, else first world" rule
+        // `requireDefaultRoot` (declared just below — safe: this closure is
+        // only ever CALLED later, once at least one world has mounted) already
+        // defines for `Game.defaultRoot`.
+        getDefaultRootId: () => (roots.length > 0 ? requireDefaultRoot().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,
+    });
+    let inputFrameActive = false;
+    systems.add('input', () => {
+        if (inputFrameActive)
+            input.poll(debugRegistry.getGameTick());
+    }, { name: 'input.poll' });
+    input.setDebugEmit((event, detail) => debugRegistry.forRoot('(game)').emit(event, detail));
+    let inputMapPath = null;
+    let inputMapLoad = null;
+    function requireDefaultRoot() {
+        if (roots.length === 0) {
+            throw new Error('Game.defaultRoot: no roots registered yet');
+        }
+        return roots.find((w) => w.kind === 'three') ?? roots[0];
+    }
+    function requireFirstPartyCtx(handle) {
+        const world = requireDefaultRoot();
+        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();
+    const systemAdapterListeners = 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 ownerRootId = 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 = ownerRootId.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 (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];
+                ownerRootId.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 `achieved-tier.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 setRootGates(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 (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 + WO-P13: the render-phase skip. Two callers set it, for the
+        // same reason — this substep is not the thing that paints. `runTicks`'s
+        // `render: 'none'|'last'` fast-forward sets it on every tick it doesn't
+        // want to paint (see `runTicks`'s doc comment on `GameInternal`), and a
+        // DISPLAY-RATE host sets it on every substep because `runRenderFrame`
+        // paints once per real frame instead. Unlike `onlyFrozen` below it is no
+        // longer internal-only: it is part of the public `GameInternal.runFrame`
+        // signature, since an external host is now one of those two callers.
+        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;
+        inputFrameActive = false;
+        for (let i = 0; i < n; i++) {
+            const world = roots[i];
+            if (onlyFrozen) {
+                if (paused && world.pausable && !world.mounted.drivesOwnLoop) {
+                    inputFrameActive = true;
+                    break;
+                }
+            }
+            else if (ignorePause ||
+                (world.mounted.drivesOwnLoop
+                    ? !paused || !world.pausable || !world.mounted.setPaused
+                    : !paused || !world.pausable)) {
+                inputFrameActive = true;
+                break;
+            }
+        }
+        // §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();
+                // Game-owned systems follow the same one-run-per-phase contract as a
+                // normal frame whenever Step advances at least one frozen world.
+                // In particular, the game-owned InputManager must poll before those
+                // worlds read actions; its matching endFrame remains at the shared
+                // frame tail below.
+                if (inputFrameActive)
+                    systems.runPhase(phase, dt);
+                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: 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 (inputFrameActive)
+            input.endFrame();
+        if (advanced) {
+            stateBridge.bump();
+            tick++;
+            simT += dt;
+            // P3 — sim timers fire IMMEDIATELY after the bump, inside this same
+            // `advanced` guard: a paused/frozen world advances no sim time, so it
+            // must fire no timers either, and `Game.play.step()` (which reaches this
+            // block with `advanced` set by the frozen-set loop above) fires exactly
+            // the timers that ONE substep makes due. One flush === one completed
+            // substep, which is what lets `SimClock.tickNow()` simply count flushes
+            // and always agree with `tick`.
+            simClock.flush(simT);
+        }
+        profiler.endFrame();
+        if (rngTrapEnabled)
+            rngTrap.disable();
+    }
+    /**
+     * WO-P13 — one display frame's PRESENTATION pass. See
+     * `GameInternal.runRenderFrame`'s doc comment for the contract; this is the
+     * `preRender`+`render` slice of `runFrameImpl`'s phase loop, lifted out and
+     * driven by the loop's own per-real-frame callback instead of by the substep
+     * loop.
+     *
+     * Three deliberate parallels with `runFrameImpl`, so the two passes cannot
+     * drift into different rules for the same situation:
+     *  - game-scoped systems run before per-world hooks, per phase;
+     *  - one world's throw is logged and isolated, never allowed to starve a
+     *    sibling still due this phase;
+     *  - the RNG trap brackets the whole pass, so `Math.random` called from a
+     *    render-phase system is still caught by D15's dev-mode trap — it was,
+     *    back when this pass lived inside `runFrame`, and moving code must not
+     *    quietly move it out from under a guard.
+     *
+     * Profiler note (a real, accepted consequence): the profiler's "frame" has
+     * always meant "one `runFrame` call", so a display frame now produces the
+     * substep records it always did PLUS one record for this pass, carrying the
+     * `preRender`/`render` spans and the renderer counters. Re-modelling the
+     * profiler's frame boundary around the display frame is a separate change to
+     * a debugging surface, not part of flipping the loop.
+     */
+    function runRenderFrameImpl(alpha, displayDt) {
+        renderAlpha = alpha;
+        if (rngTrapEnabled)
+            rngTrap.enable();
+        profiler.beginFrame();
+        // `RenderStepped` first: a camera adjusted here is drawn by THIS frame's
+        // render phase, not next frame's. Iterated over a snapshot so a callback
+        // that unsubscribes itself (or registers another) cannot mutate the set
+        // mid-iteration.
+        if (renderStepCallbacks.size > 0) {
+            for (const fn of [...renderStepCallbacks]) {
+                try {
+                    fn(alpha, displayDt);
+                }
+                catch (err) {
+                    console.error('[game] an onRenderStep callback threw:', err);
+                }
+            }
+        }
+        const n = roots.length;
+        for (const phase of DISPLAY_RATE_PHASES) {
+            profiler.beginPhase();
+            systems.runPhase(phase, displayDt);
+            for (let i = 0; i < n; i++) {
+                const world = roots[i];
+                if (world.mounted.drivesOwnLoop)
+                    continue;
+                // D10/T7.6, carried over verbatim in substance: a frozen world still
+                // renders (a paused viewport stays painted) but with `dt` forced to
+                // `0`, and skips every other phase.
+                const frozen = paused && world.pausable;
+                if (frozen && phase !== SystemPhase.RENDER)
+                    continue;
+                try {
+                    world.frame?.runPhase(phase, frozen ? 0 : displayDt);
+                }
+                catch (err) {
+                    console.error(`[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw ` +
+                        '(display frame):', err);
+                }
+            }
+            profiler.endPhase(phase);
+        }
+        profiler.endFrame();
+        if (rngTrapEnabled)
+            rngTrap.disable();
+    }
+    const gameInternal = {
+        loop: opts.loop,
+        assets: opts.assets,
+        playtest: opts.playtest ?? null,
+        profiler,
+        systems,
+        get roots() {
+            return roots;
+        },
+        world(id) {
+            return roots.find((w) => w.id === id) ?? null;
+        },
+        get defaultRoot() {
+            return requireDefaultRoot();
+        },
+        get systemAdapters() {
+            return computeSystemAdapters();
+        },
+        subscribeSystemAdapters(listener) {
+            systemAdapterListeners.add(listener);
+            return () => systemAdapterListeners.delete(listener);
+        },
+        notifySystemAdaptersChanged() {
+            for (const listener of systemAdapterListeners)
+                listener();
+        },
+        input,
+        get audio() {
+            return requireFirstPartyCtx('audio').audio;
+        },
+        state: stateBridge,
+        play: {
+            get paused() {
+                return paused;
+            },
+            pause() {
+                if (paused)
+                    return;
+                paused = true;
+                setRootGates(true);
+            },
+            resume() {
+                if (!paused)
+                    return;
+                paused = false;
+                setRootGates(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 });
+            },
+        },
+        registerRoot(world) {
+            if (roots.some((w) => w.id === world.id)) {
+                throw new Error(`Game.registerRoot: 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
+            // (`createRootInstance` 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
+            // `SetupThreeRootAdapter.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.registerRoot: 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);
+            gameInternal.notifySystemAdaptersChanged();
+            // 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 (gate
+            // 4): `mountAllRootSpecs` (`create-runtime.ts`) mounts roots
+            // SEQUENTIALLY, and a react world's `adapter.mount()`
+            // (`resolveDefaultReactAdapter`/`mountOneReactRoot`) 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 `registerRoot` for that very world. A `useWorldState`
+            // 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 "registerRoot 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`/`useWorldState` 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: a NON-first-party mount
+            // (an ingested/foreign world — first-party mounts are exempt, they're
+            // observed via `Game.state`/`useWorldState` 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: 'dom'` world is ALSO exempt — it has no `observe`
+            // BY DESIGN (D8: a react world's own mounted tree
+            // reads state via `Game.state`/`useWorldState`, the SAME first-party
+            // bridge a three/canvas world's HUD uses, never `RootStateObserver`
+            // — 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.
+            // A HOST-DRIVEN mount (`drivesOwnLoop: false`, notably the R3F adapter)
+            // is observable through `Game.state` even though it does not carry the
+            // classic scene adapter's `firstParty` brand: it ticks inside
+            // `runFrame`, so the frame-versioned bridge covers it. Requiring a
+            // foreign-world `observe` bridge there produces a false warning while
+            // the canonical bridge is already live.
+            if (!isFirstPartyMounted(world.mounted) &&
+                world.mounted.drivesOwnLoop &&
+                world.kind !== 'dom' &&
+                !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` (RootStateObserver); ' +
+                    'react HUDs/useRootObservation cannot subscribe to its state.');
+            }
+        },
+        runFrame(dt, frameOpts) {
+            runFrameImpl(dt, frameOpts);
+        },
+        runRenderFrame(alpha, displayDt) {
+            runRenderFrameImpl(alpha, displayDt);
+        },
+        get renderAlpha() {
+            return renderAlpha;
+        },
+        onRenderStep(fn, stepOpts) {
+            const signal = stepOpts?.signal;
+            // Already-aborted is a no-op registration, never a throw — the same
+            // `AbortSignal` contract `SimClock.after` honors.
+            if (signal?.aborted)
+                return () => { };
+            renderStepCallbacks.add(fn);
+            let detachAbort = null;
+            const unsubscribe = () => {
+                renderStepCallbacks.delete(fn);
+                detachAbort?.();
+                detachAbort = null;
+            };
+            if (signal) {
+                signal.addEventListener('abort', unsubscribe, { once: true });
+                detachAbort = () => signal.removeEventListener('abort', unsubscribe);
+            }
+            return unsubscribe;
+        },
+        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'");
+            }
+            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 });
+            }
+        },
+        loadInputMap(path) {
+            if (inputMapPath && inputMapPath !== path) {
+                throw new Error(`Game.loadInputMap: input map is already "${inputMapPath}"; root requested "${path}". ` +
+                    'Input is game-owned, so roots cannot load competing maps.');
+            }
+            inputMapPath = path;
+            inputMapLoad ??= input.loadMap(path);
+            return inputMapLoad;
+        },
+        dispose() {
+            // P3 — the sim clock is GAME-scoped, so this is the only correct place to
+            // dispose it: `create-runtime.ts`'s `fullCleanup` calls us after EVERY
+            // root's `mounted.dispose()`, whereas a per-root teardown may be ending
+            // just one sub-session while sibling roots keep running (see the
+            // disposed-world guard in `runFrame`). It used to be disposed from
+            // `setup-three-root-adapter.ts`'s teardown, which meant disposing one of
+            // two three roots froze `now()` for the whole Game, rejected the other
+            // world's pending `delay`s and turned its `after()` calls into silent
+            // no-ops. Note the asymmetry that gives the bug away: `seededRandom` and
+            // `debugRegistry` are game-scoped too, and per-root teardown has never
+            // destroyed either — only ever `strip(this.id)`, its own slice.
+            simClock.dispose();
+            input.dispose();
+            debugRegistry.strip();
+        },
+    };
+    // 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);
+    // P3 — same "file after the shell exists" ordering: `getSimClock(game)` is
+    // how every world's mount resolves `ctx.clock` to THIS game's one clock.
+    registerSimClock(gameInternal, simClock);
+    return gameInternal;
+}