@vgai/engine 0.5.21 → 0.5.23

package/src/canvas-react/world-context.ts

@@ -1,253 +0,0 @@
-/**
- * `createCanvasRootContext` — the ENGINE runtime a canvas world owns, split out
- * of `./pixi-react-adapter.tsx` so it stays react-free and headlessly
- * unit-testable (`test/canvas-react-context-parity.test.tsx`).
- *
- * This is the canvas surface's answer to the same question
- * `world3d-react/world-context.ts` answers for three: what does a component
- * inside the world tree reach when it asks the engine for something?
- *
- *  1. **`ctx.debug` / `ctx.random` / `ctx.game` / `ctx.roots` are wired** from
- *     the ONE game-scoped registry (`getDebugRegistry(host.game)`), so a
- *     component's effect can `ctx.debug.registerStateProvider(...)` and be
- *     visible to `vgai eval`/the editor's debug panels.
- *  2. **`ctx.input` is the game-owned `InputManager` when a Game hosts the
- *     root** (`host.game.input` — the
- *     same instance every sibling root shares), and this module registers the
- *     per-world debug-registry seams (`setVirtualInputTarget`/
- *     `setInputActionsSource`/`setInputTraceSource`) that make `game.input.*`
- *     (the bot-input doctrine) resolve instead of throwing
- *     `DEBUG_INPUT_UNAVAILABLE`. The project's input map loads through
- *     `Game.loadInputMap` (the game-owned, load-once path every root shares).
- *     A missing/unparseable map degrades LOUDLY without failing the mount — a
- *     canvas world with no declared actions is legal. A bare/foreign mount
- *     receives `null`, visibly in the type, rather than a throwing getter.
- *  3. **Absent subsystems are absent from the type.** A canvas world builds no
- *     THREE scene/camera, Rapier world, composer, first-party audio/particles/
- *     debug-draw, or Three-flavoured `AssetCache`. Its explicit
- *     {@link CanvasGameContext} cannot name those fields, so misuse fails at
- *     the call site during typechecking instead of from a throwing getter at
- *     runtime.
- *
- * The Pixi handles themselves are deliberately NOT re-exposed here: a component
- * reaches the live `Application` (and therefore `app.stage`, `app.renderer`,
- * `app.ticker`) through `@pixi/react`'s own `useApplication()`, and its assets
- * through Pixi's own `Assets`. Re-publishing them on `ctx` would be a wrapper
- * standing between the author and the library.
- */
-
-import type { Application } from 'pixi.js';
-import type { CanvasHostContext } from '../adapter';
-import type { SystemAdapters } from '../adapter/system-adapter';
-import {
-  createSeededRandom,
-  DEFAULT_SEEDED_RANDOM_SEED,
-  getSeededRandom,
-} from '../core/seeded-random';
-import type { SimClock } from '../core/sim-clock';
-import { createSimClock, getSimClock, type SimClockInternal } from '../core/sim-clock';
-import { createSystemRunner } from '../core/system-runner';
-import {
-  createDebugRegistry,
-  type DebugRegistry,
-  getDebugRegistry,
-} from '../runtime/debug-registry';
-import type { ComponentContextBase } from '../runtime/types';
-
-/** The conventional input-map location every scaffolded project ships. Shared
- *  verbatim with the three lane — a project has ONE input map, whatever surface
- *  reads it. */
-export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
-
-export interface CanvasRootContextOptions {
-  /** World id — provenance for every debug-registry registration (matches the
-   *  manifest root id). */
-  readonly id: string;
-  /**
-   * Input map to load through `Game.loadInputMap` (game-owned, load-once —
-   * several roots asking for the SAME path share one load; competing paths
-   * throw there). Defaults to {@link DEFAULT_INPUT_MAP_PATH}. Pass `null` to
-   * skip loading (a world with no actions). Ignored when no `host.game` is
-   * present.
-   */
-  readonly inputMapPath?: string | null | undefined;
-}
-
-/** The engine services a Canvas component genuinely receives. Pixi's own
- * `useApplication()` and `Assets` remain the doors to rendering and assets.
- * `disposeAfter` is excluded because it accepts a `THREE.Object3D`; Canvas
- * code schedules `displayObject.destroy()` with `clock.after()` instead. */
-export type CanvasGameContext = ComponentContextBase & {
-  readonly clock: Omit<SimClock, 'disposeAfter'>;
-};
-
-/** What {@link createCanvasRootContext} returns — the engine runtime one canvas
- *  world owns, plus the wiring hooks the adapter's `mount()` drives. */
-export interface CanvasRootRuntime {
-  /** The explicit Canvas context this world's components read through
-   *  `useGameContext`. See {@link CanvasGameContext}. */
-  readonly ctx: CanvasGameContext;
-  /** The world-local phase runner `mount().update(dt)` ticks. */
-  readonly systems: ReturnType<typeof createSystemRunner>;
-  /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
-   *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded. */
-  readonly systemAdapters: SystemAdapters;
-  /** Resolves once the input map load settles (immediately when skipped).
-   *  Never rejects — a failed load reports loudly and resolves. */
-  readonly inputMapReady: Promise<void>;
-  /** Backfill the live `Application` once `@pixi/react` has initialized it —
-   *  before any tick can run. Read back via {@link CanvasRootRuntime.app}. */
-  setApplication(app: Application): void;
-  /** The live `Application`, or `null` before the first commit resolves it. */
-  readonly app: Application | null;
-  /** Strip this world's debug registrations (scoped, so sibling roots and
-   *  react-door registrations are untouched when a Game hosts this world) and
-   *  dispose a clock this mount created. */
-  dispose(): void;
-}
-
-/**
- * Build the engine runtime for one canvas world from a `CanvasHostContext`.
- * React-free on purpose: everything here is plain engine wiring the adapter
- * threads into the `@pixi/react` tree through `EngineBridge`.
- */
-export function createCanvasRootContext(
-  host: CanvasHostContext,
-  options: CanvasRootContextOptions,
-): CanvasRootRuntime {
-  const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH } = options;
-
-  // Same observer threading as the three lane — this world's phases show up
-  // under the shared game profiler when hosted.
-  const systems = createSystemRunner(host.game?.profiler.systemObserver, 'canvas');
-
-  // The mounted world's adapter surface (`mounted.systems`) — declared before
-  // ctx so `ctx.registerSystemAdapter` can close over it (a game-owned
-  // capability like networking registers here from component code).
-  const systemAdapters: SystemAdapters = {};
-
-  let app: Application | null = null;
-
-  const ctxRaw: Record<string, unknown> = {
-    systems,
-    input: host.game?.input ?? null,
-    registerSystemAdapter: (kind: keyof SystemAdapters, adapter: SystemAdapters[typeof kind]) => {
-      // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the three lane performs; correct by construction
-      (systemAdapters as any)[kind] = adapter;
-      host.game?.notifySystemAdaptersChanged();
-    },
-  };
-  const ctx = ctxRaw as unknown as CanvasGameContext;
-  if (host.game) {
-    ctx.game = host.game;
-    ctx.roots = host.game.roots;
-    ctx.playtest = host.game.playtest ?? null;
-  }
-
-  // --- ctx.debug — the ONE registry per Game root, shared across every world
-  // mounted onto it; a bare mount with no Game shell gets a private,
-  // mount-local registry instead. ---
-  const debugRegistry: DebugRegistry =
-    (host.game ? getDebugRegistry(host.game) : null) ??
-    createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
-  systemAdapters.debug = debugRegistry.adapter;
-  ctx.debug = debugRegistry.forRoot(id);
-  ctx.random =
-    (host.game ? getSeededRandom(host.game) : null) ??
-    createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
-
-  // --- ctx.clock — a REAL value, never a throwing getter: every world has a
-  // sim clock. A bare mount with no Game shell gets a private, mount-local one.
-  // `SimClock.disposeAfter` takes a THREE.Object3D, so the mount-local
-  // fallback's disposer is a loud refusal rather than a fabricated no-op: a
-  // canvas world's debris is a `PIXI.Container`, destroyed with its own
-  // `container.destroy()`.
-  const gameClock: SimClockInternal | null = host.game ? getSimClock(host.game) : null;
-  const clock: SimClockInternal =
-    gameClock ??
-    createSimClock({
-      dispose: () => {
-        throw new Error(
-          `canvas world "${id}": clock.disposeAfter() disposes a THREE.Object3D and has no ` +
-            'meaning in a canvas world — destroy a display object with its own ' +
-            '`container.destroy({ children: true })`, scheduled with `clock.after(seconds, ...)`.',
-        );
-      },
-    });
-  ctxRaw['clock'] = clock;
-
-  // --- ctx.input + the debug-registry input seams — the game-owned
-  // InputManager, polled by the game-scoped runner each frame; this world
-  // registers the per-world seams so `game.input.*` (virtual input) and the
-  // built-in `input.actions`/`input.trace` providers resolve to it. ---
-  let inputMapReady: Promise<void> = Promise.resolve();
-  if (host.game) {
-    const game = host.game;
-    const input = game.input;
-    debugRegistry.setInputActionsSource(id, () =>
-      input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
-    );
-    debugRegistry.setInputTraceSource(id, () => {
-      const raw = input.getInputTrace();
-      return {
-        version: raw.version,
-        seed: getSeededRandom(game)?.seed ?? null,
-        fixedDt: game.loop.fixedDt,
-        ticks: raw.ticks,
-      };
-    });
-    debugRegistry.setVirtualInputTarget(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.headless && inputMapPath !== null) {
-      // Load-once through the game-owned path (competing paths across roots
-      // throw THERE, loudly). A FAILED load must not fail this mount: a canvas
-      // world with no declared actions is legal. It degrades loudly instead.
-      inputMapReady = game.loadInputMap(inputMapPath).catch((err: unknown) => {
-        // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount
-        console.error(
-          `canvas world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
-            'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
-            'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
-            `createPixiReactAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`,
-        );
-      });
-    }
-  }
-
-  return {
-    ctx,
-    systems,
-    systemAdapters,
-    inputMapReady,
-    get app(): Application | null {
-      return app;
-    },
-    setApplication(next): void {
-      app = next;
-    },
-    dispose(): void {
-      // Same ownership rule the three lane follows: dispose ONLY a clock this
-      // mount created. The game-scoped one belongs to `GameInternal.dispose()`
-      // — killing it here would freeze sim time and cancel every SIBLING
-      // world's timers.
-      if (!gameClock) clock.dispose();
-      app = null;
-      // Scoped strip when a Game hosts this world (sibling roots stay live);
-      // a bare standalone mount owns its private registry and clears it all.
-      if (host.game) debugRegistry.strip(id);
-      else debugRegistry.strip();
-    },
-  };
-}

package/src/dev/debug-draw.ts

@@ -1,80 +0,0 @@
-import * as THREE from 'three';
-
-/**
- * Debug drawing utilities for development.
- *
- * Draw lines, spheres, boxes, and arrows for visualizing
- * physics colliders, raycasts, AI paths, etc.
- *
- * All debug objects are added to a dedicated group that can be toggled.
- */
-export function createDebugDraw(scene: THREE.Scene) {
-  const group = new THREE.Group();
-  group.name = 'debug-draw';
-  scene.add(group);
-
-  return {
-    /** Draw a line between two points */
-    line(from: THREE.Vector3, to: THREE.Vector3, color = 0x00ff00) {
-      const geometry = new THREE.BufferGeometry().setFromPoints([from, to]);
-      const material = new THREE.LineBasicMaterial({ color });
-      const line = new THREE.Line(geometry, material);
-      group.add(line);
-      return line;
-    },
-
-    /** Draw a wireframe sphere at a position */
-    sphere(center: THREE.Vector3, radius = 0.1, color = 0xff0000) {
-      const geo = new THREE.SphereGeometry(radius, 8, 8);
-      const mat = new THREE.MeshBasicMaterial({ color, wireframe: true });
-      const mesh = new THREE.Mesh(geo, mat);
-      mesh.position.copy(center);
-      group.add(mesh);
-      return mesh;
-    },
-
-    /** Draw a wireframe box */
-    box(center: THREE.Vector3, size: THREE.Vector3, color = 0x00ffff) {
-      const geo = new THREE.BoxGeometry(size.x, size.y, size.z);
-      const mat = new THREE.MeshBasicMaterial({ color, wireframe: true });
-      const mesh = new THREE.Mesh(geo, mat);
-      mesh.position.copy(center);
-      group.add(mesh);
-      return mesh;
-    },
-
-    /** Draw an arrow (direction indicator) */
-    arrow(origin: THREE.Vector3, direction: THREE.Vector3, length = 1, color = 0xffff00) {
-      // Clone before normalize() — never mutate the caller's vector.
-      const dir = direction.clone().normalize();
-      const arrow = new THREE.ArrowHelper(dir, origin, length, color);
-      group.add(arrow);
-      return arrow;
-    },
-
-    /** Clear all debug drawings */
-    clear() {
-      while (group.children.length > 0) {
-        const child = group.children[0]!;
-        group.remove(child);
-        if (child instanceof THREE.Mesh || child instanceof THREE.Line) {
-          // Mesh, Line and LineSegments all own geometry + material.
-          child.geometry.dispose();
-          (child.material as THREE.Material).dispose();
-        } else if (child instanceof THREE.ArrowHelper) {
-          // ArrowHelper owns a line + cone; dispose() frees both.
-          child.dispose();
-        }
-      }
-    },
-
-    /** Toggle debug draw visibility */
-    set visible(v: boolean) {
-      group.visible = v;
-    },
-
-    get visible() {
-      return group.visible;
-    },
-  };
-}

package/src/render/auto-batcher.ts

@@ -1,168 +0,0 @@
-import * as THREE from 'three';
-
-/**
- * Transparent auto-batcher (Strategy 1).
- *
- * The framework keeps each entity's Object3D as the logical handle (transform,
- * gameplay, physics, picking) and renders eligible entities through a shared
- * InstancedMesh under the hood — N logical objects, 1 draw call — WITHOUT the
- * user changing any code. Identity is never merged, so selection/raycast survive
- * (we keep an instanceId → entity map). The whole thing flips on/off live.
- *
- * Eligibility: an entity is a THREE.Mesh sharing geometry+material with others.
- * Entities marked `userData.__noBatch` (the per-entity opt-out) always render
- * individually. Custom/unique materials simply form their own (size-1) groups and
- * cost a draw each — they degrade, they don't break.
- *
- * Cost model (measured in docs/research/bench/): per-frame cost is paid only for
- * entities that MOVED (dirty-tracked via markMoved). A static scene re-syncs
- * nothing — write-once at build, then 1 draw/frame.
- */
-
-interface Batch {
-  key: string;
-  instanced: THREE.InstancedMesh;
-  members: THREE.Mesh[]; // localIndex → entity mesh (for picking + sync)
-}
-
-const SIG = (m: THREE.Mesh): string => {
-  const mat = Array.isArray(m.material) ? m.material[0]! : m.material;
-  return `${(m.geometry as THREE.BufferGeometry).uuid}|${mat.uuid}`;
-};
-
-export class AutoBatcher {
-  /** Root the batcher owns under the scene (instanced meshes when on, entities when off). */
-  readonly root = new THREE.Group();
-
-  private entities: THREE.Mesh[] = [];
-  private batches = new Map<string, Batch>();
-  private enabled: boolean;
-  /** Indices of entities whose transform changed since last sync. */
-  private dirty = new Set<number>();
-  private touchedBatches = new Set<Batch>();
-  // Per-mesh bookkeeping is kept in WeakMaps, NOT on userData (the typed userData
-  // registry is reserved for documented engine keys — see user-data.ts).
-  private indexOf = new WeakMap<THREE.Mesh, number>();
-  private optOut = new WeakSet<THREE.Mesh>();
-  private batchOf = new WeakMap<THREE.Mesh, { key: string; localIndex: number }>();
-  private membersOf = new WeakMap<THREE.InstancedMesh, THREE.Mesh[]>();
-
-  constructor(parent: THREE.Object3D, enabled = true) {
-    this.enabled = enabled;
-    this.root.name = 'AutoBatcher';
-    parent.add(this.root);
-  }
-
-  /** Register an entity (a Mesh) as the logical handle. Call build() after adding. */
-  add(entity: THREE.Mesh, optOut = false): void {
-    this.indexOf.set(entity, this.entities.length);
-    if (optOut) this.optOut.add(entity);
-    this.entities.push(entity);
-  }
-
-  /** Mark an entity moved this frame (dirty-tracking input). */
-  markMoved(entity: THREE.Mesh): void {
-    const i = this.indexOf.get(entity);
-    if (i !== undefined) this.dirty.add(i);
-  }
-
-  /** (Re)build the render representation for the current enabled state. */
-  build(): void {
-    this.clearRoot();
-    this.batches.clear();
-    if (!this.enabled) {
-      for (const e of this.entities) this.root.add(e);
-      return;
-    }
-    const m = new THREE.Matrix4();
-    // group eligible entities; opt-outs render individually
-    const groups = new Map<string, THREE.Mesh[]>();
-    for (const e of this.entities) {
-      if (this.optOut.has(e)) {
-        this.root.add(e);
-        continue;
-      }
-      const key = SIG(e);
-      const arr = groups.get(key) ?? [];
-      arr.push(e);
-      groups.set(key, arr);
-    }
-    for (const [key, members] of groups) {
-      const proto = members[0]!;
-      const mat = Array.isArray(proto.material) ? proto.material[0]! : proto.material;
-      const inst = new THREE.InstancedMesh(proto.geometry, mat, members.length);
-      inst.frustumCulled = false;
-      for (let i = 0; i < members.length; i++) {
-        const e = members[i]!;
-        e.updateMatrix();
-        m.copy(e.matrix);
-        inst.setMatrixAt(i, m);
-        this.batchOf.set(e, { key, localIndex: i });
-      }
-      inst.instanceMatrix.needsUpdate = true;
-      this.membersOf.set(inst, members); // localIndex → entity (picking)
-      this.root.add(inst);
-      this.batches.set(key, { key, instanced: inst, members });
-    }
-  }
-
-  /** Apply the dirty set to the instance buffers. Cheap when few moved. */
-  sync(): void {
-    if (!this.enabled) return;
-    const m = new THREE.Matrix4();
-    this.touchedBatches.clear();
-    for (const i of this.dirty) {
-      const e = this.entities[i]!;
-      const info = this.batchOf.get(e);
-      if (!info) continue; // opt-out or not batched
-      const batch = this.batches.get(info.key);
-      if (!batch) continue;
-      e.updateMatrix();
-      m.copy(e.matrix);
-      batch.instanced.setMatrixAt(info.localIndex, m);
-      this.touchedBatches.add(batch);
-    }
-    for (const b of this.touchedBatches) b.instanced.instanceMatrix.needsUpdate = true;
-    this.dirty.clear();
-  }
-
-  /** Live toggle: rebuilds the representation (one-time cost, not per-frame). */
-  setEnabled(on: boolean): void {
-    if (on === this.enabled) return;
-    this.enabled = on;
-    this.build();
-  }
-
-  isEnabled(): boolean {
-    return this.enabled;
-  }
-
-  /** Map a raycast hit on a batch back to the logical entity (editor/gameplay picking). */
-  resolvePick(intersection: THREE.Intersection): THREE.Mesh | null {
-    const obj = intersection.object;
-    if ((obj as THREE.InstancedMesh).isInstancedMesh && intersection.instanceId != null) {
-      const members = this.membersOf.get(obj as THREE.InstancedMesh);
-      return members?.[intersection.instanceId] ?? null;
-    }
-    return obj instanceof THREE.Mesh ? obj : null;
-  }
-
-  /** Per-frame draw-call count this batcher contributes (for stats). */
-  get drawCallCount(): number {
-    return this.enabled ? this.batches.size + this.optOutCount : this.entities.length;
-  }
-
-  private get optOutCount(): number {
-    let n = 0;
-    for (const e of this.entities) if (this.optOut.has(e)) n++;
-    return n;
-  }
-
-  private clearRoot(): void {
-    for (let i = this.root.children.length - 1; i >= 0; i--) {
-      const c = this.root.children[i]!;
-      this.root.remove(c);
-      if ((c as THREE.InstancedMesh).isInstancedMesh) (c as THREE.InstancedMesh).dispose();
-    }
-  }
-}

package/src/render/lod.ts

@@ -1,17 +0,0 @@
-import type * as THREE from 'three';
-
-/**
- * Per-frame LOD tick. `THREE.LOD` only swaps its active level when
- * `.update(camera)` runs, so every `THREE.LOD` in the scene graph needs this
- * called once a frame. Wired into the runtime's `preRender` system in
- * `adapter/setup-three-root-adapter.ts`.
- *
- * Format-neutral: it matches THREE's own `isLOD` marker and knows nothing about
- * how the LOD was built. Formerly `@engine/scene/scene-loader`'s
- * `updateSceneLODs`, relocated here when WO-8 deleted the `.vscn` scene loader.
- */
-export function updateSceneLODs(scene: THREE.Object3D, camera: THREE.Camera): void {
-  scene.traverse((o) => {
-    if ((o as THREE.LOD).isLOD) (o as THREE.LOD).update(camera);
-  });
-}