@vgai/engine 0.2.0

package/src/scene/material-factory.ts

@@ -0,0 +1,211 @@
+import * as THREE from 'three';
+import { loadTexture } from './asset-loaders';
+import { DEFAULTS } from './defaults';
+import { buildGeneratedGeometry } from './geometry-registry';
+import { buildCustomMaterial } from './material-registry';
+import type { SceneMaterial, SceneMesh } from './scene-types';
+
+/**
+ * Single source of truth for turning a `SceneMesh` / `SceneMaterial` descriptor
+ * into Three.js geometry/material. Both the runtime scene-loader and the editor's
+ * entity-factory import these, so the editor preview renders exactly what the game
+ * renders (the WYSIWYG guarantee in ARCHITECTURE.md). Previously these were
+ * copy-pasted in two places and had to be hand-synced — any new material feature
+ * added to one and not the other silently broke that guarantee.
+ *
+ * Callers must have imported the side-effect registration modules
+ * (`./geometries`, `./materials`, plus any custom defs) so `buildGeneratedGeometry`
+ * and `buildCustomMaterial` resolve their registries.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward type-based switch with fallback args
+export function createGeometry(mesh: SceneMesh): THREE.BufferGeometry {
+  if (mesh.generator) {
+    return buildGeneratedGeometry(mesh.generator, mesh.generatorParams ?? {});
+  }
+  const args = mesh.args ?? [];
+  switch (mesh.type) {
+    case 'box':
+      return new THREE.BoxGeometry(args[0] ?? 1, args[1] ?? 1, args[2] ?? 1);
+    case 'sphere':
+      return new THREE.SphereGeometry(args[0] ?? 0.5, args[1] ?? 32, args[2] ?? 16);
+    case 'plane':
+      return new THREE.PlaneGeometry(args[0] ?? 1, args[1] ?? 1);
+    case 'cylinder':
+      return new THREE.CylinderGeometry(
+        args[0] ?? 0.5,
+        args[1] ?? 0.5,
+        args[2] ?? 1,
+        args[3] ?? 32,
+      );
+    case 'capsule':
+      return new THREE.CapsuleGeometry(args[0] ?? 0.5, args[1] ?? 1, args[2] ?? 4, args[3] ?? 16);
+    default:
+      return new THREE.BoxGeometry(1, 1, 1);
+  }
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: flat type-based switch building Three materials
+export function createMaterial(mat?: SceneMaterial): THREE.Material {
+  if (!mat) return new THREE.MeshStandardMaterial({ color: DEFAULTS.material.color });
+
+  // Only include texture props when actually defined (Three.js warns on undefined values)
+  const textures: {
+    map?: THREE.Texture;
+    normalMap?: THREE.Texture;
+    emissiveMap?: THREE.Texture;
+    aoMap?: THREE.Texture;
+    lightMap?: THREE.Texture;
+    roughnessMap?: THREE.Texture;
+    metalnessMap?: THREE.Texture;
+  } = {};
+  if (mat.map) textures.map = loadTexture(mat.map);
+  if (mat.normalMap) textures.normalMap = loadTexture(mat.normalMap);
+  if (mat.emissiveMap) textures.emissiveMap = loadTexture(mat.emissiveMap);
+  if (mat.aoMap) textures.aoMap = loadTexture(mat.aoMap);
+  if (mat.lightMap) textures.lightMap = loadTexture(mat.lightMap);
+  if (mat.roughnessMap) textures.roughnessMap = loadTexture(mat.roughnessMap);
+  if (mat.metalnessMap) textures.metalnessMap = loadTexture(mat.metalnessMap);
+
+  // R1c — every fallback below reads DEFAULTS.material.* instead of
+  // duplicating its value as a bare literal, so DEFAULTS stays the single
+  // source of truth for what an omitted field renders as (see
+  // defaults-out-of-scope-consistency.test.ts / material-factory.test.ts's
+  // "omitted-field" locks, which fail if either copy drifts from the other).
+  const dMat = DEFAULTS.material;
+  const sideValue = mat.side ?? dMat.side;
+  const side =
+    sideValue === 'back'
+      ? THREE.BackSide
+      : sideValue === 'double'
+        ? THREE.DoubleSide
+        : THREE.FrontSide;
+  const opacity = mat.opacity ?? dMat.opacity;
+  const transparent = mat.transparent ?? dMat.transparent;
+
+  switch (mat.type) {
+    case 'basic':
+      return new THREE.MeshBasicMaterial({
+        color: mat.color ?? dMat.color,
+        ...textures,
+        lightMapIntensity: mat.lightMapIntensity ?? 1,
+        opacity,
+        transparent,
+        side,
+      });
+    case 'toon':
+      return new THREE.MeshToonMaterial({
+        color: mat.color ?? dMat.color,
+        ...textures,
+        lightMapIntensity: mat.lightMapIntensity ?? 1,
+        emissive: mat.emissive ?? dMat.emissive,
+        emissiveIntensity: mat.emissiveIntensity ?? dMat.emissiveIntensity,
+        opacity,
+        transparent,
+        side,
+      });
+    case 'physical':
+      return new THREE.MeshPhysicalMaterial({
+        color: mat.color ?? dMat.color,
+        metalness: mat.metalness ?? dMat.metalness,
+        roughness: mat.roughness ?? dMat.roughness,
+        ...textures,
+        lightMapIntensity: mat.lightMapIntensity ?? 1,
+        emissive: mat.emissive ?? dMat.emissive,
+        emissiveIntensity: mat.emissiveIntensity ?? dMat.emissiveIntensity,
+        opacity,
+        transparent,
+        side,
+        flatShading: mat.flatShading ?? dMat.flatShading,
+        // Clearcoat
+        ...(mat.clearcoat
+          ? {
+              clearcoat: mat.clearcoat.clearcoat,
+              clearcoatRoughness:
+                mat.clearcoat.clearcoatRoughness ?? dMat.clearcoat.clearcoatRoughness,
+              ...(mat.clearcoat.clearcoatMap
+                ? { clearcoatMap: loadTexture(mat.clearcoat.clearcoatMap) }
+                : {}),
+              ...(mat.clearcoat.clearcoatRoughnessMap
+                ? { clearcoatRoughnessMap: loadTexture(mat.clearcoat.clearcoatRoughnessMap) }
+                : {}),
+            }
+          : {}),
+        // Transmission — `thickness` used to hardcode a literal `0` here,
+        // silently diverging from DEFAULTS.material.transmission.thickness
+        // (0.5, per the editor's Transmission inspector default). Fixed:
+        // read DEFAULTS directly, like every other fallback in this file.
+        ...(mat.transmission
+          ? {
+              transmission: mat.transmission.transmission,
+              ior: mat.transmission.ior ?? dMat.transmission.ior,
+              thickness: mat.transmission.thickness ?? dMat.transmission.thickness,
+              ...(mat.transmission.attenuationColor
+                ? { attenuationColor: new THREE.Color(mat.transmission.attenuationColor) }
+                : {}),
+              attenuationDistance: mat.transmission.attenuationDistance ?? Infinity,
+              ...(mat.transmission.transmissionMap
+                ? { transmissionMap: loadTexture(mat.transmission.transmissionMap) }
+                : {}),
+            }
+          : {}),
+        // Sheen
+        ...(mat.sheen
+          ? {
+              sheen: mat.sheen.sheen,
+              sheenColor: new THREE.Color(mat.sheen.sheenColor ?? dMat.sheen.sheenColor),
+              sheenRoughness: mat.sheen.sheenRoughness ?? dMat.sheen.sheenRoughness,
+              ...(mat.sheen.sheenColorMap
+                ? { sheenColorMap: loadTexture(mat.sheen.sheenColorMap) }
+                : {}),
+              ...(mat.sheen.sheenRoughnessMap
+                ? { sheenRoughnessMap: loadTexture(mat.sheen.sheenRoughnessMap) }
+                : {}),
+            }
+          : {}),
+        // Iridescence
+        ...(mat.iridescence
+          ? {
+              iridescence: mat.iridescence.iridescence,
+              iridescenceIOR: mat.iridescence.iridescenceIOR ?? dMat.iridescence.iridescenceIOR,
+              iridescenceThicknessRange:
+                mat.iridescence.iridescenceThicknessRange ??
+                dMat.iridescence.iridescenceThicknessRange,
+              ...(mat.iridescence.iridescenceMap
+                ? { iridescenceMap: loadTexture(mat.iridescence.iridescenceMap) }
+                : {}),
+              ...(mat.iridescence.iridescenceThicknessMap
+                ? {
+                    iridescenceThicknessMap: loadTexture(mat.iridescence.iridescenceThicknessMap),
+                  }
+                : {}),
+            }
+          : {}),
+        // Displacement
+        ...(mat.displacementMap ? { displacementMap: loadTexture(mat.displacementMap) } : {}),
+        ...(mat.displacementScale !== undefined
+          ? { displacementScale: mat.displacementScale }
+          : {}),
+        ...(mat.displacementBias !== undefined ? { displacementBias: mat.displacementBias } : {}),
+      });
+    case 'custom': {
+      if (!mat.def) {
+        throw new Error('Custom material requires a "def" (registered material name)');
+      }
+      return buildCustomMaterial(mat.def, mat.uniforms ?? {});
+    }
+    default:
+      return new THREE.MeshStandardMaterial({
+        color: mat.color ?? dMat.color,
+        metalness: mat.metalness ?? dMat.metalness,
+        roughness: mat.roughness ?? dMat.roughness,
+        ...textures,
+        lightMapIntensity: mat.lightMapIntensity ?? 1,
+        emissive: mat.emissive ?? dMat.emissive,
+        emissiveIntensity: mat.emissiveIntensity ?? dMat.emissiveIntensity,
+        opacity,
+        transparent,
+        side,
+        flatShading: mat.flatShading ?? dMat.flatShading,
+      });
+  }
+}

package/src/scene/material-registry.ts

@@ -0,0 +1,73 @@
+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

@@ -0,0 +1,7 @@
+/**
+ * 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

@@ -0,0 +1,56 @@
+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/scene/parse.ts

@@ -0,0 +1,71 @@
+import type { ZodIssue } from 'zod';
+import { checkSceneVersionInRange } from './scene-version';
+import type { InstancesFile, MaterialFile, PrefabFile, SceneFile } from './schema';
+import {
+  InstancesFileSchema,
+  MaterialFileSchema,
+  PrefabFileSchema,
+  SceneFileSchema,
+} from './schema';
+
+export class SceneParseError extends Error {
+  readonly issues: ZodIssue[];
+  /** The offending file's path/URL, when the caller knows it (T4.6). */
+  readonly filePath?: string | undefined;
+
+  constructor(issues: ZodIssue[], filePath?: string) {
+    const msg = issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+    const header = filePath ? `Scene validation failed (${filePath}):` : 'Scene validation failed:';
+    super(`${header}\n${msg}`);
+    this.name = 'SceneParseError';
+    this.issues = issues;
+    this.filePath = filePath;
+  }
+}
+
+export function parseSceneFile(json: unknown, filePath?: string): SceneFile {
+  const result = SceneFileSchema.safeParse(json);
+  if (!result.success) {
+    throw new SceneParseError(result.error.issues, filePath);
+  }
+  // Post-Zod-parse range check (T2.3/D3 §1.E) — the Zod shape stays a bare
+  // `z.number()`; this is where the file-format `version` axis is actually
+  // read/enforced.
+  checkSceneVersionInRange(result.data.version, 'scene');
+  return result.data;
+}
+
+export function parsePrefabFile(json: unknown, filePath?: string): PrefabFile {
+  const result = PrefabFileSchema.safeParse(json);
+  if (!result.success) {
+    throw new SceneParseError(result.error.issues, filePath);
+  }
+  checkSceneVersionInRange(result.data.version, 'prefab');
+  return result.data;
+}
+
+/**
+ * Parse a `.mat.json` shared material asset (T4.6). Unlike scene/prefab files,
+ * there is no version-range gate yet for this format — `MaterialFileSchema`'s
+ * `version` field is RESERVED (see `schema-consumption-map.ts`).
+ */
+export function parseMaterialFile(json: unknown, filePath?: string): MaterialFile {
+  const result = MaterialFileSchema.safeParse(json);
+  if (!result.success) {
+    throw new SceneParseError(result.error.issues, filePath);
+  }
+  return result.data;
+}
+
+/**
+ * Parse a `.instances.json` instance-transform asset (F3,
+ * docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Mirrors `parseMaterialFile` exactly —
+ * no version-range gate (the format is a bare tuple array, no `version` field).
+ */
+export function parseInstancesFile(json: unknown, filePath?: string): InstancesFile {
+  const result = InstancesFileSchema.safeParse(json);
+  if (!result.success) {
+    throw new SceneParseError(result.error.issues, filePath);
+  }
+  return result.data;
+}