@volter/editor-game 0.5.66 → 0.5.67

package/src/runtime/render-seed.ts

@@ -0,0 +1,77 @@
+/**
+ * Deterministic `Math.random` seeding for render-control mode (I2 AC:
+ * "`Math.random` is deterministically seeded/stubbed page-wide before any
+ * game module executes").
+ *
+ * Deliberately a ZERO-IMPORT module (no `three`, no other engine file) so
+ * its own evaluation is instantaneous — a render-mode entry page loads this
+ * as its FIRST `<script type="module">` tag, before the tag that pulls in
+ * the actual game/runtime modules. Per the HTML module-script ordering
+ * rules, sibling `<script type="module">` tags without `async` execute in
+ * document order, and each one's own dependency graph (here, empty) is
+ * fully evaluated before the browser moves to the next tag — so calling
+ * {@link maybeInstallRenderModeRandom} from this module's importer, in a
+ * script tag placed before the game's own entry tag, guarantees every
+ * subsequent module's top-level code (and everything it does at runtime)
+ * observes the seeded generator, never the platform's real
+ * cryptographically-random `Math.random`.
+ *
+ * This module does not decide WHETHER to seed on its own (importing it has
+ * no side effect) — the caller decides, by calling
+ * {@link maybeInstallRenderModeRandom} (query-param gated) or
+ * {@link installDeterministicRandom} (unconditional) from a tiny bootstrap
+ * entry. See `packages/engine/e2e/fixture/render-seed-entry.ts` for the
+ * worked bootstrap this module is designed to be loaded from.
+ */
+
+/**
+ * mulberry32 — a small, fast, deterministic 32-bit PRNG. Not cryptographic;
+ * this is explicitly a determinism tool (reproducible capture), not a
+ * security primitive. Returns a function with the same call signature as
+ * `Math.random` (no arguments, `[0, 1)` float).
+ */
+export function createMulberry32(seed: number): () => number {
+  let state = seed >>> 0;
+  return function mulberry32(): number {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Replace the global `Math.random` with a seeded, deterministic generator.
+ * Idempotent to call more than once (each call re-seeds from scratch — the
+ * last call wins), which matters for HMR-style re-execution.
+ */
+export function installDeterministicRandom(seed: number): void {
+  Math.random = createMulberry32(seed);
+}
+
+/** Query-param name that opts a page into render-control mode (I2 AC 4: the
+ *  mode must be unavailable/protected in normal production gameplay unless
+ *  explicitly enabled). Shared with `render-control.ts`'s own production
+ *  guard so both checks agree on the same flag. */
+export const RENDER_MODE_QUERY_PARAM = 'vgai-render';
+/** Optional query param to pin a specific seed (default below when absent). */
+export const RENDER_SEED_QUERY_PARAM = 'vgai-seed';
+const DEFAULT_RENDER_SEED = 0x9e3779b9; // golden-ratio constant — an arbitrary but fixed default
+
+/**
+ * Seed `Math.random` iff the page's URL opts into render mode
+ * (`?vgai-render=1`), reading an optional `?vgai-seed=<int>` override.
+ * Returns whether it seeded, purely for the caller's own diagnostics/log —
+ * the bootstrap entry doesn't need to branch on it.
+ */
+export function maybeInstallRenderModeRandom(
+  location: { search: string } = window.location,
+): boolean {
+  const params = new URLSearchParams(location.search);
+  if (params.get(RENDER_MODE_QUERY_PARAM) !== '1') return false;
+  const seedParam = params.get(RENDER_SEED_QUERY_PARAM);
+  const seed = seedParam !== null && seedParam !== '' ? Number(seedParam) : DEFAULT_RENDER_SEED;
+  installDeterministicRandom(Number.isFinite(seed) ? seed : DEFAULT_RENDER_SEED);
+  return true;
+}

package/src/runtime/run-ticks-settled.ts

@@ -0,0 +1,73 @@
+/**
+ * `runTicksWhenSettled` — the settled-aware tick driver behind BOTH session run-ticks doors
+ * (the bridge's `window.__vgai.runTicksSettled`, the editor relay's `run-ticks` case), one
+ * implementation with byte-identical semantics across doors, exactly as `runTicks` itself is
+ * shared (D17).
+ *
+ * Why it exists: `Game.runTicks` is deliberately SYNCHRONOUS, but a game may be intentionally
+ * BETWEEN worlds when a tick arrives — `reload_current_scene` unmounts the running scene and
+ * the fresh one arrives on an ASYNC React commit. A tick driven into that gap runs against
+ * nothing, and WHICH tick first runs the fresh world then depends on wall timing between
+ * driver calls — measured on the starter-kit fidelity drive: the same script produced 7 or 8
+ * post-respawn walked ticks depending on how long the driver idled between ticks. The fidelity
+ * contract treats a nondeterministic channel as a MECHANISM defect (the instrument that spelled
+ * that out went with the archived import lanes, `archive/*-lane-2026-09-19`; the rule did not),
+ * and this is the mechanism: ticks must not race remounts.
+ *
+ * So this driver runs the budget ONE tick at a time and, before each tick, waits for every
+ * registered world-settled probe ({@link DebugRegistry.registerWorldSettledProbe} — declared by
+ * the game through its `debug.settled` entry export) to answer `true`. The wall-clock poll is
+ * sound because the OUTCOME no longer depends on timing: however long the commit takes, the
+ * next tick is always the fresh world's first. A game that registers no probe gets the old
+ * behavior exactly (every wait resolves immediately).
+ *
+ * The wait is BOUNDED and loud: a remount that never settles is a real defect, and
+ * `WORLD_UNSETTLED_TIMEOUT` names it rather than letting the driver hang.
+ */
+import { DebugError, type DebugRegistry, type RunTicksOptions } from './debug-registry';
+
+/** A remount is a couple of React commits on an idle main thread; polling faster buys nothing
+ *  and slower delays every settled check by the poll period. */
+const SETTLED_POLL_MS = 4;
+/** A commit that hasn't landed after this long is not "in flight", it is stuck. */
+const SETTLED_TIMEOUT_MS = 10_000;
+
+export async function runTicksWhenSettled(
+  registry: Pick<DebugRegistry, 'worldSettled' | 'getRunTicksTarget'>,
+  n: number,
+  opts?: RunTicksOptions,
+  /** Test-only overrides — real callers leave this unset (the same seam
+   *  convention as fast-forward's `batchTicks`). */
+  waits?: { timeoutMs?: number; pollMs?: number },
+): Promise<void> {
+  const target = registry.getRunTicksTarget();
+  if (target === null) {
+    throw new DebugError(
+      'RUN_TICKS_UNAVAILABLE',
+      'runTicksWhenSettled: no run-ticks target is wired — no Game has mounted yet',
+    );
+  }
+  const timeoutMs = waits?.timeoutMs ?? SETTLED_TIMEOUT_MS;
+  const pollMs = waits?.pollMs ?? SETTLED_POLL_MS;
+  const render = opts?.render ?? 'last';
+  for (let i = 0; i < n; i++) {
+    if (!registry.worldSettled()) {
+      const deadline = Date.now() + timeoutMs;
+      while (!registry.worldSettled()) {
+        if (Date.now() > deadline) {
+          throw new DebugError(
+            'WORLD_UNSETTLED_TIMEOUT',
+            `runTicksWhenSettled: a world-settled probe still answers false after ${timeoutMs}ms — ` +
+              'a scene remount (or a broken probe) is stuck, and driving ticks into it would race it',
+          );
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+      }
+    }
+    const isFinalTick = i === n - 1;
+    // Same per-tick render policy `Game.runTicks` applies across its own loop.
+    const tickRender =
+      render === 'all' ? 'all' : render === 'none' ? 'none' : isFinalTick ? 'last' : 'none';
+    target.runTicks(1, { render: tickRender });
+  }
+}

package/src/runtime/setup/setup-audio.ts

@@ -0,0 +1,72 @@
+import * as THREE from 'three';
+import { type AudioBusMixer, createAudioBusMixer } from '../audio/bus-mixer';
+import { installAudioPoseGuard } from '../audio/pose-guard';
+
+export interface AudioContext {
+  listener: THREE.AudioListener;
+  masterGain: GainNode;
+  buses: {
+    music: GainNode;
+    sfx: GainNode;
+    voice: GainNode;
+  };
+  /**
+   * The named-bus mixer the three below are buses OF (`../audio/bus-mixer.ts`).
+   *
+   * `buses` is a fixed struct because those three names are the ones the engine
+   * itself routes; a game with an `ambience`, a `ui` or a per-character bus asks
+   * the mixer for it by name — `audio.mixer.bus('ambience', 'master')` mints it
+   * under the master gain, `audio.mixer.setDb('ambience', -6)` sets it in
+   * decibels — and `audio.mixer.disconnect()` is the ONE teardown for all of
+   * them, the three struct members included.
+   */
+  mixer: AudioBusMixer;
+  /** Call this on first user interaction (click/key) to resume audio context */
+  resume: () => void;
+}
+
+/** The bus every other bus routes into, and the node `masterGain` is. */
+const MASTER_BUS = 'master';
+
+/**
+ * Creates the audio listener and bus hierarchy.
+ *
+ * Bus routing: music/sfx/voice → master → destination
+ * Attach `listener` to the active camera: `camera.add(audioCtx.listener)`.
+ */
+export function setupAudio(camera: THREE.Camera): AudioContext {
+  installAudioPoseGuard();
+  const listener = new THREE.AudioListener();
+  camera.add(listener);
+
+  const ctx = listener.context;
+  const mixer = createAudioBusMixer({ context: ctx, destination: ctx.destination });
+  const masterGain = mixer.bus(MASTER_BUS);
+
+  // Route the Three.js listener through masterGain so that THREE.Audio /
+  // THREE.PositionalAudio objects are also silenced by the mute button.
+  listener.gain.disconnect();
+  listener.gain.connect(masterGain);
+
+  const musicGain = mixer.bus('music', MASTER_BUS);
+  musicGain.gain.value = 0.7;
+
+  const sfxGain = mixer.bus('sfx', MASTER_BUS);
+  const voiceGain = mixer.bus('voice', MASTER_BUS);
+
+  return {
+    listener,
+    masterGain,
+    buses: {
+      music: musicGain,
+      sfx: sfxGain,
+      voice: voiceGain,
+    },
+    mixer,
+    resume() {
+      if (ctx.state === 'suspended') {
+        ctx.resume();
+      }
+    },
+  };
+}

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

@@ -60,9 +60,9 @@
  */
 
 import { editorHost } from '@volter/editor-sdk/host';
-import { installAudioPoseGuard as installSharedAudioPoseGuard } from '@volter/game-runtime/audio/pose-guard';
+import { installAudioPoseGuard as installSharedAudioPoseGuard } from '../runtime/audio/pose-guard';
 
-export { audioPoseUpdatesDropped } from '@volter/game-runtime/audio/pose-guard';
+export { audioPoseUpdatesDropped } from '../runtime/audio/pose-guard';
 
 let reported = false;
 

package/src/services/game-audio.ts

@@ -0,0 +1,152 @@
+/**
+ * THE PAGE'S VIEW OF A RUNNING GAME'S WEB AUDIO — the editor's own audio adapter for a game
+ * that declares none (the ingest way: the game is idiomatic code, and the editor reads it).
+ *
+ * UNLOCK. A game running in the editor's page can create its AudioContext before the
+ * visitor's first gesture (survivor's auto-attack lands kills while they are still reading),
+ * and browsers with a strict autoplay policy then hold it suspended until `resume()` runs
+ * INSIDE a trusted input handler. The game's own unlock listeners go through the realm's
+ * gated re-dispatch, which is no longer that trusted stack — two human passes heard both
+ * flagship canvas games silent on first load and cured them only by restarting under a
+ * gesture (runhuman 23/33). The EDITOR owns the page, so it wraps the page's AudioContext
+ * constructor once at boot to track instances, and resumes any suspended one from
+ * capture-phase pointerdown/keydown handlers — the real, trusted stack.
+ *
+ * MUTE AND THE GRAPH. The same wrap is what lets the editor pause a game's sound and show
+ * what it built without the game implementing anything: every connection a game makes to
+ * its context's destination is routed through one editor-owned gain per context, and every
+ * connection is recorded. {@link observedGameAudio} is that adapter; Play installs it for a
+ * game whose systems declare no `audio` (`play-mode.ts`).
+ */
+
+import type { AudioAdapter, AudioGraphNode } from '@volter/editor-project/adapter/system-adapter';
+
+const tracked = new Set<WeakRef<AudioContext>>();
+
+function resumeSuspended(): void {
+  for (const ref of tracked) {
+    const ctx = ref.deref();
+    if (!ctx || ctx.state === 'closed') {
+      tracked.delete(ref);
+      continue;
+    }
+    if (ctx.state === 'suspended') void ctx.resume();
+  }
+}
+
+/** Install once at editor boot (`audio.service.ts`). Idempotent. */
+export function installGameAudio(): void {
+  const host = window as unknown as { __vgaiAudioUnlock?: boolean } & typeof window;
+  if (host.__vgaiAudioUnlock) return;
+  host.__vgaiAudioUnlock = true;
+  const Orig = window.AudioContext;
+  if (typeof Orig !== 'function') return;
+  window.AudioContext = class extends Orig {
+    constructor(...args: ConstructorParameters<typeof AudioContext>) {
+      super(...args);
+      tracked.add(new WeakRef(this));
+      trackedContexts.add(this);
+    }
+  };
+  installConnectionRecorder();
+  window.addEventListener('pointerdown', resumeSuspended, { capture: true });
+  window.addEventListener('keydown', resumeSuspended, { capture: true });
+}
+
+// ---- Routing and recording -------------------------------------------------------------
+
+/** One editor gain per tracked context, between the game's graph and the real output. */
+const buses = new WeakMap<BaseAudioContext, GainNode>();
+const trackedContexts = new WeakSet<BaseAudioContext>();
+let muted = false;
+
+/** The game's recorded connections: node → the nodes it feeds. */
+const outputs = new WeakMap<AudioNode, Set<AudioNode>>();
+const seen = new Set<WeakRef<AudioNode>>();
+const ids = new WeakMap<AudioNode, string>();
+let nextId = 0;
+
+function idOf(node: AudioNode): string {
+  if (node instanceof AudioDestinationNode) return 'destination';
+  let id = ids.get(node);
+  if (!id) {
+    id = `n${++nextId}`;
+    ids.set(node, id);
+    seen.add(new WeakRef(node));
+  }
+  return id;
+}
+
+function installConnectionRecorder(): void {
+  const connect = AudioNode.prototype.connect as (this: AudioNode, ...args: unknown[]) => unknown;
+  const disconnect = AudioNode.prototype.disconnect as (this: AudioNode, ...args: unknown[]) => unknown;
+  const busFor = (context: BaseAudioContext): GainNode => {
+    let bus = buses.get(context);
+    if (!bus) {
+      bus = context.createGain();
+      bus.gain.value = muted ? 0 : 1;
+      connect.call(bus, context.destination);
+      buses.set(context, bus);
+    }
+    return bus;
+  };
+  const routed = (target: unknown): unknown =>
+    target instanceof AudioDestinationNode && trackedContexts.has(target.context) ? busFor(target.context) : target;
+  AudioNode.prototype.connect = function (this: AudioNode, ...args: unknown[]) {
+    const [target, ...rest] = args;
+    if (target instanceof AudioNode && !(buses.get(this.context) === this)) {
+      idOf(this);
+      idOf(target);
+      let set = outputs.get(this);
+      if (!set) outputs.set(this, (set = new Set()));
+      set.add(target);
+    }
+    const result = connect.call(this, routed(target), ...rest);
+    // A game chains `a.connect(b).connect(c)`: it gets back what it asked for.
+    return target instanceof AudioDestinationNode ? target : result;
+  } as typeof AudioNode.prototype.connect;
+  AudioNode.prototype.disconnect = function (this: AudioNode, ...args: unknown[]) {
+    const [target] = args;
+    if (target === undefined || typeof target === 'number') outputs.delete(this);
+    else if (target instanceof AudioNode) outputs.get(this)?.delete(target);
+    return disconnect.call(this, ...(args.length ? [routed(target), ...args.slice(1)] : []));
+  } as typeof AudioNode.prototype.disconnect;
+}
+
+/** Silence every tracked game context, or restore it; the game's own gains are untouched. */
+function setGameAudioMuted(next: boolean): void {
+  muted = next;
+  for (const ref of tracked) {
+    const bus = ref.deref() && buses.get(ref.deref()!);
+    if (bus) bus.gain.value = next ? 0 : 1;
+  }
+}
+
+/** What the game has built, as the recorded connections read it now. */
+function gameAudioGraph(): AudioGraphNode[] {
+  const nodes: AudioGraphNode[] = [];
+  let destination = false;
+  for (const ref of seen) {
+    const node = ref.deref();
+    if (!node) {
+      seen.delete(ref);
+      continue;
+    }
+    const targets = [...(outputs.get(node) ?? [])];
+    if (targets.some((target) => target instanceof AudioDestinationNode)) destination = true;
+    nodes.push({ id: idOf(node), type: node.constructor.name, outputs: targets.map(idOf), state: node.context.state });
+  }
+  if (destination) nodes.push({ id: 'destination', type: 'AudioDestinationNode', label: 'Output', outputs: [] });
+  return nodes;
+}
+
+/**
+ * The editor's audio adapter for a game whose systems declare none: mute through the editor's
+ * bus, resume through the trusted-gesture unlock, and the graph the game built.
+ */
+export const observedGameAudio: AudioAdapter = {
+  resume: resumeSuspended,
+  setMuted: setGameAudioMuted,
+  isMuted: () => muted,
+  graphSnapshot: gameAudioGraph,
+};