@volter/editor-game 0.5.66 → 0.5.67

package/src/runtime/audio/pose-guard.ts

@@ -0,0 +1,80 @@
+import * as THREE from 'three';
+
+type UpdateMatrixWorld = (force?: boolean) => void;
+type PoseReporter = (type: string) => void;
+interface AudioNode3D {
+  matrixWorld: THREE.Matrix4;
+  type: string;
+  context: { readonly state: AudioContextState };
+  // Three's AudioListener owns this private clock; PositionalAudio reads its
+  // listener's public timeDelta. Only the verified getDelta method is needed.
+  _clock?: Pick<THREE.Clock, 'getDelta'>;
+  timeDelta?: number;
+}
+
+interface GuardState {
+  dropped: number;
+  report?: PoseReporter;
+}
+
+// The editor bundle and source-served runtime can load this helper separately
+// while sharing Three. Installation belongs to the actual prototype identity.
+const GUARD_STATE = Symbol.for('vgai.audio-pose-guard');
+type AudioPrototype = {
+  updateMatrixWorld: UpdateMatrixWorld;
+  [GUARD_STATE]?: GuardState;
+};
+
+function poseIsFinite(matrixWorld: THREE.Matrix4): boolean {
+  return matrixWorld.elements.every(Number.isFinite);
+}
+
+function guard(prototype: AudioPrototype, report?: PoseReporter): void {
+  const existing = prototype[GUARD_STATE];
+  if (existing) {
+    if (report) existing.report = report;
+    return;
+  }
+  const state: GuardState = { dropped: 0, ...(report ? { report } : {}) };
+  Object.defineProperty(prototype, GUARD_STATE, { value: state });
+  const suspendedListeners = new WeakSet<AudioNode3D>();
+  const original = prototype.updateMatrixWorld;
+  prototype.updateMatrixWorld = function guardedUpdateMatrixWorld(
+    this: AudioNode3D,
+    force?: boolean,
+  ): void {
+    // Keep the scene graph current even when Web Audio cannot consume a pose.
+    THREE.Object3D.prototype.updateMatrixWorld.call(this as unknown as THREE.Object3D, force);
+    if (this.context.state !== 'running') {
+      if (this._clock) {
+        this.timeDelta = 0;
+        suspendedListeners.add(this);
+      }
+      return;
+    }
+    if (poseIsFinite(this.matrixWorld)) {
+      // A hidden tab may have rendered no frames while suspended. Discard
+      // that wall-time gap before Three computes its next short pose ramp.
+      if (suspendedListeners.delete(this)) this._clock?.getDelta();
+      original.call(this, force);
+      return;
+    }
+    state.dropped++;
+    state.report?.(this.type);
+  };
+}
+
+/** Install once per Three prototype. Later editor installation can add its
+ * diagnostic without replacing the runtime wrapper or losing its count. */
+export function installAudioPoseGuard(report?: PoseReporter): void {
+  guard(THREE.AudioListener.prototype as unknown as AudioPrototype, report);
+  guard(THREE.PositionalAudio.prototype as unknown as AudioPrototype, report);
+}
+
+/** Non-finite pose updates dropped by this Three instance's guard. */
+export function audioPoseUpdatesDropped(): number {
+  return (
+    ((THREE.AudioListener.prototype as unknown as AudioPrototype)[GUARD_STATE]?.dropped ?? 0) +
+    ((THREE.PositionalAudio.prototype as unknown as AudioPrototype)[GUARD_STATE]?.dropped ?? 0)
+  );
+}

package/src/runtime/core/frame-pacing.ts

@@ -0,0 +1,126 @@
+/**
+ * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
+ * extracted PURE.
+ *
+ * `editor-game/src/runtime/core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
+ * `performance.now`); this module owns the arithmetic, so the interesting
+ * cases — a display frame that consumes zero substeps, a frame that hits the
+ * substep ceiling, the spiral-of-death clamp, alpha's monotonic march across a
+ * substep gap — are testable without stubbing a single global.
+ *
+ * The substep half is byte-for-byte the pacing the loop has always used
+ * (clamp the raw frame gap, scale by `timeScale`, clamp the accumulator, then
+ * consume up to `maxSubSteps` whole steps). The addition is `alpha`: the
+ * fraction of a fixed step the accumulator is holding AFTER those substeps
+ * were consumed, which is what lets a renderer present between two fixed
+ * states instead of only at them.
+ */
+
+/** The two constants that define a loop's fixed cadence. */
+export interface FramePacingLimits {
+  /** Seconds per fixed substep (the loop's `fixedTimestep`). */
+  readonly fixedDt: number;
+  /** Substep ceiling per display frame — also the accumulator's hard ceiling. */
+  readonly maxSubSteps: number;
+}
+
+/** What one display frame's worth of wall time resolves to. */
+export interface PacedFrame {
+  /** Whole fixed substeps this display frame should consume (0..maxSubSteps). */
+  readonly steps: number;
+  /** The accumulator AFTER those substeps were consumed. */
+  readonly accumulator: number;
+  /**
+   * Interpolation alpha in `[0, 1]` — `accumulator / fixedDt`, i.e. how far
+   * the presentation clock sits past the last completed fixed state. `0` means
+   * "exactly on the last fixed state"; `0.5` means "halfway to the next one".
+   */
+  readonly alpha: number;
+  /**
+   * The display frame's own delta in seconds, clamped and `timeScale`d exactly
+   * like the time fed to the accumulator. This is the delta a per-display-frame
+   * consumer (post-processing, particles, a `RenderStepped`-shaped callback)
+   * should integrate against — NOT `fixedDt`, which is a sim quantity.
+   */
+  readonly displayDt: number;
+}
+
+/**
+ * `accumulator / fixedDt`, clamped to `[0, 1]`.
+ *
+ * Clamped rather than asserted because the accumulator can legitimately still
+ * hold a whole step when a frame hits the `maxSubSteps` ceiling; presenting
+ * "all the way at the next fixed state" is the only honest answer there, and a
+ * NaN/negative/zero-`fixedDt` degenerate resolves to `0` (present the last
+ * fixed state) rather than poisoning every transform downstream.
+ */
+export function interpolationAlpha(accumulator: number, fixedDt: number): number {
+  if (!Number.isFinite(accumulator) || !Number.isFinite(fixedDt) || fixedDt <= 0) return 0;
+  if (accumulator <= 0) return 0;
+  const alpha = accumulator / fixedDt;
+  return alpha >= 1 ? 1 : alpha;
+}
+
+/**
+ * The one legal range for `GameLoop.timeScale`, and therefore the range any
+ * instrument that DRIVES it must offer (`editor-game/src/runtime/dev/instruments.ts`'s Time-scale
+ * slider reads exactly this — a second copy of `[0, 8]` in a control's bounds
+ * is how a slider ends up able to request a value the loop then silently
+ * refuses).
+ */
+export const TIME_SCALE_RANGE = { min: 0, max: 8 } as const;
+
+/**
+ * Clamp a requested time scale into {@link TIME_SCALE_RANGE}. Extracted from
+ * `editor-game/src/runtime/core/game-loop.ts`'s `set timeScale` (which still owns the out-of-range
+ * console warning — this function only computes) so the loop and every reader
+ * of the range agree by construction.
+ *
+ * A NON-FINITE request resolves to `min`, not to itself: `Math.min(8,
+ * Math.max(0, NaN))` is `NaN`, and a `NaN` time scale poisons the accumulator
+ * permanently — every frame afterwards consumes zero substeps and no warning
+ * ever repeats. Freezing (loudly, via the setter's warning) is recoverable;
+ * a silently `NaN`-ed loop is not.
+ */
+export function clampTimeScale(value: number): number {
+  if (!Number.isFinite(value)) return TIME_SCALE_RANGE.min;
+  return Math.min(TIME_SCALE_RANGE.max, Math.max(TIME_SCALE_RANGE.min, value));
+}
+
+/**
+ * Resolve one display frame: how many fixed substeps it consumes, what the
+ * accumulator holds afterwards, and the alpha/displayDt the render pass should
+ * present with.
+ *
+ * @param accumulator unconsumed sim time carried in from the previous frame
+ * @param rawDt       wall-clock seconds since the previous frame
+ * @param timeScale   the loop's live time scale (already clamped to [0, 8] by
+ *                    its setter — this function does not re-clamp it)
+ */
+export function paceFrame(
+  accumulator: number,
+  rawDt: number,
+  timeScale: number,
+  limits: FramePacingLimits,
+): PacedFrame {
+  const { fixedDt, maxSubSteps } = limits;
+  // Also the accumulator's hard ceiling (see the spiral-of-death clamp below).
+  const maxAccumulator = fixedDt * maxSubSteps;
+
+  // Clamp large frame gaps (a slow frame, a debugger pause) BEFORE scaling by
+  // timeScale.
+  const displayDt = Math.min(rawDt, maxAccumulator) * timeScale;
+  let next = accumulator + displayDt;
+  // Spiral-of-death guard: bound the accumulator regardless of timeScale or
+  // frame-gap size. Time that can't possibly be caught up on is dropped, never
+  // carried forward.
+  if (next > maxAccumulator) next = maxAccumulator;
+
+  let steps = 0;
+  while (next >= fixedDt && steps < maxSubSteps) {
+    next -= fixedDt;
+    steps++;
+  }
+
+  return { steps, accumulator: next, alpha: interpolationAlpha(next, fixedDt), displayDt };
+}

package/src/runtime/core/game-loop.ts

@@ -0,0 +1,225 @@
+import { clampTimeScale, paceFrame, TIME_SCALE_RANGE } from './frame-pacing';
+import type { GameLoopConfig, GameLoopLiveness } from './types';
+
+/** A visible rAF chain that has produced no callback for this long is not
+ * honestly "running" merely because its callback remains armed. One second
+ * is far beyond an ordinary dropped frame and short enough for status to
+ * report browser starvation while it is still actionable. */
+const LOOP_STARVATION_MS = 1_000;
+
+/**
+ * Fixed-timestep game loop with accumulator pattern — SIM at a fixed rate,
+ * PRESENTATION at the display's rate.
+ *
+ * Per real (rAF) frame:
+ *
+ *  1. the accumulator absorbs the frame gap (clamped, `timeScale`d) and
+ *     `config.update(fixedDt)` runs once per WHOLE fixed substep it can
+ *     consume, up to `maxSubSteps` — unchanged, and still the only thing that
+ *     advances gameplay, physics, `tick`/`simT` and the sim clock;
+ *  2. `config.render(alpha, displayDt)` runs EXACTLY ONCE, whatever step 1
+ *     did — including zero times. `alpha` is `accumulator / fixedDt` after
+ *     step 1 (see `core/frame-pacing.ts`): how far presentation sits past the
+ *     last completed fixed state, in `[0, 1]`.
+ *
+ * So a 120 Hz display draws 120 frames a second off a 60 Hz simulation, and a
+ * frame that consumes zero substeps still presents — which is the whole point:
+ * before this, motion presented at SIM rate, so half of every 120 Hz display's
+ * frames were duplicates and there was nowhere at all to host
+ * `RenderStepped`-shaped per-display-frame code (camera polish, procedural
+ * sway). `Game.onRenderStep` (`runtime/game.ts`) is that host, driven from
+ * this callback.
+ *
+ * `config.render` is OPTIONAL, and the hosts that don't pass it keep the old
+ * shape exactly: the `render` phase then still runs inside `config.update` as
+ * the last phase of `PHASE_ORDER` (`runtime/game.ts` only skips the render
+ * phases when its caller asks it to). That is deliberate, because two paths
+ * must stay frame-exact and neither goes through the rAF arm at all:
+ * `externalDrive` capture/offline export (see `GameLoopConfig.externalDrive`)
+ * and `Game.runTicks`, which drives `runFrame` directly.
+ */
+export function createGameLoop(config: GameLoopConfig) {
+  const fixedDt = config.fixedTimestep ?? 1 / 60;
+  // Also the accumulator's hard ceiling — `paceFrame` derives
+  // `fixedDt * maxSubSteps` from these two and clamps against it.
+  const maxSubSteps = config.maxSubSteps ?? 8;
+  // I2 (render-control runtime mode, see `GameLoopConfig.externalDrive`'s
+  // doc comment): in this mode `start()` below deliberately skips both the
+  // `requestAnimationFrame` arm AND the `visibilitychange` listener install —
+  // no wall-clock timing source ever exists for this loop instance, so
+  // `config.update` can only ever be invoked by an external driver calling
+  // into the render-control seam, never by this file's own `frame()`.
+  const externalDrive = config.externalDrive ?? false;
+
+  let accumulator = 0;
+  let lastTime = 0;
+  let running = false;
+  let rafId = 0;
+  let timeScale = 1.0;
+
+  // Idle throttle (T2.1): a hidden tab stops the loop outright; becoming
+  // visible again restarts it with the accumulator clock resynced to "now" —
+  // deliberately no catch-up burst for the wall-clock time spent hidden.
+  let visibilityPaused = false;
+  let visibilityListenerAttached = false;
+
+  /** Reconcile the gate against the CURRENT document bit, not merely the
+   * last event. Browsers can miss/coalesce visibilitychange around window
+   * occlusion and reloads; reading liveness is itself a recovery opportunity,
+   * so a stale event can never leave this flag permanently wedged. */
+  function reconcileVisibilityGate() {
+    if (externalDrive || !visibilityListenerAttached) return;
+    if (typeof document === 'undefined') return;
+    if (document.hidden) {
+      if (running) {
+        running = false;
+        cancelAnimationFrame(rafId);
+        visibilityPaused = true;
+      }
+    } else if (visibilityPaused) {
+      visibilityPaused = false;
+      running = true;
+      lastTime = performance.now();
+      accumulator = 0;
+      rafId = requestAnimationFrame(frame);
+    }
+  }
+
+  function handleVisibilityChange() {
+    reconcileVisibilityGate();
+  }
+
+  function frame(currentTime: number) {
+    if (!running) return;
+    rafId = requestAnimationFrame(frame);
+
+    // Convert to seconds
+    const rawDt = (currentTime - lastTime) / 1000;
+    lastTime = currentTime;
+
+    // All of the pacing arithmetic — frame-gap clamp, timeScale, the
+    // spiral-of-death accumulator clamp, the substep count and the
+    // interpolation alpha — lives in `core/frame-pacing.ts`, pure and unit
+    // tested. The accumulator is written back BEFORE the substeps run so a
+    // throwing `update` cannot make the loop re-consume time it already
+    // charged for.
+    const paced = paceFrame(accumulator, rawDt, timeScale, { fixedDt, maxSubSteps });
+    accumulator = paced.accumulator;
+
+    // Fixed-rate: gameplay/physics, once per consumed substep. Zero times on
+    // a frame that could not fill one.
+    for (let i = 0; i < paced.steps; i++) config.update(fixedDt);
+
+    // Display-rate: exactly once per real frame, whatever the substep count
+    // was — see the module doc comment. Optional; a host that never passes
+    // `render` keeps rendering inside `update`'s phase list.
+    config.render?.(paced.alpha, paced.displayDt);
+  }
+
+  return {
+    start() {
+      if (running) return;
+      running = true;
+      // A direct start() call can land while the loop is auto-loop-starved
+      // (`visibilityPaused` true, `running` false, no rAF pending). Without this
+      // reset, a later visibilitychange-to-visible would see stale
+      // `visibilityPaused === true` and spawn a SECOND rAF chain on top of the
+      // one this call is about to start (doubled update()/render() overhead
+      // until the next stop() — no sim-speed effect, but wasted work).
+      visibilityPaused = false;
+      lastTime = performance.now();
+      accumulator = 0;
+
+      // External-drive mode (I2): never arm rAF and never install the
+      // visibilitychange auto-stop handler. `running` still flips `true`
+      // above (so `isRunning`/`stop()` behave normally for a caller that
+      // treats this loop as "started"), but nothing will ever call
+      // `frame()` — a headless/backgrounded capture page cannot have this
+      // loop silently killed by `document.hidden`, because there is no
+      // listener to fire in the first place.
+      if (externalDrive) return;
+
+      // A play session can be started while the editor tab is ALREADY
+      // hidden. In that case no future visibilitychange-to-hidden event will
+      // arrive, and arming rAF would leave `running=true` forever while the
+      // browser executes zero callbacks. Classify and park the loop before
+      // arming it so status is truthful and visibility restore can resume it.
+      if (!visibilityListenerAttached && typeof document !== 'undefined') {
+        document.addEventListener('visibilitychange', handleVisibilityChange);
+        visibilityListenerAttached = true;
+      }
+      if (typeof document !== 'undefined' && document.hidden) {
+        running = false;
+        visibilityPaused = true;
+        return;
+      }
+
+      rafId = requestAnimationFrame(frame);
+    },
+
+    stop() {
+      running = false;
+      visibilityPaused = false;
+      cancelAnimationFrame(rafId);
+
+      if (visibilityListenerAttached && typeof document !== 'undefined') {
+        document.removeEventListener('visibilitychange', handleVisibilityChange);
+        visibilityListenerAttached = false;
+      }
+    },
+
+    get isRunning() {
+      reconcileVisibilityGate();
+      return running;
+    },
+
+    /**
+     * Truthful liveness (issue #175 — see `GameLoopLiveness`'s doc comment
+     * in `core/types.ts` for the full contract). Unlike `isRunning` above,
+     * this distinguishes a starved rAF loop from an actually-stopped loop.
+     * `visibilityPaused` records the deliberate `document.hidden` gate, and
+     * every read first reconciles that flag against the CURRENT document bit
+     * so a missed visibilitychange cannot wedge it. A visible, armed chain
+     * also reports starvation when no real frame callback has arrived within
+     * {@link LOOP_STARVATION_MS}; "armed" alone is not evidence of progress. An
+     * `externalDrive` loop never installs the visibility listener at all
+     * (see `start()` above), so `visibilityPaused` stays permanently `false` for
+     * it — it only ever reports `'running'` or `'stopped'`.
+     */
+    get liveness(): GameLoopLiveness {
+      reconcileVisibilityGate();
+      if (visibilityPaused) return 'loop-starved';
+      if (running && !externalDrive && performance.now() - lastTime > LOOP_STARVATION_MS) {
+        return 'loop-starved';
+      }
+      return running ? 'running' : 'stopped';
+    },
+
+    set timeScale(value: number) {
+      const clamped = clampTimeScale(value);
+      if (clamped !== value) {
+        console.warn(
+          `[game-loop] timeScale ${value} is out of range ` +
+            `[${TIME_SCALE_RANGE.min}, ${TIME_SCALE_RANGE.max}]; clamped to ${clamped}.`,
+        );
+      }
+      timeScale = clamped;
+    },
+
+    get timeScale() {
+      return timeScale;
+    },
+
+    /**
+     * The fixed substep timestep (seconds) this loop's accumulator consumes
+     * per `config.update()` call (`config.fixedTimestep ?? 1/60`) — read by
+     * `Game.runTicks` (D15, `runtime/game.ts`) so a synchronous fast-forward
+     * burst drives `game.runFrame` with the SAME `fixedDt` this loop's own
+     * rAF-driven accumulator would have used, without exposing (or
+     * `runTicks` needing) any other internal loop state.
+     */
+    get fixedDt() {
+      return fixedDt;
+    },
+  };
+}

package/src/runtime/core/game-scoped-slot.ts

@@ -0,0 +1,28 @@
+/**
+ * A non-enumerable slot carried by the game object itself.
+ *
+ * Packaged editor play can legitimately involve two copies of `@volter/game-runtime`:
+ * the editor bundle creates the Game, while the project's Vite graph creates
+ * its root adapter. Module-local WeakMaps cannot cross that boundary. A
+ * registry-backed symbol can, while keeping the internal value off the public
+ * string-keyed Game surface.
+ */
+export function createGameScopedSlot<T>(name: string): {
+  set(owner: object, value: T): void;
+  get(owner: object): T | null;
+} {
+  const key = Symbol.for(`@vgai/game-runtime/game-scoped/${name}`);
+
+  return {
+    set(owner, value) {
+      Object.defineProperty(owner, key, {
+        configurable: true,
+        enumerable: false,
+        value,
+      });
+    },
+    get(owner) {
+      return (owner as { [key: symbol]: T | undefined })[key] ?? null;
+    },
+  };
+}

package/src/runtime/core/seeded-random.ts

@@ -0,0 +1,162 @@
+/**
+ * The seeded-random core (T-D15.1). `ctx.random` is a game-scoped PRNG with
+ * NAMED STREAMS: calling the object itself (`ctx.random()`) draws from the
+ * `'gameplay'` stream; `ctx.random.stream('vfx')` (or any other name) derives
+ * an INDEPENDENT generator, so a cosmetic/VFX draw can never perturb the
+ * gameplay draw order — the classic replay-drift trap option B ("one
+ * game-scoped PRNG only") would fall into (see the design doc's §2.a option
+ * table).
+ *
+ * Each stream is seeded from `fnv1a(name) ^ rootSeed` — deterministic given
+ * the root seed, independent of draw order across streams (drawing from
+ * `'vfx'` never advances `'gameplay'`'s generator, since they are two
+ * separate mulberry32 instances). `reseed(seed)` re-derives every stream
+ * that has EVER been asked for via `.stream(name)` (including the implicit
+ * `'gameplay'` stream `ctx.random()` itself draws from) — future draws only:
+ * numbers already returned before a `reseed()` call are not (and cannot be)
+ * un-returned; this matches `play.seed.set`'s documented semantics (T-D15.6).
+ *
+ * Deliberately reuses {@link createMulberry32} FROM `runtime/render-seed.ts`
+ * (the render/capture door's own generator) rather than duplicating the
+ * algorithm — `render-seed.ts` stays a zero-import module itself (this file
+ * imports FROM it, never the reverse), so this is a dependency-clean
+ * direction: the render/capture door and the gameplay determinism door share
+ * one PRNG implementation without either depending on the other's door
+ * logic (§2.a: "Kept as-is for the render/capture door only" — the two doors
+ * stay orthogonal; only the generator function itself is shared).
+ */
+
+import { createMulberry32 } from '../render-seed';
+import { createGameScopedSlot } from './game-scoped-slot';
+
+/** The name `ctx.random()` (called with no `.stream(...)`) draws from. */
+export const GAMEPLAY_STREAM = 'gameplay';
+
+/** The fixed fallback seed a `SeededRandom` boots with when no explicit seed
+ *  is supplied (mirrors `render-seed.ts`'s own `DEFAULT_RENDER_SEED` in
+ *  spirit — an arbitrary but fixed golden-ratio-derived constant, never
+ *  wall-clock/`Math.random`-derived, so an UNDECLARED project's `ctx.random`
+ *  is still perfectly reproducible on its own terms even though nothing in
+ *  the manifest asked for that — it just isn't a documented CONTRACT until
+ *  `determinism.seededRandom` is declared, per T4.1's "no dead field" rule). */
+export const DEFAULT_SEEDED_RANDOM_SEED = 0x9e3779b9;
+
+/**
+ * A game-scoped random surface.
+ * Callable (draws from the `'gameplay'` stream), plus:
+ * - `stream(name)` — an independent named generator, `[0, 1)` floats, same
+ *   call signature as `Math.random`/the bare `SeededRandom` call itself.
+ * - `reseed(seed)` — re-derive every stream ever requested so far (future
+ *   draws only) from a NEW root seed.
+ * - `seed` — the CURRENT root seed (reflects the last `reseed()` call, if
+ *   any) — a live getter, not a value snapshotted at construction.
+ */
+export interface SeededRandom {
+  (): number;
+  stream(name: string): () => number;
+  reseed(seed: number): void;
+  readonly seed: number;
+}
+
+/** fnv1a-32, the standard non-cryptographic string hash — used only to mix a
+ *  stream NAME into the root seed, never as a determinism primitive on its
+ *  own (mulberry32 is still what actually produces the `[0,1)` sequence). */
+function fnv1a32(str: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+interface StreamBox {
+  /** Reassigned wholesale on `reseed()` — the wrapper function `.stream(name)`
+   *  returns to callers stays the SAME identity forever; only what it reads
+   *  from changes, which is what makes reseed observable through a handle a
+   *  caller obtained long before the reseed call. */
+  gen: () => number;
+}
+
+/**
+ * Construct a fresh, game-scoped seeded-random surface. `initialSeed` is
+ * coerced to an unsigned 32-bit integer the same way `render-seed.ts`'s
+ * `installDeterministicRandom` does (`>>> 0`), so any finite JS number is
+ * accepted.
+ */
+export function createSeededRandom(initialSeed: number): SeededRandom {
+  let rootSeed = initialSeed >>> 0;
+  const streams = new Map<string, StreamBox>();
+
+  function deriveStreamSeed(name: string): number {
+    return (fnv1a32(name) ^ rootSeed) >>> 0;
+  }
+
+  function getBox(name: string): StreamBox {
+    let box = streams.get(name);
+    if (!box) {
+      box = { gen: createMulberry32(deriveStreamSeed(name)) };
+      streams.set(name, box);
+    }
+    return box;
+  }
+
+  function streamFn(name: string): () => number {
+    const box = getBox(name);
+    return () => box.gen();
+  }
+
+  const random = (() => getBox(GAMEPLAY_STREAM).gen()) as SeededRandom;
+
+  Object.defineProperties(random, {
+    stream: { value: streamFn, enumerable: true },
+    reseed: {
+      value: (seed: number) => {
+        rootSeed = seed >>> 0;
+        // Re-derive every stream ANYONE has ever asked for (including the
+        // implicit 'gameplay' stream, once `random()` or
+        // `.stream('gameplay')` has been called at least once) — a handle a
+        // caller stashed before this call keeps its identity but now reads
+        // from the freshly-seeded generator on its NEXT call (future draws
+        // only, per the design doc's `play.seed.set` semantics).
+        for (const [name, box] of streams) {
+          box.gen = createMulberry32(deriveStreamSeed(name));
+        }
+      },
+      enumerable: true,
+    },
+    seed: {
+      get: () => rootSeed,
+      enumerable: true,
+    },
+  });
+
+  return random;
+}
+
+// ---------------------------------------------------------------------------
+// Game-scoped registry — mirrors `editor-game/src/runtime/debug-registry.ts`'s
+// `registerDebugRegistry`/`getDebugRegistry` game-slot pattern exactly, but
+// keyed on a bare `object` (not `Game`) so this module never needs to import
+// `editor-game/src/runtime/game.ts` even as a type — `core/` stays independent of `runtime/`
+// except for the one explicit, documented `render-seed.ts` reuse above.
+// `createGame` (`editor-game/src/runtime/game.ts`) is the one real registrant, passing itself
+// (the `GameInternal` shell) as the key, exactly like it does for
+// `registerDebugRegistry(gameInternal, debugRegistry)`.
+// ---------------------------------------------------------------------------
+
+const registryByOwner = createGameScopedSlot<SeededRandom>('seeded-random');
+
+/** Called once by `createGame`, right after both the seeded-random surface
+ *  and the Game shell object exist — mirrors `registerDebugRegistry`. */
+export function registerSeededRandom(owner: object, random: SeededRandom): void {
+  registryByOwner.set(owner, random);
+}
+
+/** The game-scoped `SeededRandom` backing every world's `ctx.random` — `null`
+ *  for an owner built without one (there is always one for every real
+ *  `createGame` call; `null` only for a hand-built `Game`-shaped stand-in a
+ *  test constructs without going through `createGame`). */
+export function getSeededRandom(owner: object): SeededRandom | null {
+  return registryByOwner.get(owner) ?? null;
+}