@volter/editor-game 0.5.66 → 0.5.67

package/src/runtime/pixi/ingest.ts

@@ -0,0 +1,116 @@
+import type { VisibleCaptureWindow } from '@volter/threejs-runtime/adapter/ingest/visible-capture-window';
+import {
+  type CapturedRuntime2D,
+  installSceneCapture2D,
+  type SceneCapture2DHandle,
+} from './scene-capture';
+
+/** A registered unmodified PixiJS game (the Pixi analog of `IngestGame`). */
+export interface IngestGame2D {
+  id: string;
+  name: string;
+  description: string;
+  /** Import + run the unmodified game module in the host's own realm. */
+  load: () => Promise<unknown>;
+  /** How long to wait for the game's first captured frame before failing. */
+  captureTimeoutMs?: number;
+}
+
+/**
+ * The game's own modules failed to load or run — a DIFFERENT defect from
+ * "loaded, but the host's pixi never saw a frame", and named so a caller can
+ * tell them apart.
+ *
+ * Both used to arrive as a bare `Error`, so `mount-canvas-ingest-root.ts`'s
+ * one catch reported a module that 404'd, threw, or failed to transform in
+ * the capture trap's words — "the host's pixi captured no frame ... or it
+ * bundles its own (un-shared) copy of pixi.js". That sentence sends the
+ * reader to the wrong file: it describes a module-identity problem, and the
+ * measured cause was a JSX-bearing `.js` module the packaged host had no
+ * transform for.
+ *
+ * Classified by `name` ({@link INGEST_GAME_2D_LOAD_ERROR_NAME}) rather than
+ * `instanceof` — under the packaged runtime the editor shell and the project
+ * graph can hold different instances of a module, and this whole lane exists
+ * because of that; a discriminator that silently flips when the class object
+ * differs is the wrong tool for saying which failure happened.
+ */
+export const INGEST_GAME_2D_LOAD_ERROR_NAME = 'IngestGame2DLoadError';
+
+export class IngestGame2DLoadError extends Error {
+  constructor(gameId: string, cause: unknown) {
+    super(`pixi ingest: game "${gameId}" failed to load: ${cause}`, { cause });
+    this.name = INGEST_GAME_2D_LOAD_ERROR_NAME;
+  }
+}
+
+export interface IngestMount2D {
+  /** The captured live stage Container. */
+  stage: unknown;
+  capture: SceneCapture2DHandle;
+  setPaused(paused: boolean): void;
+  dispose(): void;
+}
+
+/**
+ * Mount an UNMODIFIED PixiJS game via the shared-instance capture path — the 2D
+ * analog of `mountIngestGame`. Installs the render trap on the host's pixi
+ * instance, runs the game's `load()`, waits for the game to render its first
+ * frame (capturing its live stage), and exposes loop gating + cleanup. A game
+ * whose pixi the trap cannot reach never captures, and the mount FAILS by name.
+ *
+ * `onWait` is the three lane's own seam (`ingest-root-adapter.ts` passes
+ * `setCaptureWait`): the capture window PARKS while the tab is hidden, and a
+ * parked wait is otherwise indistinguishable from a hung mount at every door.
+ * Threading it here is what lets `vgai status` say "waiting for the first
+ * visible frame — the tab is hidden" over a canvas ingest too.
+ */
+export async function mountIngestGame2D(
+  pixiNamespace: unknown,
+  game: IngestGame2D,
+  opts: {
+    captureTimeoutMs?: number;
+    onWait?: (wait: VisibleCaptureWindow | null) => void;
+    acceptCapture?: (runtime: CapturedRuntime2D) => boolean;
+    /**
+     * Called after the entry has run, before spending the Pixi capture budget.
+     * A canvas host with other structural adapters can answer true once one of
+     * those runtimes is ready; `null` then means "dispatch that runtime" rather
+     * than "Pixi failed".
+     */
+    preferStructuralRuntime?: () => boolean | Promise<boolean>;
+  } = {},
+): Promise<IngestMount2D | null> {
+  const capture = installSceneCapture2D(pixiNamespace, {
+    ...(opts.acceptCapture ? { accept: opts.acceptCapture } : {}),
+  });
+  try {
+    await game.load();
+    if (await opts.preferStructuralRuntime?.()) {
+      capture.uninstall();
+      return null;
+    }
+  } catch (err) {
+    capture.uninstall();
+    throw new IngestGame2DLoadError(game.id, err);
+  }
+
+  const timeout = opts.captureTimeoutMs ?? game.captureTimeoutMs ?? 8000;
+  try {
+    const rt = await capture.waitForCapture({
+      timeoutMs: timeout,
+      ...(opts.onWait ? { onWait: opts.onWait } : {}),
+    });
+    return {
+      stage: rt.stage,
+      capture,
+      setPaused: (p) => capture.setPaused(p),
+      dispose: () => capture.uninstall(),
+    };
+  } catch (err) {
+    capture.uninstall();
+    throw new Error(
+      `pixi ingest: game "${game.id}" rendered no capturable frame within ${timeout}ms: ${err}`,
+    );
+  }
+}

package/src/runtime/pixi/physics-registry.ts

@@ -0,0 +1,49 @@
+import type RAPIER from '@dimforge/rapier2d-compat';
+import type { Container } from 'pixi.js';
+
+/** The Rapier 2D handles owned by a single display-object entity. */
+export interface Physics2DRefs {
+  body: RAPIER.RigidBody;
+  collider: RAPIER.Collider;
+}
+
+/**
+ * Maps PixiJS display objects to their Rapier 2D bodies/colliders and back —
+ * the Pixi analog of `PhysicsRegistry`. Two indexes:
+ *  - `Container → {body, collider}` for the postPhysics transform writer.
+ *  - `colliderHandle → Container` reverse index for collision/trigger dispatch.
+ */
+export function createPhysics2DRegistry() {
+  const byObject = new Map<Container, Physics2DRefs>();
+  const byColliderHandle = new Map<number, Container>();
+
+  return {
+    add(display: Container, body: RAPIER.RigidBody, collider: RAPIER.Collider): void {
+      byObject.set(display, { body, collider });
+      byColliderHandle.set(collider.handle, display);
+    },
+    get(display: Container): Physics2DRefs | undefined {
+      return byObject.get(display);
+    },
+    getByColliderHandle(handle: number): Container | undefined {
+      return byColliderHandle.get(handle);
+    },
+    remove(display: Container): void {
+      const refs = byObject.get(display);
+      if (refs) byColliderHandle.delete(refs.collider.handle);
+      byObject.delete(display);
+    },
+    entries(): IterableIterator<[Container, Physics2DRefs]> {
+      return byObject.entries();
+    },
+    get size(): number {
+      return byObject.size;
+    },
+    clear(): void {
+      byObject.clear();
+      byColliderHandle.clear();
+    },
+  };
+}
+
+export type Physics2DRegistry = ReturnType<typeof createPhysics2DRegistry>;

package/src/runtime/pixi/render-pass-bracket.ts

@@ -0,0 +1,117 @@
+/**
+ * The render-pass BRACKET on the Pixi surface — the canvas-substrate answer to
+ * the question the three lane answers with the render accessor-trap's
+ * `setRenderPassHooks` (`adapter/ingest/scene-capture.ts`): *when does this
+ * renderer's pass begin and end?*
+ *
+ * ## Why the renderer's own runners, and not another wrap
+ *
+ * Pixi's `AbstractRenderer.render()` emits five runners in a fixed order —
+ * `prerender → renderStart → render → renderEnd → postrender` (verified in the
+ * installed pixi.js 8.19,
+ * `rendering/renderers/shared/system/AbstractRenderer.mjs`). EVERY GL draw the
+ * pass issues happens between the first and the last: the batcher draws under
+ * `render`, and even the back-buffer blit, the one draw that is easy to miss,
+ * runs under `renderStart`/`renderEnd` (`gl/GlBackBufferSystem.mjs`). So a
+ * listener added to `prerender` and `postrender` brackets the whole pass using
+ * the renderer's OWN published seam — no instance shadowing, no prototype
+ * patch, no ordering assumption beyond the one Pixi itself guarantees.
+ *
+ * `SystemRunner.add(item)` binds by METHOD NAME (`item[runnerName]` must
+ * exist) and `remove(item)` takes it back off, so installing and uninstalling
+ * is symmetric and touches nothing else on the renderer.
+ *
+ * ## Honest absence
+ *
+ * A renderer that publishes no such runners is not bracketed by guesswork:
+ * this returns `null`, and the caller treats that exactly like a missing
+ * WebGL2 context — the capability is absent, never faked.
+ */
+
+import type { RenderPassHooks } from '@volter/threejs-runtime/adapter/ingest/scene-capture';
+
+/** The slice of a Pixi renderer this reads — structural, so a headless test
+ *  hands in a plain object with two runners and nothing else. */
+interface RunnerLike {
+  add(item: unknown): unknown;
+  remove(item: unknown): unknown;
+}
+
+interface RendererWithRunners {
+  runners?: {
+    prerender?: RunnerLike;
+    postrender?: RunnerLike;
+  };
+}
+
+function runnerPair(renderer: unknown): { pre: RunnerLike; post: RunnerLike } | null {
+  if (!renderer || typeof renderer !== 'object') return null;
+  const runners = (renderer as RendererWithRunners).runners;
+  const pre = runners?.prerender;
+  const post = runners?.postrender;
+  if (!pre || typeof pre.add !== 'function' || typeof pre.remove !== 'function') return null;
+  if (!post || typeof post.add !== 'function' || typeof post.remove !== 'function') return null;
+  return { pre, post };
+}
+
+/**
+ * Bracket a Pixi renderer's render pass with `hooks.before`/`hooks.after`.
+ *
+ * Returns the uninstall function, or `null` when this renderer publishes no
+ * `prerender`/`postrender` runners — the honest "cannot bracket this", which
+ * the caller reads as "no render-debug capability here".
+ *
+ * Neither hook may throw — the same contract the three lane's `RenderPassHooks`
+ * carries, and for a sharper reason here: these run as listeners on the
+ * renderer's own runners, so a throwing `before` aborts the game's frame AND
+ * skips the `postrender` emit that would have closed the pass. The assembly
+ * point (`ingest/ingest-render-debug.ts`) is where that contract is kept.
+ */
+export function installPixiRenderPassBracket(
+  renderer: unknown,
+  hooks: RenderPassHooks,
+): (() => void) | null {
+  const pair = runnerPair(renderer);
+  if (!pair) return null;
+
+  // One object per runner: `SystemRunner.add` binds by method name, so the
+  // `prerender` listener and the `postrender` listener cannot be the same
+  // object unless it answers to both — keeping them separate makes each
+  // `remove()` exact.
+  const preListener = {
+    prerender() {
+      hooks.before();
+    },
+  };
+  const postListener = {
+    postrender() {
+      hooks.after();
+    },
+  };
+
+  pair.pre.add(preListener);
+  pair.post.add(postListener);
+
+  let uninstalled = false;
+  return () => {
+    if (uninstalled) return;
+    uninstalled = true;
+    pair.pre.remove(preListener);
+    pair.post.remove(postListener);
+  };
+}
+
+/**
+ * The captured Pixi renderer's real WebGL2 context, or `undefined`.
+ *
+ * `WebGLRenderer.gl` is the renderer's own published field — `GlContextSystem`
+ * assigns it (`this._renderer.gl = gl`,
+ * `rendering/renderers/gl/context/GlContextSystem.mjs`) as part of
+ * initialisation, and `WebGLRenderer.d.ts` declares it. A WebGPU renderer, or
+ * a renderer that has not initialised a context, simply has none — which is the
+ * answer, not an error.
+ */
+export function pixiRenderingContext(renderer: unknown): unknown {
+  if (!renderer || typeof renderer !== 'object') return undefined;
+  return (renderer as { gl?: unknown }).gl;
+}

package/src/runtime/pixi/scene-capture.ts

@@ -0,0 +1,179 @@
+/**
+ * Scene capture for the Pixi surface — the PixiJS analog of the three.js render
+ * accessor-trap (`adapter/ingest/scene-capture.ts`).
+ *
+ * An unmodified PixiJS game owns its own `Application`, `stage`, renderer, and
+ * ticker. To inspect/host that live scene with ZERO edits to the game, we trap the
+ * render call and capture the game's `stage` + renderer + app on its first frame.
+ *
+ * Unlike three.js's `WebGLRenderer` (whose `render` is an own-instance property,
+ * forcing a prototype getter/setter), PixiJS's `Application.prototype.render` is a
+ * normal prototype method — the standard ticker render path (`ticker → app.render()`)
+ * goes through it — so a direct prototype wrap suffices.
+ *
+ * CRITICAL (same module-identity gatekeeper as the 3D path): the trap must be
+ * installed on the SAME `pixi.js` module instance the game uses. A bundler/dev-server
+ * that dedupes `pixi.js` makes an ESM game's `import 'pixi.js'` resolve to the host
+ * instance, so it is trapped; a game bundling its own pixi cannot be captured at
+ * all, and its mount fails by name.
+ */
+
+import {
+  type CaptureWaitOptions,
+  documentVisibilityClock,
+  startVisibleCaptureWindow,
+} from '@volter/threejs-runtime/adapter/ingest/visible-capture-window';
+
+/**
+ * Options for {@link SceneCapture2DHandle.waitForCapture} — the WAIT's options,
+ * not this lane's, so they carry no `2D` suffix and are not declared here.
+ * They configure `visible-capture-window.ts`'s window, which both surfaces
+ * share; this lane used to restate them field-for-field under a `2D` name.
+ * The suffix marks what a surface genuinely owns
+ * ({@link CapturedRuntime2D} is a Pixi stage/renderer/app, and stays), and a
+ * budget of visible milliseconds is not that. Passing a bare number is
+ * `{ timeoutMs }`, which is what every existing caller does.
+ */
+export type { CaptureWaitOptions };
+
+/** A live Pixi runtime captured from an external PixiJS game. */
+export interface CapturedRuntime2D {
+  /** The game's root stage Container. */
+  stage: unknown;
+  /** The game's PixiJS renderer. */
+  renderer: unknown;
+  /** The game's Application (so the host can pause/resume its ticker). */
+  app: unknown;
+}
+
+export interface SceneCapture2DHandle {
+  readonly captured: CapturedRuntime2D | null;
+  /**
+   * Resolve once the game's stage is captured.
+   *
+   * The timeout is a budget of **VISIBLE** time, not wall-clock time — the same
+   * rule the three lane has had since `visible-capture-window.ts`, and for the
+   * same measured reason: a hidden document cannot render (the browser parks
+   * rAF), so counting hidden time against the game counts time it was not
+   * allowed to use. MEASURED on the bubbo-bubbo ingest with a plain
+   * `setTimeout` here: the mount succeeded when the auto-opened tab happened to
+   * be in front and died terminally 8s later when it was behind — "canvas
+   * ingest: game … rendered no capturable frame", with foregrounding the tab
+   * afterwards changing nothing. The normal HUMAN path is the backgrounded one.
+   *
+   * So the wait PARKS while hidden, the trap stays installed, and the first
+   * frame the tab draws after it comes forward is trapped exactly as it would
+   * have been at boot. Rejects only when the window is spent while VISIBLE.
+   */
+  waitForCapture(options?: number | CaptureWaitOptions): Promise<CapturedRuntime2D>;
+  getDrawCount(): number;
+  /** Pause/resume the captured game's own ticker (loop-host gating). */
+  setPaused(paused: boolean): void;
+  uninstall(): void;
+}
+
+interface PixiLike {
+  Application: { prototype: Record<string, unknown> };
+}
+
+export interface SceneCapture2DOptions {
+  /**
+   * Select the runtime owned by this mount when other Pixi Applications share
+   * the page (for example editor prefab previews). Rejected draws still count,
+   * but cannot satisfy {@link SceneCapture2DHandle.waitForCapture}.
+   */
+  accept?: ((runtime: CapturedRuntime2D) => boolean) | undefined;
+}
+
+/**
+ * Install the render trap on `pixiNamespace.Application.prototype.render`. Pass the
+ * host's `pixi.js` namespace so a shared-instance game is trapped. Install once per
+ * ingest session; `uninstall()` on teardown.
+ */
+export function installSceneCapture2D(
+  pixiNamespace: unknown,
+  options: SceneCapture2DOptions = {},
+): SceneCapture2DHandle {
+  const PIXI = pixiNamespace as PixiLike;
+  const proto = PIXI.Application.prototype;
+
+  let captured: CapturedRuntime2D | null = null;
+  let drawCount = 0;
+  const waiters: Array<(rt: CapturedRuntime2D) => void> = [];
+
+  const priorRender = Object.getOwnPropertyDescriptor(proto, 'render');
+  const realRender = proto['render'] as ((...a: unknown[]) => unknown) | undefined;
+
+  Object.defineProperty(proto, 'render', {
+    configurable: true,
+    writable: true,
+    value: function (this: Record<string, unknown>, ...args: unknown[]) {
+      drawCount++;
+      const stage = this['stage'];
+      if (!captured && stage) {
+        const candidate = { stage, renderer: this['renderer'], app: this };
+        if (options.accept?.(candidate) ?? true) {
+          captured = candidate;
+          for (const resolve of waiters.splice(0)) resolve(captured);
+        }
+      }
+      return realRender?.apply(this, args);
+    },
+  });
+
+  return {
+    get captured() {
+      return captured;
+    },
+    getDrawCount() {
+      return drawCount;
+    },
+    setPaused(paused: boolean) {
+      const app = captured?.app as { ticker?: { start(): void; stop(): void } } | undefined;
+      if (!app?.ticker) return;
+      if (paused) app.ticker.stop();
+      else app.ticker.start();
+    },
+    waitForCapture(options) {
+      const opts: CaptureWaitOptions =
+        typeof options === 'number' ? { timeoutMs: options } : (options ?? {});
+      const timeoutMs = opts.timeoutMs ?? 10_000;
+      if (captured) return Promise.resolve(captured);
+      return new Promise<CapturedRuntime2D>((resolve, reject) => {
+        const captureWindow = startVisibleCaptureWindow({
+          budgetMs: timeoutMs,
+          clock: opts.visibility ?? documentVisibilityClock(),
+          onExpire: () => {
+            const i = waiters.indexOf(wrapped);
+            if (i >= 0) waiters.splice(i, 1);
+            opts.onWait?.(null);
+            reject(
+              new Error(
+                `pixi scene capture timed out after ${timeoutMs}ms of VISIBLE time ` +
+                  `(${Math.round(captureWindow.elapsedHiddenMs())}ms browser-suspended, which is ` +
+                  'not counted because no frame can be presented) — the game never rendered, or it bundles its own ' +
+                  '(un-shared) copy of pixi.js.',
+              ),
+            );
+          },
+        });
+        const wrapped = (rt: CapturedRuntime2D) => {
+          captureWindow.cancel();
+          opts.onWait?.(null);
+          resolve(rt);
+        };
+        waiters.push(wrapped);
+        opts.onWait?.(captureWindow);
+      });
+    },
+    uninstall() {
+      if (priorRender) Object.defineProperty(proto, 'render', priorRender);
+      else if (realRender)
+        Object.defineProperty(proto, 'render', {
+          configurable: true,
+          writable: true,
+          value: realRender,
+        });
+    },
+  };
+}

package/src/runtime/pixi/system-adapters.ts

@@ -0,0 +1,69 @@
+import type { PhysicsAdapter2D as PhysicsAdapter2DSeam } from '@volter/editor-project/adapter/physics-adapter-2d';
+import type { Container } from 'pixi.js';
+import type { Physics2DRegistry } from './physics-registry';
+
+/** The canvas physics seam, keyed by Pixi's display object. */
+export type PhysicsAdapter2D = PhysicsAdapter2DSeam<Container>;
+
+export function createPhysicsAdapter2D(physics: Physics2DRegistry): PhysicsAdapter2D {
+  // Remember each frozen body's prior type so unfreeze restores it.
+  const frozen = new WeakMap<Container, number>();
+  return {
+    keyedBy: 'display',
+    ownerOf(display) {
+      const refs = physics.get(display);
+      if (!refs) return 'none';
+      return refs.body.isDynamic() || refs.body.isKinematic() ? 'physics' : 'none';
+    },
+    freeze(display) {
+      const refs = physics.get(display);
+      if (!refs) return;
+      frozen.set(display, refs.body.bodyType());
+      // Kinematic-position bodies hold a pose without being driven by forces.
+      refs.body.setBodyType(2 /* KinematicPositionBased */, true);
+    },
+    commit(display, position, rotation) {
+      const refs = physics.get(display);
+      if (!refs) return;
+      refs.body.setTranslation({ x: position[0], y: position[1] }, true);
+      refs.body.setRotation(rotation, true);
+    },
+    unfreeze(display) {
+      const refs = physics.get(display);
+      if (!refs) return;
+      const prior = frozen.get(display);
+      if (prior !== undefined) {
+        refs.body.setBodyType(prior, true);
+        frozen.delete(display);
+      }
+    },
+  };
+}
+
+/**
+ * ONE carrier over several, each owning a DIFFERENT set of display objects.
+ *
+ * The canvas ingest mount is the case: the host always builds a registry-backed
+ * carrier for objects the editor itself created, and an ingested game may ALSO
+ * declare one over its own simulation's objects. Neither is a superset of the
+ * other and neither can answer for the other's objects, so the composition is
+ * ownership-routed rather than layered — `ownerOf` asks each in order and the
+ * FIRST to claim the object handles every other call for it. A display object
+ * nobody claims answers `'none'` and the freeze/commit/unfreeze trio no-ops,
+ * which is exactly what a single unclaiming carrier already does.
+ *
+ * Order is precedence: earlier carriers win a (never-expected) double claim,
+ * so the caller states its own preference instead of this function inventing
+ * one.
+ */
+export function composePhysicsAdapters2D(carriers: readonly PhysicsAdapter2D[]): PhysicsAdapter2D {
+  const ownerFor = (display: Container): PhysicsAdapter2D | null =>
+    carriers.find((carrier) => carrier.ownerOf(display) === 'physics') ?? null;
+  return {
+    keyedBy: 'display',
+    ownerOf: (display) => (ownerFor(display) ? 'physics' : 'none'),
+    freeze: (display) => ownerFor(display)?.freeze(display),
+    commit: (display, position, rotation) => ownerFor(display)?.commit(display, position, rotation),
+    unfreeze: (display) => ownerFor(display)?.unfreeze(display),
+  };
+}

package/src/runtime/playtest.ts

@@ -0,0 +1,22 @@
+/**
+ * WHO IS PLAYING, and under what identity — the host's own declaration for one
+ * private play run or coordinated team test.
+ *
+ * Its own module because it is a PUBLISHED path: a project's Colyseus
+ * networking adapter (the `colyseus` capability, copied into every game) names
+ * this type, so it must live somewhere that survives. The engine never joins a
+ * room and never couples this authoring identity to a networking library —
+ * games may pass `roomKey` as a Colyseus filter/join option, and that is the
+ * whole of the coupling.
+ */
+
+/** Host-supplied identity for one private play run or coordinated team test.
+ * Games may pass `roomKey` as a Colyseus filter/join option; the engine never
+ * joins a room or couples this authoring identity to a networking library. */
+export interface PlaytestContext {
+  readonly mode: 'private' | 'team';
+  readonly id: string;
+  readonly roomKey: string;
+  readonly revision: number | null;
+  readonly participantId: string | null;
+}