@vgai/engine 0.2.0 → 0.3.0

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

package/dist/scene/parse.js

@@ -0,0 +1,179 @@
+import { checkSceneVersionInRange } from './scene-version';
+import { InstancesFileSchema, MaterialFileSchema, PrefabFileSchema, SceneFileSchema, } from './schema';
+export class SceneParseError extends Error {
+    issues;
+    /** The offending file's path/URL, when the caller knows it (T4.6). */
+    filePath;
+    constructor(issues, filePath) {
+        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;
+    }
+}
+// ---------------------------------------------------------------------------
+// D8 — removed-format migration guard: declarative property tracks
+// (`animation.tracks`) were deleted (spec §3.2/§10 D8; Theatre — `@theatre/core`
+// — is the sole authored continuous-animation source now). `SceneAnimationSchema`
+// no longer declares a `tracks` field at all (so the generated JSON schema stays
+// clean), which means Zod's default object mode would otherwise silently STRIP
+// an authored `animation.tracks` rather than reporting it — violating Global AC
+// §6 ("Removed formats fail with a concise migration/removal error rather than
+// being partially read"). This walks the RAW pre-Zod JSON (Zod would already
+// have stripped `tracks` by the time any schema-level check could see it) and
+// throws a `SceneParseError` before Zod ever parses the data. Matches on the
+// literal key `animation` (singular, an object) carrying a `tracks` property —
+// this is deliberately narrower than Scene UI's unrelated, RETAINED
+// `ui[].animations[].tracks` (plural `animations`), which this guard must not
+// trip on.
+// ---------------------------------------------------------------------------
+/** True when `value` is a plain object (not an array) carrying a `tracks` property — the shape
+ * `SceneAnimationSchema` used to declare before D8 deleted it. */
+function isRemovedTracksAnimation(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value) && 'tracks' in value;
+}
+function findRemovedPropertyTrackPathInArray(node, path) {
+    for (let i = 0; i < node.length; i++) {
+        const hit = findRemovedPropertyTrackPath(node[i], `${path}[${i}]`);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function findRemovedPropertyTrackPathInObject(obj, path) {
+    if (isRemovedTracksAnimation(obj['animation'])) {
+        return `${path ? `${path}.` : ''}animation.tracks`;
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        const hit = findRemovedPropertyTrackPath(value, path ? `${path}.${key}` : key);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function findRemovedPropertyTrackPath(node, path) {
+    if (Array.isArray(node))
+        return findRemovedPropertyTrackPathInArray(node, path);
+    if (node && typeof node === 'object') {
+        return findRemovedPropertyTrackPathInObject(node, path);
+    }
+    return undefined;
+}
+function assertNoRemovedPropertyTracks(json, filePath) {
+    const hit = findRemovedPropertyTrackPath(json, '');
+    if (!hit)
+        return;
+    const issue = {
+        code: 'custom',
+        message: 'property tracks were removed; author continuous animation with Theatre (@theatre/core) ' +
+            'instead — see docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.2/§10 D8.',
+        path: hit.split('.'),
+    };
+    throw new SceneParseError([issue], filePath);
+}
+// ---------------------------------------------------------------------------
+// E5 — removed-format migration guard: the AnimGraph state-machine runtime,
+// `.animgraph.json` format, and `SceneAnimationSchema.animGraph` field were
+// deleted (spec §3.3/§11 E5; XState + native Three `AnimationMixer` — see
+// `xstate-animation-binding.ts` — replace it). `SceneAnimationSchema` no
+// longer declares an `animGraph` field at all (so it carries zero trace in
+// the generated JSON schema), which means Zod's default object mode would
+// otherwise silently STRIP an authored `animation.animGraph` rather than
+// reporting it — violating Global AC §6. Mirrors
+// `assertNoRemovedPropertyTracks` above exactly: walks the RAW pre-Zod JSON
+// and throws a `SceneParseError` before Zod ever parses the data.
+// ---------------------------------------------------------------------------
+/** True when `value` is a plain object (not an array) carrying an `animGraph` property — the
+ * shape `SceneAnimationSchema` used to declare before E5 deleted it. */
+function isRemovedAnimGraphAnimation(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value) && 'animGraph' in value;
+}
+function findRemovedAnimGraphPathInArray(node, path) {
+    for (let i = 0; i < node.length; i++) {
+        const hit = findRemovedAnimGraphPath(node[i], `${path}[${i}]`);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function findRemovedAnimGraphPathInObject(obj, path) {
+    if (isRemovedAnimGraphAnimation(obj['animation'])) {
+        return `${path ? `${path}.` : ''}animation.animGraph`;
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        const hit = findRemovedAnimGraphPath(value, path ? `${path}.${key}` : key);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+function findRemovedAnimGraphPath(node, path) {
+    if (Array.isArray(node))
+        return findRemovedAnimGraphPathInArray(node, path);
+    if (node && typeof node === 'object') {
+        return findRemovedAnimGraphPathInObject(node, path);
+    }
+    return undefined;
+}
+function assertNoRemovedAnimGraph(json, filePath) {
+    const hit = findRemovedAnimGraphPath(json, '');
+    if (!hit)
+        return;
+    const issue = {
+        code: 'custom',
+        message: 'AnimGraph was removed; drive character animation with an XState animation machine instead ' +
+            '— see docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§5.6/§11 E5 and ' +
+            'packages/engine/src/animation/xstate-animation-binding.ts.',
+        path: hit.split('.'),
+    };
+    throw new SceneParseError([issue], filePath);
+}
+export function parseSceneFile(json, filePath) {
+    assertNoRemovedPropertyTracks(json, filePath);
+    assertNoRemovedAnimGraph(json, filePath);
+    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, filePath) {
+    assertNoRemovedPropertyTracks(json, filePath);
+    assertNoRemovedAnimGraph(json, filePath);
+    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, filePath) {
+    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, filePath) {
+    const result = InstancesFileSchema.safeParse(json);
+    if (!result.success) {
+        throw new SceneParseError(result.error.issues, filePath);
+    }
+    return result.data;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Converts SceneParticles JSON → three.quarks ParticleSystem.
+ *
+ * Shared between the editor entity-factory and the runtime scene-loader.
+ * The schema mirrors quarks' native JSON format, so most fields pass through
+ * directly to quarks' fromJSON or constructor methods.
+ */
+import * as THREE from 'three';
+import { type BatchedRenderer, ParticleSystem } from 'three.quarks';
+import type { SceneParticles } from './scene-types';
+export interface ParticleSystemResult {
+    /** The emitter Object3D (add to scene for transform) */
+    emitter: THREE.Object3D;
+    /** The ParticleSystem instance (register with BatchedRenderer) */
+    system: ParticleSystem;
+}
+/**
+ * Create a three.quarks ParticleSystem from SceneParticles JSON data.
+ */
+export declare function createParticleSystemFromData(data: SceneParticles): ParticleSystemResult;
+/**
+ * Register a particle system with a BatchedRenderer.
+ */
+export declare function registerParticleSystem(batchedRenderer: BatchedRenderer, system: ParticleSystem): void;
+/**
+ * Unregister a particle system from a BatchedRenderer.
+ */
+export declare function unregisterParticleSystem(batchedRenderer: BatchedRenderer, system: ParticleSystem): void;
+/**
+ * Default particle data for creating a new particle emitter via AddSectionMenu.
+ */
+export declare function defaultParticlesData(): SceneParticles;
+//# sourceMappingURL=particles-factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particles-factory.d.ts","sourceRoot":"","sources":["../../src/scene/particles-factory.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AA6BH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,eAAe,EAAE,cAAc,EAAc,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AA+NpD,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;IACxB,kEAAkE;IAClE,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;GAEG;AAEH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAwDvF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CA6BrD"}