@vgai/engine 0.2.0 → 0.3.0

package/dist/scene/defaults.js

@@ -0,0 +1,151 @@
+/** Single source of truth for all scene default values. */
+export const DEFAULTS = {
+    transform: {
+        position: [0, 0, 0],
+        rotation: [0, 0, 0, 1],
+        scale: [1, 1, 1],
+    },
+    entity: {
+        visible: true,
+        locked: false,
+        pivot: [0, 0, 0],
+    },
+    material: {
+        type: 'standard',
+        color: '#888888',
+        metalness: 0,
+        roughness: 0.5,
+        emissive: '#000000',
+        emissiveIntensity: 0,
+        opacity: 1,
+        transparent: false,
+        side: 'front',
+        flatShading: false,
+        clearcoat: { clearcoat: 1, clearcoatRoughness: 0 },
+        transmission: { transmission: 1, ior: 1.5, thickness: 0.5 },
+        sheen: { sheen: 1, sheenColor: '#ffffff', sheenRoughness: 0.5 },
+        iridescence: {
+            iridescence: 1,
+            iridescenceIOR: 1.3,
+            iridescenceThicknessRange: [100, 400],
+        },
+        displacementScale: 1,
+        displacementBias: 0,
+    },
+    light: {
+        color: '#ffffff',
+        intensity: 1,
+        groundColor: '#000000',
+        distance: 0,
+        angle: Math.PI / 6,
+        penumbra: 0,
+        // three.js's own RectAreaLight constructor defaults (area lights only).
+        width: 10,
+        height: 10,
+    },
+    camera: {
+        fov: 60,
+        near: 0.1,
+        far: 1000,
+        orthoSize: 5,
+        width: 1920,
+        height: 1080,
+    },
+    audio: {
+        spatial: true,
+        volume: 1,
+        refDistance: 1,
+        rolloffFactor: 1,
+        maxDistance: 10000,
+        loop: false,
+        autoplay: false,
+    },
+    collider: {
+        cuboid: { halfExtents: [0.5, 0.5, 0.5] },
+        ball: { radius: 0.5 },
+        capsule: { radius: 0.25, halfHeight: 0.5 },
+    },
+    shadow: {
+        mapSize: 1024,
+    },
+    animation: {
+        loop: true,
+    },
+    fog: {
+        linear: { near: 1, far: 100 },
+        exponential: { density: 0.01 },
+    },
+    environment: {
+        envMapIntensity: 1.0,
+    },
+    toneMapping: {
+        // T1.13: the effective renderer default is ACES (see
+        // setup-renderer.ts's `createHostRenderer` + `applyScenePostProcessing`,
+        // which both hardcode `THREE.ACESFilmicToneMapping`/'aces' as the
+        // fallback when a scene omits `environment.toneMapping`) — NOT 'none'.
+        // This used to say 'none', silently disagreeing with the runtime and
+        // with the editor's Tone Mapping inspector dropdown.
+        mode: 'aces',
+        exposure: 1.0,
+    },
+    postProcessing: {
+        bloom: { intensity: 1.0, luminanceThreshold: 0.9, luminanceSmoothing: 0.025 },
+        vignette: { darkness: 0.5, offset: 0.5 },
+        brightnessContrast: { brightness: 0, contrast: 0 },
+        hueSaturation: { hue: 0, saturation: 0 },
+        sepia: { intensity: 1.0 },
+        colorDepth: { bits: 16 },
+        chromaticAberration: { offsetX: 0.002, offsetY: 0.002, modulationOffset: 0.15 },
+        lensDistortion: { distortionX: 0, distortionY: 0, focalLengthX: 1, focalLengthY: 1, skew: 0 },
+        depthOfField: { worldFocusDistance: 10, worldFocusRange: 5, bokehScale: 3, focalLength: 0.04 },
+        tiltShift: { offset: 0, rotation: 0, focusArea: 0.4, feather: 0.3 },
+        noise: { premultiply: false },
+        scanline: { density: 1.25 },
+        dotScreen: { angle: 1.57, scale: 1.0 },
+        grid: { scale: 1.0, lineWidth: 0.0 },
+        pixelation: { granularity: 6 },
+        glitch: {
+            delayX: 1.5,
+            delayY: 3.5,
+            durationX: 0.6,
+            durationY: 1.0,
+            strengthX: 0.3,
+            strengthY: 1.0,
+            columns: 0.05,
+            ratio: 0.85,
+        },
+        shockWave: { speed: 2, maxRadius: 1, waveSize: 0.2, amplitude: 0.05 },
+        smaa: { preset: 'high' },
+        ssao: { radius: 0.05, intensity: 2.0, bias: 0.025, samples: 16, rings: 7, fade: 0.01 },
+        n8ao: {
+            aoSamples: 16,
+            aoRadius: 5.0,
+            intensity: 5,
+            denoiseSamples: 8,
+            denoiseRadius: 12,
+            distanceFalloff: 1.0,
+        },
+        godRays: { density: 0.96, decay: 0.93, weight: 0.4, exposure: 0.6, samples: 60 },
+        outline: {
+            edgeStrength: 3,
+            pulseSpeed: 0,
+            visibleEdgeColor: '#ffffff',
+            hiddenEdgeColor: '#22090a',
+        },
+        ssr: { intensity: 1, exponent: 1, distance: 10, thickness: 10, maxRoughness: 1 },
+        ssgi: { intensity: 1, distance: 10, thickness: 10, maxRoughness: 1 },
+        motionBlur: { intensity: 1, jitter: 1, samples: 16 },
+    },
+    navigation: {
+        cellSize: 0.3,
+        cellHeight: 0.2,
+        walkableSlopeAngle: 45,
+        walkableHeight: 2,
+        walkableClimb: 1,
+        walkableRadius: 0.5,
+        maxEdgeLen: 12,
+        maxSimplificationError: 1.3,
+        minRegionArea: 8,
+        mergeRegionArea: 20,
+    },
+};

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

@@ -0,0 +1,8 @@
+/**
+ * Built-in geometry generators. Importing this module for its side effects
+ * registers the built-ins into the geometry registry. Both the runtime factory
+ * (scene-loader) and the editor factory (entity-factory) import it so generated
+ * meshes resolve on whichever side builds first.
+ */
+import './terrain';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/scene/geometries/index.js

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

package/dist/scene/geometries/terrain.d.ts

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

package/dist/scene/geometries/terrain.d.ts.map

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

package/dist/scene/geometries/terrain.js

@@ -0,0 +1,37 @@
+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, z, amplitude, frequency) {
+    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'] ?? 40;
+        const depth = params['depth'] ?? 40;
+        const segments = params['segments'] ?? 64;
+        const amplitude = params['amplitude'] ?? 3;
+        const frequency = params['frequency'] ?? 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'];
+        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/dist/scene/geometry-registry.d.ts

@@ -0,0 +1,24 @@
+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;
+}
+/** Register a geometry generator under `name`. */
+export declare function registerGeometryGenerator(name: string, def: GeometryGeneratorDef): void;
+/** Look up a registered geometry generator. */
+export declare function getGeometryGenerator(name: string): GeometryGeneratorDef | undefined;
+/**
+ * Build a procedural geometry by registered generator name. Throws if the
+ * generator is unknown (fail loud — same posture as the other registries).
+ */
+export declare function buildGeneratedGeometry(name: string, params: Record<string, unknown>): THREE.BufferGeometry;
+//# sourceMappingURL=geometry-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geometry-registry.d.ts","sourceRoot":"","sources":["../../src/scene/geometry-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC;CAC9D;AAID,kDAAkD;AAClD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,oBAAoB,GAAG,IAAI,CAEvF;AAED,+CAA+C;AAC/C,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAEnF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,KAAK,CAAC,cAAc,CAMtB"}

package/dist/scene/geometry-registry.js

@@ -0,0 +1,20 @@
+const registry = new Map();
+/** Register a geometry generator under `name`. */
+export function registerGeometryGenerator(name, def) {
+    registry.set(name, def);
+}
+/** Look up a registered geometry generator. */
+export function getGeometryGenerator(name) {
+    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, params) {
+    const def = registry.get(name);
+    if (!def) {
+        throw new Error(`Geometry generator "${name}" not found in geometry registry`);
+    }
+    return def.build(params ?? {});
+}

package/dist/scene/instance-registry.d.ts

@@ -0,0 +1,36 @@
+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[];
+}
+/** Register an instancer definition under `name`. */
+export declare function registerInstancer(name: string, def: InstancerDef): void;
+/** Look up a registered instancer. */
+export declare function getInstancer(name: string): InstancerDef | undefined;
+/**
+ * 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 declare function buildInstancedMesh(geometry: THREE.BufferGeometry, material: THREE.Material, name: string, params: Record<string, unknown>): THREE.InstancedMesh;
+/**
+ * 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 declare function buildInstancedMeshFromTuples(geometry: THREE.BufferGeometry, material: THREE.Material, tuples: InstancesFile): THREE.InstancedMesh;
+//# sourceMappingURL=instance-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instance-registry.d.ts","sourceRoot":"","sources":["../../src/scene/instance-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;CACzD;AAID,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAEvE;AAED,sCAAsC;AACtC,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,KAAK,CAAC,aAAa,CAarB;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ,EACxB,MAAM,EAAE,aAAa,GACpB,KAAK,CAAC,aAAa,CAgBrB"}

package/dist/scene/instance-registry.js

@@ -0,0 +1,55 @@
+import * as THREE from 'three';
+const registry = new Map();
+/** Register an instancer definition under `name`. */
+export function registerInstancer(name, def) {
+    registry.set(name, def);
+}
+/** Look up a registered instancer. */
+export function getInstancer(name) {
+    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, material, name, params) {
+    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, material, tuples) {
+    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/dist/scene/instancers/grid.d.ts

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

package/dist/scene/instancers/grid.d.ts.map

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

package/dist/scene/instancers/grid.js

@@ -0,0 +1,36 @@
+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'] ?? 100;
+        const countZ = params['countZ'] ?? 100;
+        const spacing = params['spacing'] ?? 2;
+        const jitter = params['jitter'] ?? 0;
+        let seed = params['seed'] ?? 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 = [];
+        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/dist/scene/instancers/index.d.ts

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

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

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

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"}