@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

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

@@ -1,19 +1,32 @@
 import RAPIER from '@dimforge/rapier2d-compat';
 import type { Container } from 'pixi.js';
+import { createInputManagerAdapter } from '../adapter/first-party-systems';
 import type { MountedPixiWorld } from '../adapter/game-adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
 import { createAssetCache } from '../assets';
 import { createGameLoop } from '../core/game-loop';
+import {
+  createSeededRandom,
+  DEFAULT_SEEDED_RANDOM_SEED,
+  getSeededRandom,
+} from '../core/seeded-random';
 import { createSystemRunner } from '../core/system-runner';
 import { createComponentManager } from '../ecs/component-manager';
+import { InputManager } from '../input/input-manager';
+import {
+  createDebugRegistry,
+  type DebugRegistry,
+  getDebugRegistry,
+} from '../runtime/debug-registry';
 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 { DEFAULT_WORLD2D_PIXELS_PER_METER, defaultWorld2DGravityY } from './physics2d-units';
 import { createPixiSurface, type PixiSurface } from './pixi-surface';
 import { loadScene2DFromData, type Scene2DInstance } from './scene2d-loader';
 import type { Scene2DFile } from './schema/entity2d';
@@ -25,6 +38,8 @@ export interface World2DHost {
   canvas: HTMLCanvasElement;
   width: number;
   height: number;
+  /** Headless validation mount: skip browser-only asset/input initialization. */
+  headless?: boolean;
   /** Shared Game root when mounted by the universal multi-world host. */
   game?: GameInternal;
   /** DPR override (T6.1 slice 1, COMPOSITION-DESIGN.md D5 §3 — "one DPR
@@ -85,6 +100,9 @@ export interface PixiSceneConfig {
   setup?: World2DSetupFn;
   /** Component registry the scene's `components` reference. */
   registry?: Component2DRegistry;
+  /** Input map JSON path. Defaults to the same conventional map as Three;
+   *  explicit `null` disables loading for deliberately input-free/test mounts. */
+  inputMapPath?: string | null;
   id?: string;
 }
 
@@ -101,7 +119,12 @@ export class PixiSceneGameAdapter {
   }
 
   async mount(host: World2DHost): Promise<MountedGame2D> {
-    const { sceneData, setup, registry = {} } = this.config;
+    const {
+      inputMapPath = '/inputmaps/default.inputmap.json',
+      sceneData,
+      setup,
+      registry = {},
+    } = this.config;
 
     // --- Pixi surface (autoStart:false; engine loop drives render) ---
     const surface: PixiSurface = await createPixiSurface({
@@ -120,15 +143,43 @@ export class PixiSceneGameAdapter {
 
     // --- Rapier 2D world (separate from the 3D world) ---
     await RAPIER.init();
-    const gravity = sceneData?.gravity ?? [0, 980];
+    const pixelsPerMeter = sceneData?.pixelsPerMeter ?? DEFAULT_WORLD2D_PIXELS_PER_METER;
+    const gravity = sceneData?.gravity ?? [0, defaultWorld2DGravityY(pixelsPerMeter)];
     const rapier2dWorld = new RAPIER.World({ x: gravity[0], y: gravity[1] });
+    // Keep Rapier's public API in authored pixels. Its native length-unit
+    // setting scales solver/contact tolerances for those pixel-sized bodies.
+    rapier2dWorld.lengthUnit = pixelsPerMeter;
     const eventQueue = new RAPIER.EventQueue(true);
 
     const physics2d = createPhysics2DRegistry();
-    const writeTransforms2D = createTransformWriter2D(physics2d);
+    const writeTransforms2D = createTransformWriter2D(physics2d, surface.world);
     const collisions2d = createCollision2DSystem(rapier2dWorld, eventQueue);
+    const ownsInput = !host.game;
+    const input = host.game?.input ?? new InputManager();
+    if (!host.headless && inputMapPath !== null) {
+      if (host.game) await host.game.loadInputMap(inputMapPath);
+      else await input.loadMap(inputMapPath);
+    }
+
+    const systemAdapters: SystemAdapters = {};
+    const debugRegistry: DebugRegistry =
+      (host.game ? getDebugRegistry(host.game) : null) ??
+      createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
+    if (ownsInput) systemAdapters.input = createInputManagerAdapter(input);
+    systemAdapters.debug = debugRegistry.adapter;
+    // W4b (F11 frame debugger): the pixijs adapter deliberately does NOT
+    // register a `renderDebug` SystemAdapter. The first-party WebGL2 frame
+    // capture (`dev/webgl-frame-capture.ts`) and its `onBeforeRender`-based
+    // attribution are three.js-shaped (three's own per-object pre-draw hook,
+    // a THREE.Scene traversal, `renderer.info` memory). PixiJS draws through
+    // its own batch renderer with no equivalent per-object seam, so a faithful
+    // pixi capture is a separate instrument — deferred, not faked. Absence of
+    // `renderDebug` here is the honest "capability not supported" signal; the
+    // editor's frame-debugger panel marks a pixi world's section absent rather
+    // than showing fabricated draws.
 
     const systems = createSystemRunner(host.game?.profiler.systemObserver, 'pixijs');
+    if (ownsInput) systems.add('input', () => input.poll(), { name: 'input.poll' });
     systems.add('physics', () => rapier2dWorld.step(eventQueue), { name: 'physics2d.step' });
     systems.add(
       'postPhysics',
@@ -149,44 +200,110 @@ export class PixiSceneGameAdapter {
       collisions2d,
       components: null!,
       systems,
-      ...(host.game ? { game: host.game } : {}),
+      input,
+      debug: debugRegistry.forWorld(this.id),
+      random:
+        (host.game ? getSeededRandom(host.game) : null) ??
+        createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED),
+      registerSystemAdapter: (kind, adapter) => {
+        systemAdapters[kind] = adapter;
+      },
+      ...(host.game ? { game: host.game, roots: host.game.roots } : {}),
     };
 
+    debugRegistry.setInputActionsSource(this.id, () =>
+      input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
+    );
+    debugRegistry.setInputTraceSource(this.id, () => {
+      const raw = input.getInputTrace();
+      return {
+        version: raw.version,
+        seed: (host.game ? getSeededRandom(host.game) : null)?.seed ?? null,
+        fixedDt: host.game?.loop.fixedDt ?? null,
+        ticks: raw.ticks,
+      };
+    });
+    debugRegistry.setVirtualInputTarget(this.id, {
+      setVirtualAction: (action, value) => input.setVirtualAction(action, value),
+      tapVirtualAction: (action) => input.tapVirtualAction(action),
+      clearVirtualActions: () => input.clearVirtualActions(),
+      scheduleActionAtTick: (tick, action, value) =>
+        input.scheduleActionAtTick(tick, action, value),
+      startInputRecording: () => input.startInputRecording(),
+      stopInputRecording: () => input.stopInputRecording(),
+      isInputRecording: () => input.isInputRecording(),
+      injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
+      injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
+      injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
+      injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
+    });
+    if (!host.game) input.setDebugEmit((event, detail) => ctx.debug?.emit(event, detail));
+
     // 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`
+    // is deleted (T7.3 slice 2). The manager accepts this native
+    // `World2DContext`, so Pixi component lifecycles need no union/cast.
+    // `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, {
+    ctx.components = createComponentManager(ctx, undefined, {
       kind: 'pixijs',
       physics2d,
     });
     collisions2d.onCollision(
-      createTriggerDispatch2D(
-        physics2d,
-        ctx.components,
-        rapier2dWorld,
-        ctx as unknown as GameContext,
-      ),
+      createTriggerDispatch2D(physics2d, ctx.components, rapier2dWorld, ctx),
     );
 
     // --- 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);
+    let disposed = false;
+    systems.add('animation', (dt) => sceneInstance?.updateAnimations(dt), {
+      name: 'pixi.animated-sprites',
+    });
+    const disposeResources = (): void => {
+      if (disposed) return;
+      disposed = true;
+      const errors: unknown[] = [];
+      const attempt = (dispose: () => void): void => {
+        try {
+          dispose();
+        } catch (error) {
+          errors.push(error);
+        }
+      };
+      attempt(() => cleanup?.dispose());
+      attempt(() => sceneInstance?.dispose());
+      attempt(() => ctx.components.clear());
+      attempt(() => debugRegistry.strip(this.id));
+      if (ownsInput) attempt(() => input.dispose());
+      attempt(() => physics2d.clear());
+      attempt(() => rapier2dWorld.free());
+      attempt(() => eventQueue.free());
+      attempt(() => surface.dispose());
+      if (errors.length > 0) {
+        throw new AggregateError(errors, `Failed to dispose Pixi world "${this.id}" cleanly`);
+      }
+    };
+    try {
+      if (sceneData) {
+        sceneInstance = await loadScene2DFromData(sceneData, ctx, registry);
+      } else if (setup) {
+        cleanup = await setup(ctx);
+      }
+    } catch (error) {
+      try {
+        disposeResources();
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [error, cleanupError],
+          `Pixi world "${this.id}" failed to mount and roll back cleanly`,
+        );
+      }
+      throw error;
     }
 
     return {
@@ -199,21 +316,15 @@ export class PixiSceneGameAdapter {
       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).
+      // Bare adapters own and close their private input frame here. A
+      // game-hosted adapter shares the one game-owned manager, whose frame is
+      // closed once after every root has advanced.
       frame: {
         runPhase: (phase, dt) => systems.runPhase(phase, dt),
+        ...(ownsInput ? { endFrame: () => input.endFrame() } : {}),
       },
-      dispose: () => {
-        cleanup?.dispose();
-        sceneInstance?.dispose();
-        ctx.components.clear();
-        physics2d.clear();
-        rapier2dWorld.free();
-        eventQueue.free();
-        surface.dispose();
-      },
+      systems: systemAdapters,
+      dispose: disposeResources,
     };
   }
 }
@@ -298,6 +409,7 @@ export async function createWorld2DRuntime(
     stop() {
       loop.stop();
       mounted.dispose();
+      game.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,

package/src/world2d/scene2d-identity.ts

@@ -0,0 +1,49 @@
+import type { Entity2D, Scene2DFile } from './schema/entity2d';
+
+/** Resolve every entity to one collision-free identity without mutating source. */
+export function resolveScene2DEntityIds(scene: Scene2DFile): Map<Entity2D, string> {
+  const authored = new Set<string>();
+  const collect = (entities: Entity2D[]): void => {
+    for (const entity of entities) {
+      if (entity.id) {
+        if (authored.has(entity.id)) throw new Error(`Duplicate world2d entity id: "${entity.id}"`);
+        authored.add(entity.id);
+      }
+      if (entity.children) collect(entity.children);
+    }
+  };
+  collect(scene.entities);
+
+  const used = new Set(authored);
+  const result = new Map<Entity2D, string>();
+  const visit = (entities: Entity2D[], parentPath: readonly number[]): void => {
+    entities.forEach((entity, index) => {
+      const path = [...parentPath, index];
+      let id = entity.id;
+      if (!id) {
+        const base = `scn2d:${path.join('.')}`;
+        id = base;
+        let suffix = 1;
+        while (used.has(id)) id = `${base}~${suffix++}`;
+        used.add(id);
+      }
+      result.set(entity, id);
+      if (entity.children) visit(entity.children, path);
+    });
+  };
+  visit(scene.entities, []);
+  return result;
+}
+
+/** Materialize the same identities the preview/hierarchy already project. */
+export function materializeScene2DEntityIds(scene: Scene2DFile): boolean {
+  const ids = resolveScene2DEntityIds(scene);
+  let changed = false;
+  for (const [entity, id] of ids) {
+    if (!entity.id) {
+      entity.id = id;
+      changed = true;
+    }
+  }
+  return changed;
+}