@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/scene/geometries/terrain.ts

@@ -1,42 +0,0 @@
-import * as THREE from 'three';
-import { registerGeometryGenerator } from '../geometry-registry';
-
-/**
- * Built-in "Terrain" geometry generator — a horizontal heightfield (XZ plane,
- * height in +Y) displaced by a deterministic sum-of-sines, so it pairs with a
- * `trimesh` collider for matching terrain physics. Proof material for roadmap #3.
- *
- * Params: width, depth (world size), segments (grid resolution per axis),
- * amplitude (max height), frequency (wave scale). Deterministic — no Math.random.
- */
-function heightAt(x: number, z: number, amplitude: number, frequency: number): number {
-  return (
-    amplitude *
-    (Math.sin(x * frequency) * 0.5 +
-      Math.cos(z * frequency * 1.3) * 0.3 +
-      Math.sin((x + z) * frequency * 0.5) * 0.2)
-  );
-}
-
-registerGeometryGenerator('Terrain', {
-  build(params) {
-    const width = (params['width'] as number) ?? 40;
-    const depth = (params['depth'] as number) ?? 40;
-    const segments = (params['segments'] as number) ?? 64;
-    const amplitude = (params['amplitude'] as number) ?? 3;
-    const frequency = (params['frequency'] as number) ?? 0.25;
-
-    const geo = new THREE.PlaneGeometry(width, depth, segments, segments);
-    // Lay the plane flat (XZ) with normal +Y, then displace Y by the heightfield.
-    geo.rotateX(-Math.PI / 2);
-    const pos = geo.attributes['position'] as THREE.BufferAttribute;
-    for (let i = 0; i < pos.count; i++) {
-      const x = pos.getX(i);
-      const z = pos.getZ(i);
-      pos.setY(i, heightAt(x, z, amplitude, frequency));
-    }
-    pos.needsUpdate = true;
-    geo.computeVertexNormals();
-    return geo;
-  },
-});

package/src/scene/geometry-registry.ts

@@ -1,42 +0,0 @@
-import type * as THREE from 'three';
-
-/**
- * A geometry-generator definition. Registered by name and resolved when a scene
- * mesh declares `{ generator: <name> }`. Mirrors the material/instancer registry
- * pattern: the generation logic lives here in code, the authored params arrive as
- * scene data.
- *
- * `build` returns a real THREE.BufferGeometry. Paired with a `trimesh` collider,
- * the generated geometry also drives physics (e.g. terrain), so the visual and
- * collision surfaces match exactly.
- */
-export interface GeometryGeneratorDef {
-  build(params: Record<string, unknown>): THREE.BufferGeometry;
-}
-
-const registry = new Map<string, GeometryGeneratorDef>();
-
-/** Register a geometry generator under `name`. */
-export function registerGeometryGenerator(name: string, def: GeometryGeneratorDef): void {
-  registry.set(name, def);
-}
-
-/** Look up a registered geometry generator. */
-export function getGeometryGenerator(name: string): GeometryGeneratorDef | undefined {
-  return registry.get(name);
-}
-
-/**
- * Build a procedural geometry by registered generator name. Throws if the
- * generator is unknown (fail loud — same posture as the other registries).
- */
-export function buildGeneratedGeometry(
-  name: string,
-  params: Record<string, unknown>,
-): THREE.BufferGeometry {
-  const def = registry.get(name);
-  if (!def) {
-    throw new Error(`Geometry generator "${name}" not found in geometry registry`);
-  }
-  return def.build(params ?? {});
-}

package/src/scene/instance-registry.ts

@@ -1,84 +0,0 @@
-import * as THREE from 'three';
-import type { InstancesFile } from './schema/instances';
-
-/**
- * An instancer definition. Registered by name and resolved when a scene mesh
- * declares `{ instancer: <name> }`. Mirrors the material-registry pattern: the
- * generation logic lives here in code (the "behavior" half), the authored params
- * arrive as scene data (the "data" half).
- *
- * `build` returns per-instance LOCAL transforms; the factory packs them into a
- * single THREE.InstancedMesh, so N instances cost one draw call.
- */
-export interface InstancerDef {
-  /** Produce per-instance local matrices from authored params. */
-  build(params: Record<string, unknown>): THREE.Matrix4[];
-}
-
-const registry = new Map<string, InstancerDef>();
-
-/** Register an instancer definition under `name`. */
-export function registerInstancer(name: string, def: InstancerDef): void {
-  registry.set(name, def);
-}
-
-/** Look up a registered instancer. */
-export function getInstancer(name: string): InstancerDef | undefined {
-  return registry.get(name);
-}
-
-/**
- * Build a THREE.InstancedMesh from a registered instancer. Throws if the
- * instancer is unknown (fail loud — same posture as the component/material
- * registries). One InstancedMesh = one draw call for all instances.
- */
-export function buildInstancedMesh(
-  geometry: THREE.BufferGeometry,
-  material: THREE.Material,
-  name: string,
-  params: Record<string, unknown>,
-): THREE.InstancedMesh {
-  const def = registry.get(name);
-  if (!def) {
-    throw new Error(`Instancer "${name}" not found in instancer registry`);
-  }
-  const matrices = def.build(params ?? {});
-  const mesh = new THREE.InstancedMesh(geometry, material, matrices.length);
-  for (let i = 0; i < matrices.length; i++) {
-    mesh.setMatrixAt(i, matrices[i]!);
-  }
-  mesh.instanceMatrix.needsUpdate = true;
-  mesh.userData['__instancer'] = name;
-  return mesh;
-}
-
-/**
- * Build a THREE.InstancedMesh directly from an already-parsed `.instances.json`
- * tuple array (F3, docs/VSCN-STRUCTURAL-GAPS-DESIGN.md — the declarative,
- * authored-data counterpart to `buildInstancedMesh`'s code-registered
- * instancers). Each tuple is
- * `[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ]`. Pure and
- * synchronous (no fetch) so it's exercisable headlessly by both the scene
- * loader (after it fetches+parses the asset) and unit tests.
- */
-export function buildInstancedMeshFromTuples(
-  geometry: THREE.BufferGeometry,
-  material: THREE.Material,
-  tuples: InstancesFile,
-): THREE.InstancedMesh {
-  const mesh = new THREE.InstancedMesh(geometry, material, tuples.length);
-  const pos = new THREE.Vector3();
-  const quat = new THREE.Quaternion();
-  const scale = new THREE.Vector3();
-  const matrix = new THREE.Matrix4();
-  for (let i = 0; i < tuples.length; i++) {
-    const t = tuples[i]!;
-    pos.set(t[0], t[1], t[2]);
-    quat.set(t[3], t[4], t[5], t[6]);
-    scale.set(t[7], t[8], t[9]);
-    matrix.compose(pos, quat, scale);
-    mesh.setMatrixAt(i, matrix);
-  }
-  mesh.instanceMatrix.needsUpdate = true;
-  return mesh;
-}

package/src/scene/instancers/grid.ts

@@ -1,38 +0,0 @@
-import * as THREE from 'three';
-import { registerInstancer } from '../instance-registry';
-
-/**
- * Built-in "Grid" instancer — a countX × countZ grid of instances on the XZ
- * plane, centred on the entity origin, with optional deterministic y-jitter.
- * Proof material for roadmap #2 (first-class instancing): a 100×100 grid is
- * 10,000 instances in one draw call.
- *
- * Determinism: uses a seeded LCG (not Math.random) so a scene renders the same
- * layout every load — important for reproducible scenes and tests.
- */
-registerInstancer('Grid', {
-  build(params) {
-    const countX = (params['countX'] as number) ?? 100;
-    const countZ = (params['countZ'] as number) ?? 100;
-    const spacing = (params['spacing'] as number) ?? 2;
-    const jitter = (params['jitter'] as number) ?? 0;
-    let seed = (params['seed'] as number) ?? 1;
-    const rand = () => {
-      seed = (seed * 1664525 + 1013904223) % 4294967296;
-      return seed / 4294967296;
-    };
-
-    const offX = ((countX - 1) * spacing) / 2;
-    const offZ = ((countZ - 1) * spacing) / 2;
-    const matrices: THREE.Matrix4[] = [];
-    const m = new THREE.Matrix4();
-    for (let x = 0; x < countX; x++) {
-      for (let z = 0; z < countZ; z++) {
-        const y = jitter ? (rand() - 0.5) * jitter : 0;
-        m.makeTranslation(x * spacing - offX, y, z * spacing - offZ);
-        matrices.push(m.clone());
-      }
-    }
-    return matrices;
-  },
-});

package/src/scene/instancers/index.ts

@@ -1,7 +0,0 @@
-/**
- * Built-in instancer definitions. Importing this module for its side effects
- * registers the built-ins into the instancer registry. Both the runtime factory
- * (scene-loader) and the editor factory (entity-factory) import it so instanced
- * meshes resolve on whichever side builds first.
- */
-import './grid';

package/src/scene/material-registry.ts

@@ -1,73 +0,0 @@
-import type * as THREE from 'three';
-
-/**
- * A custom-material definition. Registered by name and resolved when a scene
- * material declares `{ type: 'custom', def: <name> }`.
- *
- * The GLSL program lives here in code (the "behavior" half); the per-entity
- * authored uniform values arrive as data on the scene material's `uniforms`
- * (the "data" half) and are passed to `build`. A def may optionally tick its
- * own uniforms each frame (e.g. uTime) via `update`.
- *
- * This is the native extension point of the material system — not a wrapper:
- * `build` returns a real THREE.Material (typically a ShaderMaterial, or a stock
- * material patched via onBeforeCompile), and the engine renders it directly.
- */
-export interface MaterialDef {
-  /** Build a real THREE material from authored uniform values. */
-  build(uniforms: Record<string, unknown>): THREE.Material;
-  /** Optional per-frame uniform update for self-animating materials. */
-  update?(dt: number, material: THREE.Material, uniforms: Record<string, unknown>): void;
-  /** Representative flat color (CSS hex) for the editor's "unlit" view mode. */
-  previewColor?: string;
-}
-
-const registry = new Map<string, MaterialDef>();
-
-/** Register a custom-material definition under `name`. */
-export function registerMaterial(name: string, def: MaterialDef): void {
-  registry.set(name, def);
-}
-
-/** Look up a registered material definition. */
-export function getMaterialDef(name: string): MaterialDef | undefined {
-  return registry.get(name);
-}
-
-/**
- * Build a custom material by registered def name. Tags the resulting material's
- * `userData` so the per-frame tick and the editor view-mode override can find it.
- * Throws if the def is unknown (fail loud — same posture as the component registry).
- */
-export function buildCustomMaterial(
-  name: string,
-  uniforms: Record<string, unknown>,
-): THREE.Material {
-  const def = registry.get(name);
-  if (!def) {
-    throw new Error(`Custom material def "${name}" not found in material registry`);
-  }
-  const material = def.build(uniforms ?? {});
-  material.userData['__matDef'] = name;
-  material.userData['__uniforms'] = uniforms ?? {};
-  return material;
-}
-
-/**
- * Tick every custom material under `root` (self-animating uniforms). Called from
- * the runtime `preRender` phase and from the editor's edit-mode RAF — one code
- * path, both modes. Walks the scene graph; materials without a `__matDef` tag are
- * skipped.
- */
-export function tickCustomMaterials(root: THREE.Object3D, dt: number): void {
-  root.traverse((obj) => {
-    const material = (obj as THREE.Mesh).material;
-    if (!material) return;
-    const list = Array.isArray(material) ? material : [material];
-    for (const mat of list) {
-      const defName = mat.userData?.['__matDef'] as string | undefined;
-      if (!defName) continue;
-      registry.get(defName)?.update?.(dt, mat, mat.userData['__uniforms'] ?? {});
-    }
-  });
-}

package/src/scene/materials/index.ts

@@ -1,7 +0,0 @@
-/**
- * Built-in custom-material definitions. Importing this module for its side
- * effects registers the built-ins into the material registry. Both the runtime
- * factory (scene-loader) and the editor factory (entity-factory) import it so
- * custom materials resolve on whichever side builds first.
- */
-import './water';

package/src/scene/materials/water.ts

@@ -1,56 +0,0 @@
-import * as THREE from 'three';
-import { registerMaterial } from '../material-registry';
-
-/**
- * Built-in "Water" custom material — the proof-of-concept for first-class custom
- * shaders (roadmap item #1). Vertex shader displaces a plane with travelling sine
- * waves driven by `uTime`; fragment tints by `uColor` with a little wave-crest
- * lightening. Demonstrates: authored uniforms (color, waveHeight), a real
- * ShaderMaterial built from scene JSON, and a self-animating uniform (uTime).
- */
-const vertexShader = /* glsl */ `
-  uniform float uTime;
-  uniform float uWaveHeight;
-  varying float vWave;
-  void main() {
-    vec3 p = position;
-    // PlaneGeometry lies in local XY with normal +Z; displace along the normal so
-    // a plane rotated flat (XZ) ripples upward in world Y.
-    float wave =
-      sin(p.x * 1.5 + uTime) * 0.6 +
-      cos(p.y * 1.2 + uTime * 0.8) * 0.4;
-    p.z += wave * uWaveHeight;
-    vWave = wave;
-    gl_Position = projectionMatrix * modelViewMatrix * vec4(p, 1.0);
-  }
-`;
-
-const fragmentShader = /* glsl */ `
-  uniform vec3 uColor;
-  varying float vWave;
-  void main() {
-    vec3 c = uColor + vWave * 0.12;
-    gl_FragColor = vec4(c, 1.0);
-  }
-`;
-
-registerMaterial('Water', {
-  previewColor: '#0a5fa5',
-  build(uniforms) {
-    const color = (uniforms['color'] as string) ?? '#0a5fa5';
-    const waveHeight = (uniforms['waveHeight'] as number) ?? 0.4;
-    return new THREE.ShaderMaterial({
-      uniforms: {
-        uTime: { value: 0 },
-        uColor: { value: new THREE.Color(color) },
-        uWaveHeight: { value: waveHeight },
-      },
-      vertexShader,
-      fragmentShader,
-    });
-  },
-  update(dt, material) {
-    const uTime = (material as THREE.ShaderMaterial).uniforms['uTime'];
-    if (uTime) uTime.value += dt;
-  },
-});

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

@@ -1,86 +0,0 @@
-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);
-  }
-}