@vgai/engine 0.2.0

package/src/world2d/authoring-2d.ts

@@ -0,0 +1,208 @@
+import type { Container } from 'pixi.js';
+
+/**
+ * AuthoringAdapter-2D — the world2d analog of the editor AuthoringAdapter /
+ * IngestAuthoringAdapter, implemented DIRECTLY over a live PixiJS display tree
+ * (no fabricated Scene2D / SceneEntity — the anti-shim rule). Used by the editor to
+ * inspect + edit world2d entities (first-party OR an ingested unmodified game),
+ * with stable structural-path ids so edits re-bind after the tree rebuilds.
+ */
+
+export interface EditorNode2D {
+  id: string;
+  label: string;
+  kind: 'sprite' | 'animatedsprite' | 'text' | 'container' | string;
+  parentId: string | null;
+  childIds: string[];
+}
+
+export interface Transform2DValue {
+  position: [number, number];
+  rotation: number;
+  scale: [number, number];
+}
+
+export interface Property2D {
+  path: string;
+  label: string;
+  type: 'string' | 'number' | 'boolean' | 'vec2' | 'color';
+  value: unknown;
+}
+
+/** A persisted edit overlay keyed by structural-path id (the 2D analog of IngestOverlay). */
+export interface Override2D {
+  position?: [number, number];
+  rotation?: number;
+  scale?: [number, number];
+  tint?: number;
+  visible?: boolean;
+}
+export type Overlay2D = Record<string, Override2D>;
+
+function kindOf(o: Container): string {
+  const ctor = o.constructor?.name?.toLowerCase() ?? 'container';
+  if (ctor.includes('animatedsprite')) return 'animatedsprite';
+  if (ctor.includes('sprite')) return 'sprite';
+  if (ctor.includes('text')) return 'text';
+  return 'container';
+}
+
+export class AuthoringAdapter2D {
+  private readonly byId = new Map<string, Container>();
+  private overlay: Overlay2D = {};
+  private dirty = false;
+
+  constructor(
+    private readonly root: Container,
+    opts: { overlay?: Overlay2D } = {},
+  ) {
+    if (opts.overlay) this.overlay = opts.overlay;
+    this.refresh();
+  }
+
+  /** Walk the live tree assigning deterministic structural-path ids, reapply overlay. */
+  refresh(): { count: number; sprites: number } {
+    this.byId.clear();
+    let count = 0;
+    let sprites = 0;
+    const visit = (o: Container, path: string): void => {
+      const id = `w2d:${path}:${kindOf(o)}:${o.label ?? ''}`;
+      (o as Container & { __authId?: string }).__authId = id;
+      this.byId.set(id, o);
+      count++;
+      if (kindOf(o).includes('sprite')) sprites++;
+      o.children.forEach((c, i) => {
+        visit(c as Container, `${path}/${i}`);
+      });
+    };
+    this.root.children.forEach((c, i) => {
+      visit(c as Container, `${i}`);
+    });
+    // Reapply any saved overlay edits to the live tree.
+    for (const [id, ov] of Object.entries(this.overlay)) this.applyOverride(id, ov);
+    return { count, sprites };
+  }
+
+  roots(): EditorNode2D[] {
+    return this.root.children.map((c) => this.toNode(c as Container));
+  }
+
+  node(id: string): EditorNode2D | null {
+    const o = this.byId.get(id);
+    return o ? this.toNode(o) : null;
+  }
+
+  displayObject(id: string): Container | null {
+    return this.byId.get(id) ?? null;
+  }
+
+  private toNode(o: Container): EditorNode2D {
+    const self = o as Container & { __authId?: string };
+    return {
+      id: self.__authId ?? '',
+      label: o.label ?? kindOf(o),
+      kind: kindOf(o),
+      parentId: (o.parent as (Container & { __authId?: string }) | null)?.__authId ?? null,
+      childIds: o.children.map((c) => (c as Container & { __authId?: string }).__authId ?? ''),
+    };
+  }
+
+  // --- Transforms ---
+  getTransform(id: string): Transform2DValue | null {
+    const o = this.byId.get(id);
+    if (!o) return null;
+    return {
+      position: [o.position.x, o.position.y],
+      rotation: o.rotation,
+      scale: [o.scale.x, o.scale.y],
+    };
+  }
+
+  setTransform(id: string, t: Partial<Transform2DValue>): void {
+    const o = this.byId.get(id);
+    if (!o) return;
+    if (t.position) o.position.set(t.position[0], t.position[1]);
+    if (t.rotation !== undefined) o.rotation = t.rotation;
+    if (t.scale) o.scale.set(t.scale[0], t.scale[1]);
+    this.overlay[id] ??= {};
+    const ov = this.overlay[id];
+    if (t.position) ov.position = t.position;
+    if (t.rotation !== undefined) ov.rotation = t.rotation;
+    if (t.scale) ov.scale = t.scale;
+    this.dirty = true;
+  }
+
+  // --- Inspector (reflected fields) ---
+  properties(id: string): Property2D[] {
+    const o = this.byId.get(id);
+    if (!o) return [];
+    const props: Property2D[] = [
+      { path: 'label', label: 'Name', type: 'string', value: o.label ?? '' },
+      { path: 'visible', label: 'Visible', type: 'boolean', value: o.visible },
+      { path: 'alpha', label: 'Alpha', type: 'number', value: o.alpha },
+    ];
+    if ('tint' in o)
+      props.push({
+        path: 'tint',
+        label: 'Tint',
+        type: 'color',
+        value: (o as { tint: number }).tint,
+      });
+    return props;
+  }
+
+  set(id: string, path: string, value: unknown): void {
+    const o = this.byId.get(id) as (Container & Record<string, unknown>) | undefined;
+    if (!o) return;
+    o[path] = value;
+    this.overlay[id] ??= {};
+    if (path === 'tint') this.overlay[id].tint = value as number;
+    if (path === 'visible') this.overlay[id].visible = value as boolean;
+    this.dirty = true;
+  }
+
+  private applyOverride(id: string, ov: Override2D): void {
+    const o = this.byId.get(id);
+    if (!o) return;
+    if (ov.position) o.position.set(ov.position[0], ov.position[1]);
+    if (ov.rotation !== undefined) o.rotation = ov.rotation;
+    if (ov.scale) o.scale.set(ov.scale[0], ov.scale[1]);
+    if (ov.tint !== undefined && 'tint' in o) (o as { tint: number }).tint = ov.tint;
+    if (ov.visible !== undefined) o.visible = ov.visible;
+  }
+
+  /**
+   * Re-apply a saved/external overlay onto the (already-walked) live tree, merging
+   * it into the in-memory overlay so a later `serializeOverlay()`/save preserves it
+   * and a later `refresh()` re-applies it again. Ids absent from the current tree
+   * are skipped (orphaned, not an error) — the 2D analog of
+   * `IngestAuthoringAdapter.applyOverlay` (T3.2 slice 3). Used both for the initial
+   * reload (constructor `opts.overlay`) and for `PersistenceProvider.applyExternal`
+   * (re-apply a changed overlay file without a full remount).
+   */
+  applyOverlay(overlay: Overlay2D): { applied: number; orphaned: number } {
+    let applied = 0;
+    let orphaned = 0;
+    for (const [id, ov] of Object.entries(overlay)) {
+      if (!this.byId.has(id)) {
+        orphaned++;
+        continue;
+      }
+      this.applyOverride(id, ov);
+      this.overlay[id] = { ...this.overlay[id], ...ov };
+      applied++;
+    }
+    return { applied, orphaned };
+  }
+
+  isDirty(): boolean {
+    return this.dirty;
+  }
+  serializeOverlay(): Overlay2D {
+    return this.overlay;
+  }
+  /** Clear the dirty flag after a successful save (mirrors IngestAuthoringAdapter). */
+  markClean(): void {
+    this.dirty = false;
+  }
+}

package/src/world2d/capture-to-scene2d.ts

@@ -0,0 +1,52 @@
+import type { Container } from 'pixi.js';
+import type { Entity2D, Scene2DFile } from './schema/entity2d';
+
+/**
+ * Capture an ingested/live PixiJS subtree into authored Scene2D entities — the
+ * world2d analog of capture-to-vscn (`ingest-capture.ts`). Recognizable sprites/
+ * text/containers map to first-party `sprite`/`text`/`transform2d` sections;
+ * turns inspection into portable authored content.
+ *
+ * Honest ceiling (mirrors the 3D one): a Scene2D `sprite` expresses tint + size +
+ * anchor, not an arbitrary texture/GraphicsContext, so a captured display keeps its
+ * transform + tint + size; bespoke Graphics geometry is captured as a plain tinted
+ * sprite placeholder.
+ */
+function numToHex(n: number | undefined): string {
+  return `#${((n ?? 0xffffff) & 0xffffff).toString(16).padStart(6, '0')}`;
+}
+
+function captureNode(o: Container): Entity2D {
+  const ctor = o.constructor?.name?.toLowerCase() ?? '';
+  const entity: Entity2D = {
+    name: o.label ?? ctor ?? 'entity',
+    surface: 'world2d',
+    transform2d: {
+      position: [o.position.x, o.position.y],
+      rotation: o.rotation,
+      scale: [o.scale.x, o.scale.y],
+    },
+  };
+  if (ctor.includes('text')) {
+    entity.text = { text: (o as { text?: string }).text ?? '' };
+  } else if (ctor.includes('sprite')) {
+    entity.sprite = {
+      tint: numToHex((o as { tint?: number }).tint),
+      width: Math.round(o.width),
+      height: Math.round(o.height),
+    };
+  }
+  const kids = o.children?.filter((c) => (c as Container).label !== undefined) ?? [];
+  if (kids.length) entity.children = kids.map((c) => captureNode(c as Container));
+  return entity;
+}
+
+/** Capture selected subtree roots (by display object) into a Scene2D file. */
+export function captureToScene2D(roots: Container[], name = 'captured-world2d'): Scene2DFile {
+  return {
+    version: 1,
+    name,
+    surface: 'world2d',
+    entities: roots.map(captureNode),
+  };
+}

package/src/world2d/collision-2d.ts

@@ -0,0 +1,106 @@
+import type RAPIER from '@dimforge/rapier2d-compat';
+import type { NodeOf } from '../ecs/game-component';
+import type { GameContext } from '../runtime/types';
+import type { Physics2DRegistry } from './physics2d-registry';
+
+export type Collision2DHandler = (handleA: number, handleB: number, started: boolean) => void;
+
+/**
+ * Drains the Rapier 2D event queue each postPhysics and dispatches collision
+ * events — the world2d analog of `createCollisionSystem`. Events are buffered then
+ * handlers run after the drain returns (same re-entrancy guard as the 3D system:
+ * a handler must not call back into Rapier while the queue is borrowed).
+ */
+export function createCollision2DSystem(rapierWorld: RAPIER.World, eventQueue: RAPIER.EventQueue) {
+  const handlers: Collision2DHandler[] = [];
+  return {
+    onCollision(handler: Collision2DHandler) {
+      handlers.push(handler);
+    },
+    offCollision(handler: Collision2DHandler) {
+      const idx = handlers.indexOf(handler);
+      if (idx !== -1) handlers.splice(idx, 1);
+    },
+    drain() {
+      const events: Array<[number, number, boolean]> = [];
+      eventQueue.drainCollisionEvents((h1, h2, started) => {
+        events.push([h1, h2, started]);
+      });
+      for (const [h1, h2, started] of events) {
+        for (let i = 0; i < handlers.length; i++) handlers[i]!(h1, h2, started);
+      }
+    },
+    getBodyHandleFromCollider(colliderHandle: number): number | undefined {
+      const collider = rapierWorld.getCollider(colliderHandle);
+      return collider?.parent()?.handle;
+    },
+  };
+}
+
+export type Collision2DSystem = ReturnType<typeof createCollision2DSystem>;
+
+/**
+ * The minimal component-manager capability `createTriggerDispatch2D` needs —
+ * `getComponents` returning instances with optional trigger callbacks, typed
+ * honestly against `NodeOf<'pixijs'>` (T7.2, D8 — this dispatch is always
+ * pixi-world-scoped) rather than the full manager type. Deliberately a
+ * structural slice: the unified `ComponentManager` (`ecs/component-manager.ts`,
+ * what production wires up since T7.3 slice 1, and the only manager left —
+ * the world2d silo's manager is deleted, T7.3 slice 2) satisfies it — this
+ * dispatcher has no dependency on which `WorldKind` a caller's manager was
+ * constructed for.
+ */
+export interface TriggerDispatchComponents {
+  getComponents(node: NodeOf<'pixijs'>): ReadonlyArray<{
+    onTriggerEnter?(other: NodeOf<'pixijs'>, ctx: GameContext): void;
+    onTriggerExit?(other: NodeOf<'pixijs'>, ctx: GameContext): void;
+  }>;
+}
+
+/**
+ * Turn Rapier 2D sensor overlaps into `onTriggerEnter`/`onTriggerExit` callbacks on
+ * the GameComponents of the two involved display objects — the 2D analog of
+ * `createTriggerDispatch`. Only sensor-involved collisions dispatch triggers.
+ *
+ * `ctx` is typed `GameContext` (the unified manager's typing) — production
+ * (`pixi-game-adapter.ts`) casts its real `World2DContext` to `GameContext`
+ * before passing it here; individual `GameComponent<'pixijs'>` subclasses
+ * that need real 2D fields off `ctx` widen their own lifecycle-method
+ * signature to `GameContext | World2DContext` and narrow back down (see
+ * `Camera2DFollow.update` in `./components-2d.ts` — the worked example of
+ * the pattern since the world2d-demo silo and its `first-party-scene.ts`
+ * were deleted, T6.1 slice 4). This function only ever forwards `ctx` — it
+ * never reads a field off it itself.
+ */
+export function createTriggerDispatch2D(
+  physics: Physics2DRegistry,
+  components: TriggerDispatchComponents,
+  rapierWorld: RAPIER.World,
+  ctx: GameContext,
+): Collision2DHandler {
+  return (handleA, handleB, started) => {
+    const colA = rapierWorld.getCollider(handleA);
+    const colB = rapierWorld.getCollider(handleB);
+    if (!colA?.isSensor() && !colB?.isSensor()) return;
+
+    const objA = physics.getByColliderHandle(handleA);
+    const objB = physics.getByColliderHandle(handleB);
+    if (!objA || !objB) return;
+
+    notify(components, objA, objB, started, ctx);
+    notify(components, objB, objA, started, ctx);
+  };
+}
+
+function notify(
+  components: TriggerDispatchComponents,
+  self: NodeOf<'pixijs'>,
+  other: NodeOf<'pixijs'>,
+  started: boolean,
+  ctx: GameContext,
+): void {
+  for (const inst of components.getComponents(self)) {
+    if (started) inst.onTriggerEnter?.(other, ctx);
+    else inst.onTriggerExit?.(other, ctx);
+  }
+}

package/src/world2d/components-2d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { GameComponent } from '../ecs/game-component';
+import type { GameContext } from '../runtime/types';
+import type { World2DContext } from './types';
+
+/**
+ * Camera2DFollow — the canonical 2D camera (spec backend-2d-camera): a 2D camera is
+ * a transform on the world Container (`ctx.stage`). Attached to the entity to follow;
+ * each frame it pans/zooms `ctx.stage` so the target display stays centered. Mirrors
+ * the 3D "camera GameComponent on a camera entity" canonical-way rule.
+ */
+export class Camera2DFollow extends GameComponent<'pixijs'> {
+  static declaredKind = 'pixijs' as const;
+  static phase = 'preRender' as const;
+  static schema = z.object({
+    zoom: z.number().default(1).describe('Camera zoom (world Container scale)'),
+    smoothing: z.number().default(0.12).describe('Follow lerp factor 0..1 (1 = instant)'),
+  });
+  zoom = 1;
+  smoothing = 0.12;
+
+  // CONFLICT (bridged, same mechanism the deleted `GameComponent2D` alias
+  // used — T7.3 slice 2): `GameComponent<K>`'s lifecycle methods are typed
+  // `ctx: GameContext` (D8 §2 — `ctx` always means the game-level context),
+  // but this component genuinely needs `World2DContext` fields (`app`/
+  // `stage`), which share no structure with `GameContext` (neither is
+  // assignable to the other) — a plain `ctx: World2DContext` override would
+  // fail even under method bivariance (TS2416). Widening the parameter to
+  // the union is a valid (non-bivariant) override on its own — accepting a
+  // superset of the base signature is always sound — then narrowing back
+  // down via the cast below. At runtime this always receives the real
+  // `World2DContext` (`pixi-game-adapter.ts` casts it to `GameContext` only
+  // for the unified manager's internal typing).
+  update(_dt: number, gameCtx: GameContext | World2DContext): void {
+    const ctx = gameCtx as World2DContext;
+    const screen = ctx.app.screen;
+    const targetX = screen.width / 2 - this.node.x * this.zoom;
+    const targetY = screen.height / 2 - this.node.y * this.zoom;
+    const stage = ctx.stage;
+    stage.scale.set(this.zoom);
+    stage.position.x += (targetX - stage.position.x) * this.smoothing;
+    stage.position.y += (targetY - stage.position.y) * this.smoothing;
+  }
+}
+
+/**
+ * Clickable2D — federated-events picking (spec backend-2d-input-picking). The sprite
+ * must be authored `interactive: true` (loader sets eventMode='static'); on pointerdown
+ * the sprite cycles tint, proving Pixi world picking works and is independent of the
+ * React/DOM HUD layer.
+ *
+ * INPUT ROUTING RULE (resolves the headline open design question): the three surfaces
+ * are stacked DOM siblings — React/DOM HUD (top, z-index, pointer-events gated) gets the
+ * event first; if it doesn't consume it, the Pixi canvas's federated EventSystem hit-tests
+ * world2d display objects; Three's raycaster handles the world3d canvas. Because each
+ * surface owns its own canvas/DOM node, a click on the HUD does not also pick the Pixi
+ * world beneath it, and vice-versa — no cross-surface double-picking.
+ */
+export class Clickable2D extends GameComponent<'pixijs'> {
+  static declaredKind = 'pixijs' as const;
+  static schema = z.object({
+    tints: z
+      .array(z.string())
+      .default(['#ff6b6b', '#4ecdc4', '#ffd23f', '#a06bff'])
+      .describe('Tint cycle'),
+  });
+  tints: string[] = ['#ff6b6b', '#4ecdc4', '#ffd23f', '#a06bff'];
+  private idx = 0;
+  private handler = (): void => {
+    this.idx = (this.idx + 1) % this.tints.length;
+    (this.node as { tint?: number }).tint = Number.parseInt(
+      this.tints[this.idx]!.replace('#', ''),
+      16,
+    );
+  };
+
+  init(): void {
+    this.node.eventMode = 'static';
+    this.node.cursor = 'pointer';
+    this.node.on('pointerdown', this.handler);
+  }
+  update(): void {}
+  dispose(): void {
+    this.node.off('pointerdown', this.handler);
+  }
+}

package/src/world2d/index.ts

@@ -0,0 +1,66 @@
+/**
+ * world2d — the PixiJS 2D render surface for vgai.
+ *
+ * A peer to the Three.js world3d surface and the React UI surface (ARCHITECTURE.md
+ * §Render Surfaces). It LITERALLY reuses the engine's loop primitives (`createGameLoop`,
+ * `createSystemRunner`, `PHASE_ORDER`) and faithfully MIRRORS the entity / authored-data
+ * model as a 2D twin (`Scene2D`), instantiating entities as PixiJS display objects
+ * instead of Object3Ds, with 2D physics/collision via native Rapier 2D — built on
+ * native libraries with thin adapters. Gameplay behavior attaches via the SAME
+ * `GameComponent<'pixijs'>` (`ecs/game-component.ts`) and unified `ComponentManager`
+ * (`ecs/component-manager.ts`) every threejs world uses (T7.3).
+ *
+ * See docs/PIXI-WORLD2D-MAXIMAL-SPEC.json (FROZEN).
+ */
+
+export {
+  AuthoringAdapter2D,
+  type EditorNode2D,
+  type Overlay2D,
+  type Override2D,
+  type Property2D,
+  type Transform2DValue,
+} from './authoring-2d';
+export { captureToScene2D } from './capture-to-scene2d';
+export {
+  type Collision2DSystem,
+  createCollision2DSystem,
+  createTriggerDispatch2D,
+} from './collision-2d';
+export { Camera2DFollow, Clickable2D } from './components-2d';
+export {
+  type EmbedMount2D,
+  type IframeReachableMount2D,
+  mountIngestGame2DEmbed,
+  mountIngestGame2DIframeReachable,
+} from './ingest-iframe-2d';
+export { type IngestGame2D, type IngestMount2D, mountIngestGame2D } from './ingest2d';
+export {
+  createPhysics2DRegistry,
+  type Physics2DRefs,
+  type Physics2DRegistry,
+} from './physics2d-registry';
+export {
+  createWorld2DRuntime,
+  type MountedGame2D,
+  type PixiSceneConfig,
+  PixiSceneGameAdapter,
+  type World2DHost,
+  type World2DSession,
+  type World2DSetupFn,
+} from './pixi-game-adapter';
+export { createPixiSurface, type PixiSurface, type PixiSurfaceOptions } from './pixi-surface';
+export {
+  type CapturedRuntime2D,
+  installSceneCapture2D,
+  type SceneCapture2DHandle,
+} from './scene-capture-2d';
+export { loadScene2DFromData, type Scene2DInstance } from './scene2d-loader';
+export * from './schema/entity2d';
+export * from './schema/physics2d';
+export * from './schema/sprite';
+export * from './schema/tilemap';
+export * from './schema/tuples2d';
+export { createPhysicsAdapter2D, type PhysicsAdapter2D } from './system-adapters-2d';
+export { createTransformWriter2D } from './transform-writer-2d';
+export type { Component2DRegistry, World2DContext } from './types';