@vgai/engine 0.5.22 → 0.5.23

package/src/animation/clip-map.ts

@@ -1,34 +0,0 @@
-import type * as THREE from 'three';
-
-/**
- * Build the clip lookup shared by runtime and editor.
- *
- * GLTF exporters disagree about case and may prefix animation names with an
- * armature (`Armature|Idle`). Keep the exact exported suffix while also
- * exposing a lowercase lookup, then apply aliases case-insensitively. This
- * lets authored graphs use either `Idle_Loop` or `idle_loop` without silently
- * falling back to the bind pose.
- */
-export function buildClipMap(
-  animations: THREE.AnimationClip[],
-  aliases: Record<string, string> = {},
-): Map<string, THREE.AnimationClip> {
-  const clips = new Map<string, THREE.AnimationClip>();
-  const canonical = new Map<string, THREE.AnimationClip>();
-
-  for (const clip of animations) {
-    const raw = clip.name.split('|').pop()?.trim() || clip.name;
-    canonical.set(raw.toLowerCase(), clip);
-    if (!clips.has(raw)) clips.set(raw, clip);
-    if (!clips.has(raw.toLowerCase())) clips.set(raw.toLowerCase(), clip);
-  }
-
-  for (const [source, alias] of Object.entries(aliases)) {
-    const clip = canonical.get(source.toLowerCase());
-    if (!clip) continue;
-    if (!clips.has(alias)) clips.set(alias, clip);
-    if (!clips.has(alias.toLowerCase())) clips.set(alias.toLowerCase(), clip);
-  }
-
-  return clips;
-}

package/src/asset-registry.ts

@@ -1,89 +0,0 @@
-/**
- * Central asset registry — stores per-asset metadata (import corrections, etc.).
- *
- * Loaded once via fetch(), cached in memory. Both the runtime scene loader
- * and editor entity factory import from this module.
- */
-
-import * as THREE from 'three';
-import { resolveUrl } from './loader';
-
-export interface ImportCorrection {
-  /** Uniform scale factor applied to the GLTF clone before entity transform. */
-  scale?: number;
-  /** Euler rotation in degrees [x, y, z] applied to the GLTF clone before entity transform. */
-  rotation?: [number, number, number];
-}
-
-export interface AssetMeta {
-  importCorrection?: ImportCorrection;
-}
-
-/**
- * Apply an asset's visual-only import correction to the loaded GLTF content.
- * Call this on the model child, before placing it under the entity wrapper, so
- * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
- * -Z-forward coordinate contract.
- */
-export function applyImportCorrection(
-  content: THREE.Object3D,
-  correction: ImportCorrection | undefined,
-): void {
-  if (!correction) return;
-  if (correction.scale !== undefined) content.scale.multiplyScalar(correction.scale);
-  if (correction.rotation) {
-    content.rotation.set(
-      THREE.MathUtils.degToRad(correction.rotation[0]),
-      THREE.MathUtils.degToRad(correction.rotation[1]),
-      THREE.MathUtils.degToRad(correction.rotation[2]),
-    );
-  }
-}
-
-type AssetRegistry = Record<string, AssetMeta>;
-
-let registryCache: AssetRegistry | null = null;
-let registryPromise: Promise<AssetRegistry> | null = null;
-
-/** Normalize asset path for registry lookup (strip leading slash). */
-function normalize(path: string): string {
-  return path.startsWith('/') ? path.slice(1) : path;
-}
-
-/**
- * Fetch and cache the asset registry. Safe to call multiple times —
- * returns the cached result after the first successful load.
- */
-export function loadRegistry(): Promise<AssetRegistry> {
-  if (registryCache) return Promise.resolve(registryCache);
-  if (registryPromise) return registryPromise;
-
-  registryPromise = fetch(resolveUrl('asset-registry.json'))
-    .then((res) => {
-      if (!res.ok) return {};
-      return res.json() as Promise<AssetRegistry>;
-    })
-    .catch(() => ({}) as AssetRegistry)
-    .then((data) => {
-      registryCache = data;
-      return data;
-    });
-
-  return registryPromise;
-}
-
-/** Get metadata for an asset path, or undefined if not in the registry. */
-export function getAssetMeta(path: string): AssetMeta | undefined {
-  if (!registryCache) return undefined;
-  // Try exact match first, then normalized
-  return registryCache[path] ?? registryCache[normalize(path)];
-}
-
-/**
- * Update the in-memory cache directly (used by the editor after saving
- * import settings, to avoid a re-fetch).
- */
-export function setRegistryCache(data: AssetRegistry): void {
-  registryCache = data;
-  registryPromise = null;
-}

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);
-  });
-}