@vgai/engine 0.2.0

package/src/world2d/pixi-game-adapter.ts

@@ -0,0 +1,325 @@
+import RAPIER from '@dimforge/rapier2d-compat';
+import type { Container } from 'pixi.js';
+import type { MountedPixiWorld } from '../adapter/game-adapter';
+import { createAssetCache } from '../assets';
+import { createGameLoop } from '../core/game-loop';
+import { createSystemRunner } from '../core/system-runner';
+import { createComponentManager } from '../ecs/component-manager';
+import {
+  createGame,
+  createWorldInstance,
+  type GameInternal,
+  type WorldFrameHooks,
+} from '../runtime/game';
+import type { GameContext } from '../runtime/types';
+import { createCollision2DSystem, createTriggerDispatch2D } from './collision-2d';
+import { createPhysics2DRegistry } from './physics2d-registry';
+import { createPixiSurface, type PixiSurface } from './pixi-surface';
+import { loadScene2DFromData, type Scene2DInstance } from './scene2d-loader';
+import type { Scene2DFile } from './schema/entity2d';
+import { createTransformWriter2D } from './transform-writer-2d';
+import type { Component2DRegistry, World2DContext } from './types';
+
+/** Minimal host surface for world2d (the stacked-own-root model from the spec). */
+export interface World2DHost {
+  canvas: HTMLCanvasElement;
+  width: number;
+  height: number;
+  /** Screen-space React/HUD overlay container. */
+  ui?: HTMLDivElement;
+  /** DPR override (T6.1 slice 1, COMPOSITION-DESIGN.md D5 §3 — "one DPR
+   *  everywhere"): the worlds-path host computes ONE dpr for every stacked
+   *  surface and passes it here; omitted -> `createPixiSurface`'s own
+   *  default (`window.devicePixelRatio`, uncapped) — today's behavior. */
+  dpr?: number;
+  /** This world is stacked ABOVE another world (D5 §1): clear with alpha 0
+   *  instead of an opaque background so the layer below shows through. */
+  transparent?: boolean;
+  /** Capture tier cost (D5 §4) — see `PixiSurfaceOptions.preserveDrawingBuffer`. */
+  preserveDrawingBuffer?: boolean;
+}
+
+/** A world2d setup function — build the scene from the context, return cleanup. */
+export type World2DSetupFn = (
+  ctx: World2DContext,
+) => Promise<{ dispose: () => void }> | { dispose: () => void };
+
+/**
+ * MountedGame for world2d — the pixi peer of the 3D `MountedThreeWorld`,
+ * satisfying `MountedPixiWorld` (`adapter/game-adapter.ts`, T7.5) via `kind`/
+ * `stage` so a `WorldInstance` built from this mount needs no cast through
+ * the generic `MountedWorld` union. `scene`/`camera` (both the SAME `Container`
+ * as `stage`) are kept as extra fields for pre-T7.5 call sites/tests that
+ * already read them — `stage` is the canonical name going forward.
+ */
+export interface MountedGame2D extends MountedPixiWorld {
+  /** First-party brand (T7.3 slice 2 — closes the gap `adapter/vgai-scene-
+   *  game-adapter.ts`'s `VgaiMountedGame.firstParty` doc flagged as a "T7.3
+   *  lookahead"): `runtime/game.ts`'s `isFirstPartyMounted` brand-checks
+   *  this literal, NOT a structural `'ctx' in mounted` probe (this mount's
+   *  `ctx` is a `World2DContext`, unrelated to `GameContext`). Without this,
+   *  a pixijs `WorldInstance` is silently skipped by every first-party-only
+   *  Game feature — `Game.queryByComponent` in particular, the T7.3 AC
+   *  (`test/game-three-plus-pixi.test.ts`). */
+  readonly firstParty: true;
+  /** Pre-T7.5 field names, kept for compatibility — both alias `stage`
+   *  (pixi has no separate camera concept; `MountedGame2D.mount` always sets
+   *  `scene === camera === stage`). */
+  readonly scene: Container;
+  readonly camera: Container;
+  readonly ctx: World2DContext;
+  update?(dt: number): void;
+  resize?(width: number, height: number): void;
+  dispose(): void;
+  /** Phase-partitioned frame entry point (T7.3 slice 1) — the pixi analog of
+   *  `VgaiMountedGame.frame` (`adapter/vgai-scene-game-adapter.ts`). Delegates
+   *  to this mount's own `SystemRunner`, so a `WorldInstance` built from this
+   *  mount ticks it through `Game.runFrame` instead of a standalone loop. */
+  readonly frame?: WorldFrameHooks;
+}
+
+export interface PixiSceneConfig {
+  /** A world2d scene file to load (declarative path). */
+  sceneData?: Scene2DFile;
+  /** A setup function (imperative path) — mutually exclusive with sceneData. */
+  setup?: World2DSetupFn;
+  /** Component registry the scene's `components` reference. */
+  registry?: Component2DRegistry;
+  id?: string;
+}
+
+/**
+ * The first-party implementer that mounts an authored world2d scene — the 2D
+ * analog of `VgaiSceneGameAdapter`. It builds the Pixi surface + Rapier 2D world,
+ * registers the engine systems into the shared phase runner, loads the scene (or
+ * runs a setup), and returns a `MountedGame2D`.
+ */
+export class PixiSceneGameAdapter {
+  readonly id: string;
+  constructor(private readonly config: PixiSceneConfig = {}) {
+    this.id = config.id ?? 'pixi-scene';
+  }
+
+  async mount(host: World2DHost): Promise<MountedGame2D> {
+    const { sceneData, setup, registry = {} } = this.config;
+
+    // --- Pixi surface (autoStart:false; engine loop drives render) ---
+    const surface: PixiSurface = await createPixiSurface({
+      canvas: host.canvas,
+      width: host.width,
+      height: host.height,
+      ...(sceneData?.background ? { background: sceneData.background } : {}),
+      // T6.1 slice 1 (worlds-path host hints — see `World2DHost`'s fields):
+      // all optional, all no-ops when the host is the legacy
+      // `createWorld2DRuntime` entry (which never sets them), so behavior
+      // there is unchanged.
+      ...(host.dpr !== undefined ? { resolution: host.dpr } : {}),
+      ...(host.transparent ? { transparent: true } : {}),
+      ...(host.preserveDrawingBuffer ? { preserveDrawingBuffer: true } : {}),
+    });
+
+    // --- Rapier 2D world (separate from the 3D world) ---
+    await RAPIER.init();
+    const gravity = sceneData?.gravity ?? [0, 980];
+    const rapier2dWorld = new RAPIER.World({ x: gravity[0], y: gravity[1] });
+    const eventQueue = new RAPIER.EventQueue(true);
+
+    const physics2d = createPhysics2DRegistry();
+    const writeTransforms2D = createTransformWriter2D(physics2d);
+    const collisions2d = createCollision2DSystem(rapier2dWorld, eventQueue);
+
+    const systems = createSystemRunner();
+    systems.add('physics', () => rapier2dWorld.step(eventQueue));
+    systems.add('postPhysics', () => {
+      collisions2d.drain();
+      writeTransforms2D();
+    });
+    systems.add('render', () => surface.render());
+
+    const uiContainer = host.ui ?? document.createElement('div');
+
+    const ctx: World2DContext = {
+      app: surface.app,
+      stage: surface.world,
+      rapier2dWorld,
+      rapier2d: RAPIER,
+      physics2d,
+      collisions2d,
+      components: null!,
+      systems,
+      uiContainer,
+    };
+
+    // T7.3 slice 1/2: the pixi world's components attach onto the SAME
+    // unified `ComponentManager` (`ecs/component-manager.ts`) the threejs
+    // path uses, constructed for kind `'pixijs'` — the world2d-silo manager
+    // is deleted (T7.3 slice 2). `ctx` is cast to `GameContext` for the
+    // manager's internal typing only: at runtime this object IS the real
+    // `World2DContext` above, so `GameComponent<'pixijs'>` subclasses that
+    // need real 2D ctx fields (e.g. `Camera2DFollow`, which widens its own
+    // `update`'s ctx param to `GameContext | World2DContext` and narrows
+    // back down) still receive their real ctx, unchanged behavior — the
+    // same cast `test/mirror-tree-guard.test.ts` uses for its unit-level
+    // pixi manager. `createComponentManager`'s positional `physics`
+    // parameter (the 3D `PhysicsRegistry`) is optional (T7.3 slice 2) and
+    // omitted here — a `'pixijs'`-kind manager never reads it (rigidBody/
+    // collider resolve from `physics2d` instead — see `resolvePhysicsRefs`
+    // in `ecs/component-manager.ts`).
+    ctx.components = createComponentManager(ctx as unknown as GameContext, undefined, {
+      kind: 'pixijs',
+      physics2d,
+    });
+    collisions2d.onCollision(
+      createTriggerDispatch2D(
+        physics2d,
+        ctx.components,
+        rapier2dWorld,
+        ctx as unknown as GameContext,
+      ),
+    );
+
+    // --- Load scene or run setup ---
+    let sceneInstance: Scene2DInstance | null = null;
+    let cleanup: { dispose: () => void } | null = null;
+    if (sceneData) {
+      sceneInstance = await loadScene2DFromData(sceneData, ctx, registry);
+    } else if (setup) {
+      cleanup = await setup(ctx);
+    }
+
+    return {
+      kind: 'pixijs',
+      firstParty: true,
+      stage: surface.world,
+      scene: surface.world,
+      camera: surface.world,
+      drivesOwnLoop: false,
+      ctx,
+      update: (dt: number) => systems.run(dt),
+      resize: (w: number, h: number) => surface.resize(w, h),
+      // T7.3 slice 1: no `endFrame` hook — world2d has no per-substep
+      // post-phase work today (no `input.endFrame()` analog; HUD input is
+      // plain DOM events, not routed through an engine InputManager).
+      frame: {
+        runPhase: (phase, dt) => systems.runPhase(phase, dt),
+      },
+      dispose: () => {
+        cleanup?.dispose();
+        sceneInstance?.dispose();
+        ctx.components.clear();
+        physics2d.clear();
+        rapier2dWorld.free();
+        eventQueue.free();
+        surface.dispose();
+      },
+    };
+  }
+}
+
+/** Handle returned by {@link createWorld2DRuntime}. */
+export interface World2DSession {
+  stop(): void;
+  pause(): void;
+  resume(): void;
+  /** Advance exactly one fixed substep — the pixi analog of
+   *  `GameSession.step()` (`runtime/create-runtime.ts`), delegating to the
+   *  same `Game.play.step()` (D10, T7.6). */
+  step(): void;
+  resize(width: number, height: number): void;
+  readonly mounted: MountedGame2D;
+}
+
+/**
+ * Host entry for world2d — the sibling of `createGameRuntime`, kept separate so the
+ * proven THREE host/interfaces are untouched (the stacked-own-root option the spec's
+ * surface-host-backend-neutral allows). Owns the canvas and constructs a real `Game`
+ * (T7.3 slice 1) with exactly one `'pixijs'`-kind `WorldInstance`, driven each fixed
+ * substep through `Game.runFrame` — the world2d analog of `createGameRuntime`'s
+ * `registerDefaultThreeWorld` (`runtime/create-runtime.ts`). Before T7.3 this ran its
+ * own standalone `createGameLoop` calling `mounted.update` directly; that loop is
+ * retired here in favor of one shared frame executor per game root.
+ */
+export async function createWorld2DRuntime(
+  config: PixiSceneConfig & World2DHost,
+): Promise<World2DSession> {
+  const { canvas, width, height, ui, ...sceneConfig } = config;
+  const adapter = new PixiSceneGameAdapter(sceneConfig);
+  const mounted = await adapter.mount({ canvas, width, height, ...(ui ? { ui } : {}) });
+
+  const assets = createAssetCache();
+  // `game` is referenced here before its `const` below only textually — this
+  // closure isn't invoked until `loop.start()`, well after `game` exists
+  // (same forward-reference pattern `create-runtime.ts` uses).
+  const loop = createGameLoop({
+    fixedTimestep: 1 / 60,
+    maxSubSteps: 8,
+    update: (dt) => {
+      game.runFrame(dt);
+    },
+  });
+  const game: GameInternal = createGame({ loop, assets });
+
+  // T7.5: `mounted` (a `MountedGame2D`, extending `MountedPixiWorld`) and
+  // `adapter` (this `PixiSceneGameAdapter`, satisfying `WorldInstance.adapter`'s
+  // minimal `AdapterHandle` shape — see that field's doc comment in
+  // `runtime/game.ts`) now pass through with ZERO cast — previously this cast
+  // through `GameAdapter`/`MountedGame`, which hardwired THREE `scene`/`camera`.
+  const pixiWorld = createWorldInstance({
+    id: 'main',
+    kind: 'pixijs',
+    adapter,
+    mounted,
+    stage: mounted.stage,
+    physics2d: mounted.ctx.physics2d,
+    collisions2d: mounted.ctx.collisions2d,
+    frame: mounted.frame,
+  });
+  // T7.2/T7.3 world-wiring backfill (mirrors `registerThreeWorld` in
+  // `create-runtime.ts`): scene-authored components attach DURING `mount()`,
+  // before this `WorldInstance` exists, so `instance.world` is left
+  // `undefined` for each of them — `adoptWorld` backfills it now, once, for
+  // every already-attached instance still missing a world.
+  mounted.ctx.components.adoptWorld(pixiWorld);
+  game.registerWorld(pixiWorld);
+
+  loop.start();
+
+  if (typeof window !== 'undefined' && import.meta.env?.DEV) {
+    (window as unknown as Record<string, unknown>)['__vgaiWorld2d'] = {
+      app: mounted.ctx.app,
+      stage: mounted.stage,
+      physics2d: mounted.ctx.physics2d,
+    };
+  }
+
+  return {
+    stop() {
+      loop.stop();
+      mounted.dispose();
+    },
+    // D10/T7.6: route through the real `Game.play` control surface instead of
+    // `loop.timeScale = 0/1` — that starved the accumulator entirely (per D1,
+    // zero substeps ⇒ zero renders too), the exact bug this control surface
+    // replaces. `Game.play.pause()` freezes this world's simulation (it is
+    // `pausable` by default) while its `render` phase keeps running every
+    // substep — the screen does not go black while paused.
+    pause() {
+      game.play.pause();
+    },
+    resume() {
+      game.play.resume();
+    },
+    step() {
+      game.play.step();
+    },
+    resize(w: number, h: number) {
+      // T7.5/T7.6 own real per-world resize routing through the Game/host
+      // surface split (the host is not yet surface-neutral for world2d) —
+      // kept as today's direct host→surface call for this slice.
+      mounted.resize?.(w, h);
+    },
+    get mounted() {
+      return mounted;
+    },
+  };
+}

package/src/world2d/pixi-surface.ts

@@ -0,0 +1,78 @@
+import { Application, Container } from 'pixi.js';
+
+export interface PixiSurface {
+  app: Application;
+  /** The world container (the 2D "camera": pan/zoom by transforming this). */
+  world: Container;
+  /** Render one frame (called from the engine's `render` phase). */
+  render: () => void;
+  resize: (width: number, height: number) => void;
+  dispose: () => void;
+}
+
+export interface PixiSurfaceOptions {
+  canvas: HTMLCanvasElement;
+  width: number;
+  height: number;
+  background?: string;
+  resolution?: number;
+  antialias?: boolean;
+  /** Stacked-composition transparency (COMPOSITION-DESIGN.md D5 §1, T6.1
+   *  slice 1): when true, the surface clears with alpha 0
+   *  (`backgroundAlpha:0`) instead of an opaque `background`, so a world
+   *  layered ABOVE another shows the layer below through it. */
+  transparent?: boolean;
+  /** Capture tier cost (D5 §4): flat on `Application.init`, never nested
+   *  under `context:` (the documented pixi trap) — required for any later
+   *  `drawImage()`-based composite capture of this surface. */
+  preserveDrawingBuffer?: boolean;
+}
+
+/**
+ * Create the world2d render surface — a PixiJS v8 `Application` whose auto-ticker
+ * is DISABLED (`autoStart:false`), so the engine's fixed-timestep loop drives
+ * rendering by calling `render()` from the `render` phase (mirroring how the
+ * Three.js adapter calls `composer.render(dt)`).
+ *
+ * `app.stage` holds a single `world` Container — the 2D camera lives here as a
+ * transform on `world` (pan = world.position, zoom = world.scale), per the spec's
+ * backend-2d-camera resolution. Screen-space HUD stays in the React/DOM overlay.
+ */
+export async function createPixiSurface(opts: PixiSurfaceOptions): Promise<PixiSurface> {
+  const app = new Application();
+  await app.init({
+    canvas: opts.canvas,
+    width: opts.width,
+    height: opts.height,
+    background: opts.background ?? '#10101a',
+    backgroundAlpha: opts.transparent ? 0 : 1,
+    resolution: opts.resolution ?? (typeof window !== 'undefined' ? window.devicePixelRatio : 1),
+    autoDensity: true,
+    antialias: opts.antialias ?? true,
+    autoStart: false, // engine loop drives rendering — NOT Pixi's ticker
+    preference: 'webgl',
+    // Capture tier cost (D5 §4) — FLAT here, never nested under `context:`
+    // (the documented pixi trap: nesting silently breaks GL bootstrap).
+    ...(opts.preserveDrawingBuffer ? { preserveDrawingBuffer: true } : {}),
+  });
+  // Stop the shared/internal ticker defensively (autoStart:false already prevents start).
+  app.ticker.stop();
+
+  const world = new Container();
+  world.label = 'world2d-root';
+  app.stage.addChild(world);
+
+  return {
+    app,
+    world,
+    render: () => app.render(),
+    resize: (width: number, height: number) => {
+      app.renderer.resize(width, height);
+    },
+    dispose: () => {
+      // Tear down the Pixi app + GPU context. Children are destroyed by the loader's
+      // own dispose; here we release the renderer/canvas binding.
+      app.destroy({ removeView: false }, { children: true });
+    },
+  };
+}

package/src/world2d/scene-capture-2d.ts

@@ -0,0 +1,117 @@
+/**
+ * Scene capture for world2d — 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 this
+ * way (degrade to iframe-reachable or opaque-embed tiers — see the spec).
+ */
+
+/** A live world2d 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;
+  waitForCapture(timeoutMs?: number): 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> };
+}
+
+/**
+ * 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): 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) {
+        captured = { stage, renderer: this['renderer'], app: this };
+        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(timeoutMs = 10_000) {
+      if (captured) return Promise.resolve(captured);
+      return new Promise<CapturedRuntime2D>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          const i = waiters.indexOf(wrapped);
+          if (i >= 0) waiters.splice(i, 1);
+          reject(
+            new Error(
+              `world2d scene capture timed out after ${timeoutMs}ms — the game never ` +
+                `rendered, or it bundles its own (un-shared) copy of pixi.js.`,
+            ),
+          );
+        }, timeoutMs);
+        const wrapped = (rt: CapturedRuntime2D) => {
+          clearTimeout(timer);
+          resolve(rt);
+        };
+        waiters.push(wrapped);
+      });
+    },
+    uninstall() {
+      if (priorRender) Object.defineProperty(proto, 'render', priorRender);
+      else if (realRender)
+        Object.defineProperty(proto, 'render', {
+          configurable: true,
+          writable: true,
+          value: realRender,
+        });
+    },
+  };
+}