@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/scene/instancers/index.js

@@ -0,0 +1,7 @@
+/**
+ * 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/dist/scene/light-camera-factory.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared light + camera factory (T1.13 — DEFAULTS truth).
+ *
+ * `createLight`/`createCamera` used to be duplicated verbatim between the
+ * runtime loader (`scene-loader.ts`) and the editor preview
+ * (`entity-factory.ts`) — both hardcoded the same fallback literals (color
+ * '#ffffff', fov 60, near 0.1, far 1000, etc.) that happened to agree with
+ * `DEFAULTS.light`/`DEFAULTS.camera` by luck rather than by reading them. Any
+ * edit to one copy (or to `DEFAULTS`) could silently diverge from the other.
+ *
+ * This module is now the ONE place that builds a `THREE.Light`/`THREE.Camera`
+ * from a `SceneLight`/`SceneCamera` descriptor, reading its fallbacks from
+ * `DEFAULTS` (the single source of truth for scene default values — see
+ * `scene/defaults.ts`). Both the loader and the editor import it, so they
+ * can no longer disagree.
+ */
+import * as THREE from 'three';
+import type { SceneCamera, SceneLight } from './scene-types';
+/** Build a Three.js light from a `SceneLight` descriptor. */
+export declare function createLight(def: SceneLight): THREE.Light;
+/** Build a Three.js camera from a `SceneCamera` descriptor. */
+export declare function createCamera(def: SceneCamera): THREE.Camera;
+//# sourceMappingURL=light-camera-factory.d.ts.map

package/dist/scene/light-camera-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light-camera-factory.d.ts","sourceRoot":"","sources":["../../src/scene/light-camera-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAa/B,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAI7D,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,KAAK,CAAC,KAAK,CAsCxD;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,KAAK,CAAC,MAAM,CAoB3D"}

package/dist/scene/light-camera-factory.js

@@ -0,0 +1,68 @@
+/**
+ * Shared light + camera factory (T1.13 — DEFAULTS truth).
+ *
+ * `createLight`/`createCamera` used to be duplicated verbatim between the
+ * runtime loader (`scene-loader.ts`) and the editor preview
+ * (`entity-factory.ts`) — both hardcoded the same fallback literals (color
+ * '#ffffff', fov 60, near 0.1, far 1000, etc.) that happened to agree with
+ * `DEFAULTS.light`/`DEFAULTS.camera` by luck rather than by reading them. Any
+ * edit to one copy (or to `DEFAULTS`) could silently diverge from the other.
+ *
+ * This module is now the ONE place that builds a `THREE.Light`/`THREE.Camera`
+ * from a `SceneLight`/`SceneCamera` descriptor, reading its fallbacks from
+ * `DEFAULTS` (the single source of truth for scene default values — see
+ * `scene/defaults.ts`). Both the loader and the editor import it, so they
+ * can no longer disagree.
+ */
+import * as THREE from 'three';
+// F2 (docs/VSCN-STRUCTURAL-GAPS-DESIGN.md) — area lights. `RectAreaLight`
+// requires its LTC lookup-texture uniforms initialized once before the first
+// instance is constructed; three.js ships that setup as an addon, not part
+// of core. Imported via the `three/addons/*` alias (package.json `exports`:
+// `"./addons/*": "./examples/jsm/*"` — the identical file as
+// `three/examples/jsm/lights/RectAreaLightUniformsLib.js`) because a literal
+// `/examples/` specifier trips `engine-host-no-game-imports.test.ts`'s
+// game/editor-example guard (a same-substring false positive against this
+// repo's OWN `packages/editor/template/src/examples/` convention, unrelated
+// to three.js's addon folder naming).
+import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';
+import { DEFAULTS } from './defaults';
+let rectAreaLightUniformsInitialized = false;
+/** Build a Three.js light from a `SceneLight` descriptor. */
+export function createLight(def) {
+    const d = DEFAULTS.light;
+    const color = def.color ?? d.color;
+    const intensity = def.intensity ?? d.intensity;
+    switch (def.type) {
+        case 'directional':
+            return new THREE.DirectionalLight(color, intensity);
+        case 'point':
+            return new THREE.PointLight(color, intensity, def.distance ?? d.distance);
+        case 'spot':
+            return new THREE.SpotLight(color, intensity, def.distance ?? d.distance, def.angle ?? d.angle, def.penumbra ?? d.penumbra);
+        case 'hemisphere':
+            return new THREE.HemisphereLight(color, def.groundColor ?? d.groundColor, intensity);
+        case 'area': {
+            // No shadow map is ever wired for this light (RectAreaLight does not
+            // support shadows in three.js — see the honesty note on the schema
+            // field's .describe(); degrade loudly, not silently).
+            if (!rectAreaLightUniformsInitialized) {
+                RectAreaLightUniformsLib.init();
+                rectAreaLightUniformsInitialized = true;
+            }
+            return new THREE.RectAreaLight(color, intensity, def.width ?? d.width, def.height ?? d.height);
+        }
+        default:
+            return new THREE.DirectionalLight(color, intensity);
+    }
+}
+/** Build a Three.js camera from a `SceneCamera` descriptor. */
+export function createCamera(def) {
+    const d = DEFAULTS.camera;
+    const aspect = (def.width ?? d.width) / (def.height ?? d.height);
+    if (def.type === 'orthographic') {
+        const size = def.orthoSize ?? d.orthoSize;
+        return new THREE.OrthographicCamera(-size * aspect, size * aspect, size, -size, def.near ?? d.near, def.far ?? d.far);
+    }
+    return new THREE.PerspectiveCamera(def.fov ?? d.fov, aspect, def.near ?? d.near, def.far ?? d.far);
+}

package/dist/scene/material-factory.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three';
+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.
+ */
+export declare function createGeometry(mesh: SceneMesh): THREE.BufferGeometry;
+export declare function createMaterial(mat?: SceneMaterial): THREE.Material;
+//# sourceMappingURL=material-factory.d.ts.map

package/dist/scene/material-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material-factory.d.ts","sourceRoot":"","sources":["../../src/scene/material-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;;;;GAWG;AAEH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CAAC,cAAc,CAwBpE;AAGD,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,KAAK,CAAC,QAAQ,CAmKlE"}

package/dist/scene/material-factory.js

@@ -0,0 +1,197 @@
+import * as THREE from 'three';
+import { loadTexture } from './asset-loaders';
+import { DEFAULTS } from './defaults';
+import { buildGeneratedGeometry } from './geometry-registry';
+import { buildCustomMaterial } from './material-registry';
+/**
+ * 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) {
+    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) {
+    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 = {};
+    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/dist/scene/material-registry.d.ts

@@ -0,0 +1,40 @@
+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;
+}
+/** Register a custom-material definition under `name`. */
+export declare function registerMaterial(name: string, def: MaterialDef): void;
+/** Look up a registered material definition. */
+export declare function getMaterialDef(name: string): MaterialDef | undefined;
+/**
+ * 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 declare function buildCustomMaterial(name: string, uniforms: Record<string, unknown>): THREE.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 declare function tickCustomMaterials(root: THREE.Object3D, dt: number): void;
+//# sourceMappingURL=material-registry.d.ts.map

package/dist/scene/material-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material-registry.d.ts","sourceRoot":"","sources":["../../src/scene/material-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC;IACzD,sEAAsE;IACtE,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvF,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAErE;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,KAAK,CAAC,QAAQ,CAShB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAW1E"}

package/dist/scene/material-registry.js

@@ -0,0 +1,44 @@
+const registry = new Map();
+/** Register a custom-material definition under `name`. */
+export function registerMaterial(name, def) {
+    registry.set(name, def);
+}
+/** Look up a registered material definition. */
+export function getMaterialDef(name) {
+    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, uniforms) {
+    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, dt) {
+    root.traverse((obj) => {
+        const material = obj.material;
+        if (!material)
+            return;
+        const list = Array.isArray(material) ? material : [material];
+        for (const mat of list) {
+            const defName = mat.userData?.['__matDef'];
+            if (!defName)
+                continue;
+            registry.get(defName)?.update?.(dt, mat, mat.userData['__uniforms'] ?? {});
+        }
+    });
+}

package/dist/scene/materials/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/scene/materials/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/scene/materials/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,SAAS,CAAC"}

package/dist/scene/materials/index.js

@@ -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/dist/scene/materials/water.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=water.d.ts.map

package/dist/scene/materials/water.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"water.d.ts","sourceRoot":"","sources":["../../../src/scene/materials/water.ts"],"names":[],"mappings":""}

package/dist/scene/materials/water.js

@@ -0,0 +1,54 @@
+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'] ?? '#0a5fa5';
+        const waveHeight = uniforms['waveHeight'] ?? 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.uniforms['uTime'];
+        if (uTime)
+            uTime.value += dt;
+    },
+});

package/dist/scene/parse.d.ts

@@ -0,0 +1,23 @@
+import type { ZodIssue } from 'zod';
+import type { InstancesFile, MaterialFile, PrefabFile, SceneFile } from './schema';
+export declare 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);
+}
+export declare function parseSceneFile(json: unknown, filePath?: string): SceneFile;
+export declare function parsePrefabFile(json: unknown, filePath?: string): PrefabFile;
+/**
+ * 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 declare function parseMaterialFile(json: unknown, filePath?: string): MaterialFile;
+/**
+ * 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 declare function parseInstancesFile(json: unknown, filePath?: string): InstancesFile;
+//# sourceMappingURL=parse.d.ts.map

package/dist/scene/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/scene/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAEpC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAQnF,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE3B,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM;CAQlD;AAmID,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAY1E;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAS5E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAMhF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAMlF"}