@volter/editor-game 0.5.66 → 0.5.68

package/src/runtime/gameplay-rng-trap.ts

@@ -0,0 +1,135 @@
+/**
+ * The dev-mode `Math.random` phase trap (enforcer 3, T-D15.3). A project that
+ * declares `determinism.seededRandom` is claiming ALL gameplay RNG flows
+ * through `ctx.random` — the burn-down scan (`test/gameplay-rng-ban.test.ts`)
+ * catches raw `Math.random()`/`Date.now()`/`performance.now()` call sites it
+ * can SEE in source; this trap catches what the scan structurally can't: a
+ * TRANSITIVE draw made by a third-party library the game calls into during a
+ * gameplay tick.
+ *
+ * Scope is exactly one fixed-step frame (`GameInternal.runFrame`'s whole
+ * body — see `game.ts`'s `runFrameImpl`, which brackets its entire call with
+ * `profiler.beginFrame()`/`endFrame()`; this trap's `enable()`/`disable()`
+ * are called at those exact two points) — code that runs OUTSIDE a frame
+ * (module-load-time library init, an unrelated timer callback) never trips
+ * it. Warn-once PER CALL SITE (not once ever, not once per call) — a
+ * third-party library that draws from several different internal call sites
+ * gets one warning per site, so nothing is silently swallowed after the
+ * first hit, but a hot per-frame draw from the SAME site doesn't spam.
+ * Never throws: a cosmetic third-party draw is legal, just outside the
+ * contract (the design doc is explicit about this — "warn, never throw").
+ */
+
+import { createGameScopedSlot } from './core/game-scoped-slot';
+
+export interface GameplayRngTrap {
+  /** Wrap `Math.random` for the duration of one frame — call at frame start. */
+  enable(): void;
+  /** Restore whatever `Math.random` was immediately before `enable()` — call
+   *  at frame end. A no-op if something else already replaced `Math.random`
+   *  out from under this trap between `enable()` and `disable()` (defensive;
+   *  should not happen in practice). */
+  disable(): void;
+}
+
+/** Pull a single representative "call site" line out of a captured stack —
+ *  the warn-once dedupe key. `stack[0]` is the `Error:` header line,
+ *  `stack[1]` is this trap's OWN wrapper frame — the caller's frame is the
+ *  next one down. Falls back to a fixed string when `Error().stack` isn't
+ *  populated (some non-V8 engines) so the trap still functions, just with
+ *  coarser (single-bucket) deduping. */
+function callSiteFromStack(stack: string | undefined): string {
+  if (!stack) return '<unknown call site — no stack captured>';
+  const lines = stack.split('\n');
+  return (lines[2] ?? lines[1] ?? lines[0] ?? '<unknown call site>').trim();
+}
+
+/**
+ * Construct a fresh trap. `warn` defaults to `console.warn`; tests (and any
+ * caller that wants to assert on the message) can override it to a plain
+ * capturing function instead of spying on the global console.
+ */
+export function createGameplayRngTrap(
+  warn: (message: string) => void = (message: string) => {
+    // biome-ignore lint/suspicious/noConsole: the trap's entire purpose is a structured, greppable dev-mode warning (D15) — this IS the console sink, not incidental debug output.
+    console.warn(message);
+  },
+): GameplayRngTrap {
+  const warnedSites = new Set<string>();
+  let previous: (() => number) | undefined;
+
+  function trapped(): number {
+    const site = callSiteFromStack(new Error().stack);
+    if (!warnedSites.has(site)) {
+      warnedSites.add(site);
+      warn(
+        // Deliberately NOT the literal substring "Math.random(" (the phrasing
+        // below reads fine without it) — this engine repo's OWN gameplay-rng-
+        // ban scan (`test/gameplay-rng-ban.test.ts`) greps engine src/ for
+        // that exact pattern, and a plain-text mention of the call inside
+        // this warning STRING would otherwise false-positive against itself.
+        '[determinism] the global Math.random generator was drawn from during a gameplay frame ' +
+          'while this project declares determinism.seededRandom — use ctx.random() / ' +
+          `ctx.random.stream(name) instead. Call site:\n${site}`,
+      );
+    }
+    // `previous` is always set by the time `trapped` can run — `enable()`
+    // assigns it before installing `trapped` as `Math.random`, and nothing
+    // else can invoke this function reference.
+    return previous!();
+  }
+
+  return {
+    enable() {
+      previous = Math.random;
+      Math.random = trapped;
+    },
+    disable() {
+      if (Math.random === trapped && previous) {
+        Math.random = previous;
+        previous = undefined;
+      }
+      // else: something else replaced `Math.random` out from under this trap
+      // between `enable()` and `disable()` — leave `previous` untouched.
+      // `trapped` may still be reachable via a chain built on top of it (e.g.
+      // a third party did `const wrapped = Math.random; Math.random = () =>
+      // { ...; return wrapped(); }` while `wrapped` was `trapped`) — nulling
+      // `previous` here would make that still-chained call to `trapped()`
+      // throw (`previous!()` on undefined) instead of quietly forwarding to
+      // the real original generator.
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Game-scoped registry — same slot-on-owner-object pattern as
+// `core/seeded-random.ts`'s `registerSeededRandom`/`getSeededRandom` (and
+// `debug-registry.ts`'s `registerDebugRegistry`/`getDebugRegistry`): the
+// trap's enable/disable calls live inside `game.ts`'s `runFrameImpl`, gated
+// on a boolean only the manifest-aware boot path (`mount-manifest.ts`) knows
+// how to set — `createGame` constructs the trap unconditionally (cheap, does
+// nothing while disabled) and registers a control surface for that boot path
+// to flip once it has resolved `manifest.determinism?.seededRandom`.
+// ---------------------------------------------------------------------------
+
+export interface GameplayRngTrapControl {
+  setEnabled(enabled: boolean): void;
+  readonly enabled: boolean;
+}
+
+const controlByOwner = createGameScopedSlot<GameplayRngTrapControl>('gameplay-rng-trap');
+
+/** Called once by `createGame`, alongside `registerSeededRandom`/
+ *  `registerDebugRegistry`. */
+export function registerGameplayRngTrapControl(
+  owner: object,
+  control: GameplayRngTrapControl,
+): void {
+  controlByOwner.set(owner, control);
+}
+
+/** `null` for an owner built without one — same absence precedent as
+ *  `getSeededRandom`/`getDebugRegistry`. */
+export function getGameplayRngTrapControl(owner: object): GameplayRngTrapControl | null {
+  return controlByOwner.get(owner) ?? null;
+}

package/src/runtime/host-context.ts

@@ -0,0 +1,64 @@
+/**
+ * The game runtime's extension of the shared host contexts: the `game` handle
+ * a host hands a root it mounts. `@volter/editor-project`'s host contexts carry
+ * only surfaces; this product-specific execution handle belongs here, beside
+ * the `Game` it names, so the shared project contract never imports this
+ * runtime.
+ */
+import type {
+  CanvasHostContext,
+  DomHostContext,
+  ThreeHostContext,
+} from '@volter/editor-project/adapter/host-context';
+import type { AssetCache } from '@volter/threejs-runtime/assets';
+import type * as THREE from 'three';
+import type { Game } from './game';
+
+/**
+ * THE DOORS a mounting root actually opens on the Game — and the whole
+ * reason `three`/`canvas` host contexts no longer name `GameInternal`.
+ *
+ * `GameInternal` is the HOST's own control surface: `runFrame`,
+ * `runRenderFrame`, `runTicks`, `registerRoot`, `notifySystemAdaptersChanged`,
+ * `dispose`. Handing it to an adapter's `mount()` published the loop driver to
+ * the thing being driven — nothing read those members through `host.game`, but
+ * the type said they could, so "what may a root do to its Game?" had no
+ * answer short of "everything".
+ *
+ * The two doors, each with its verified consumer:
+ *
+ *  1. **Debug-registry access** — `getDebugRegistry(host.game)`
+ *     (`r3f-root.tsx` and `canvas-root.tsx` in the editor); the registry is keyed by
+ *     Game IDENTITY, which is why this handle is the Game and not a projection
+ *     of it.
+ *  2. **The profiler toggle** — `host.game.profiler` (`r3f-root.tsx`).
+ *
+ * Both are on the PUBLIC {@link Game}, and a `GameInternal` satisfies it.
+ */
+export type HostGameHandle = Game;
+
+/**
+ * A `three`-surface host context carrying the Game root. The host constructs
+ * the Game shell BEFORE mounting an adapter and hands it down here so an
+ * adapter can expose `ctx.game`/`ctx.roots` to the game it mounts. Absent in
+ * headless harnesses and foreign hosts — everything must keep working when
+ * this is undefined.
+ */
+export interface GameThreeHostContext extends ThreeHostContext<typeof THREE, THREE.WebGLRenderer, AssetCache> {
+  readonly game?: HostGameHandle | undefined;
+}
+
+/** The `canvas`-surface counterpart of {@link GameThreeHostContext}. */
+export interface GameCanvasHostContext extends CanvasHostContext {
+  /** Shared Game root when mounted by the universal multi-root host. */
+  readonly game?: HostGameHandle | undefined;
+}
+
+/**
+ * The `dom`-surface counterpart, typed as the PUBLIC `Game` shell because that
+ * is the weakest promise this surface makes, and deliberately optional: a
+ * sibling mounted beside an ingest root has no native `Game` to hand it.
+ */
+export interface GameDomHostContext extends DomHostContext {
+  readonly game?: Game | undefined;
+}

package/src/runtime/input-router.ts

@@ -0,0 +1,182 @@
+/**
+ * The delegating input router (D5 §2a) —
+ * `createGameRuntime`'s roots path (T6.1 slice 1) uses this to route
+ * pointer input across N stacked world canvases with exactly ONE root
+ * listener.
+ *
+ * Split into two layers so the decision logic is unit-testable with plain
+ * fake roots — no real DOM/canvas needed:
+ *
+ *  - `stackOrder` / `resolveClaimingRoot`: pure functions over
+ *    `{id, zOrder, hitTest?}` — "who claims this point". They live in
+ *    `adapter/root-stacking.ts`, because the EDITOR asks the same question
+ *    at design time with no game running and may not import the runtime.
+ *  - `applyPointerEventsStacking` / `createInputRouter`: this file, the DOM wiring —
+ *    sets `pointer-events` CSS per D5 §2a and forwards a claimed event to
+ *    the claiming world's own canvas.
+ *
+ * Per-event fall-through (D5 §2b — the sanctioned mechanism for an
+ * authoring surface's own interior drag affordances, e.g. a canvas
+ * editor's gizmos) is explicitly NOT this file's job — it stays inside
+ * whatever authoring surface needs it.
+ */
+
+import {
+  type ClaimEntry,
+  resolveClaimingRoot,
+  stackOrder,
+} from '@volter/editor-project/adapter/root-stacking';
+
+/** The DOM-wiring inputs — one real canvas per world. */
+export interface RouterAdapterRoot extends ClaimEntry {
+  readonly canvas: HTMLCanvasElement;
+}
+
+/**
+ * Sets `canvas.style.pointerEvents` per D5 §1/§2a: the bottom (lowest
+ * zOrder) world's canvas is `'auto'` (real user input DOM-hit-tests it by
+ * default); every canvas above it is `'none'` (real user input never
+ * DOM-hit-tests it — the router's JS-level `hitTest` is what still lets it
+ * claim a point via `createInputRouter`'s forwarding).
+ */
+export function applyPointerEventsStacking(entries: readonly RouterAdapterRoot[]): void {
+  const order = stackOrder(entries);
+  order.forEach((entry, i) => {
+    entry.canvas.style.pointerEvents = i === 0 ? 'auto' : 'none';
+  });
+}
+
+const ROUTED_EVENT_TYPES = ['pointerdown', 'pointerup', 'pointermove', 'click', 'wheel'] as const;
+
+/** Common pointer/mouse/wheel event fields this router knows how to carry
+ *  over when forwarding a claimed event to a different canvas (see
+ *  `forwardEvent` below) — not an exhaustive Event surface, just the fields
+ *  games/libraries actually read for hit-testing and input state. */
+function pickEventInit(original: Event): Record<string, unknown> {
+  const src = original as unknown as Record<string, unknown>;
+  const keys = [
+    'clientX',
+    'clientY',
+    'screenX',
+    'screenY',
+    'offsetX',
+    'offsetY',
+    'button',
+    'buttons',
+    'ctrlKey',
+    'altKey',
+    'shiftKey',
+    'metaKey',
+    'pointerId',
+    'pointerType',
+    'pressure',
+    'isPrimary',
+    'deltaX',
+    'deltaY',
+    'deltaZ',
+    'deltaMode',
+  ];
+  const init: Record<string, unknown> = { bubbles: true, cancelable: true, composed: true };
+  for (const key of keys) if (key in src) init[key] = src[key];
+  return init;
+}
+
+/**
+ * Forward `original` onto `canvas` as a NEW event of the same event-type
+ * family — so a canvas with `pointer-events:none` (never a native DOM
+ * hit-test target) still receives the interaction its own event pipeline
+ * (Pixi's `EventSystem`, a raycast-driven three controller, …) listens for.
+ * The clone BUBBLES, because Pixi hears `pointermove` on the document and
+ * `pointerup` on the window, not on its canvas; the container's capture
+ * listener sees every clone on the way down (capture runs whether or not an
+ * event bubbles), and {@link forwarded} is what lets it pass rather than be
+ * routed again. Re-dispatching the SAME event object is not an option (the
+ * DOM forbids re-dispatching an event still being dispatched).
+ *
+ * Best-effort: environments with no `PointerEvent`/`MouseEvent`/
+ * `WheelEvent` global (Node unit tests) skip forwarding silently — those
+ * tests exercise the pure claim-resolution logic above instead, which needs
+ * no real `Event` objects at all.
+ */
+/** The clones this router dispatched: they bubble through the container's capture listener, which
+ *  lets them pass instead of routing them again. */
+const forwarded = new WeakSet<Event>();
+
+function forwardEvent(canvas: HTMLCanvasElement, original: Event): void {
+  const g = globalThis as unknown as {
+    PointerEvent?: new (type: string, init?: unknown) => Event;
+    MouseEvent?: new (type: string, init?: unknown) => Event;
+    WheelEvent?: new (type: string, init?: unknown) => Event;
+  };
+  const Ctor =
+    original.type === 'wheel'
+      ? g.WheelEvent
+      : original.type.startsWith('pointer')
+        ? g.PointerEvent
+        : (g.MouseEvent ?? g.PointerEvent);
+  if (!Ctor || typeof canvas.dispatchEvent !== 'function') return;
+  try {
+    const clone = new Ctor(original.type, pickEventInit(original));
+    forwarded.add(clone);
+    canvas.dispatchEvent(clone);
+  } catch {
+    // Best-effort forwarding — a construction failure here must never break
+    // the (already-delivered) original event's own handling.
+  }
+}
+
+export interface InputRouterHandle {
+  /** Resolve which world claims a container-relative point right now — the
+   *  pure decision, exposed for callers/tests that don't want to simulate a
+   *  real DOM event. */
+  resolveClaim(x: number, y: number): string | null;
+  /** Detach the container listener(s). Idempotent. */
+  dispose(): void;
+}
+
+/**
+ * Wire the delegating router onto `container` for `entries` (D5 §2a): apply
+ * the pointer-events stacking, then attach ONE capture-phase listener per
+ * routed event type that resolves the claiming world and forwards the event
+ * to ITS canvas when that world isn't already the natural DOM target (the
+ * bottom world, whose canvas is the only one with `pointer-events:auto`).
+ */
+export function createInputRouter(
+  container: HTMLElement,
+  entries: readonly RouterAdapterRoot[],
+): InputRouterHandle {
+  applyPointerEventsStacking(entries);
+  const byId = new Map(entries.map((e) => [e.id, e] as const));
+  const bottomId = stackOrder(entries)[0]?.id;
+
+  const handler = (evt: Event) => {
+    if (forwarded.has(evt)) return;
+    const rect = container.getBoundingClientRect?.() ?? { left: 0, top: 0 };
+    const clientX = (evt as unknown as { clientX?: number }).clientX ?? 0;
+    const clientY = (evt as unknown as { clientY?: number }).clientY ?? 0;
+    const x = clientX - rect.left;
+    const y = clientY - rect.top;
+    const claimant = resolveClaimingRoot(entries, x, y);
+    if (claimant && claimant !== bottomId) {
+      const entry = byId.get(claimant);
+      if (entry) {
+        // The claim is exclusive: the world beneath never hears a press its HUD took.
+        evt.stopPropagation();
+        forwardEvent(entry.canvas, evt);
+      }
+    }
+  };
+
+  for (const type of ROUTED_EVENT_TYPES) {
+    container.addEventListener?.(type, handler, true);
+  }
+
+  return {
+    resolveClaim: (x, y) => resolveClaimingRoot(entries, x, y),
+    dispose() {
+      for (const type of ROUTED_EVENT_TYPES) {
+        container.removeEventListener?.(type, handler, true);
+      }
+    },
+  };
+}