@vgai/engine 0.5.4 → 0.5.6

package/dist/render/particles-factory.js

@@ -0,0 +1,361 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: quarks' API uses untyped FunctionJSON internally; our Zod types are structurally compatible but TS can't unify them
+/**
+ * Converts ParticlesDescriptor 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 { ApplyForce, ChangeEmitDirection, CircleEmitter, ColorGeneratorFromJSON, ColorOverLife, ConeEmitter, DonutEmitter, ForceOverLife, FrameOverLife, GravityForce, GridEmitter, HemisphereEmitter, LimitSpeedOverLife, Noise, OrbitOverLife, PointEmitter, Vector3 as QVector3, RectangleEmitter, RotationOverLife, SizeOverLife, SpeedOverLife, SphereEmitter, TurbulenceField, ValueGeneratorFromJSON, WidthOverLength, } from 'quarks.core';
+import * as THREE from 'three';
+import { ParticleSystem, RenderMode } from 'three.quarks';
+// --- Render mode mapping ---
+const RENDER_MODE_MAP = {
+    billboard: RenderMode.BillBoard,
+    stretchedBillboard: RenderMode.StretchedBillBoard,
+    mesh: RenderMode.Mesh,
+    trail: RenderMode.Trail,
+    horizontalBillboard: RenderMode.HorizontalBillBoard,
+    verticalBillboard: RenderMode.VerticalBillBoard,
+};
+// --- Texture loader (shared cache) ---
+import { textureLoader } from '../loader';
+const particleTexCache = new Map();
+function loadParticleTexture(url) {
+    const cached = particleTexCache.get(url);
+    if (cached)
+        return cached;
+    const tex = textureLoader.load(url);
+    particleTexCache.set(url, tex);
+    return tex;
+}
+// --- Helpers ---
+/** Strip keys with undefined values so exactOptionalPropertyTypes is satisfied. */
+function defined(obj) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            result[k] = v;
+    }
+    return result;
+}
+// --- Emitter shape ---
+function createEmitterShape(json) {
+    switch (json.type) {
+        case 'point':
+            return new PointEmitter();
+        case 'sphere':
+            return new SphereEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'hemisphere':
+            return new HemisphereEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'cone':
+            return new ConeEmitter(defined({
+                radius: json.radius,
+                arc: json.arc,
+                thickness: json.thickness,
+                angle: json.angle,
+            }));
+        case 'circle':
+            return new CircleEmitter(defined({ radius: json.radius, arc: json.arc, thickness: json.thickness }));
+        case 'donut':
+            return new DonutEmitter(defined({
+                radius: json.radius,
+                arc: json.arc,
+                thickness: json.thickness,
+                donutRadius: json.donutRadius,
+            }));
+        case 'rectangle':
+            return new RectangleEmitter(defined({ width: json.width, height: json.height, thickness: json.thickness }));
+        case 'grid':
+            return new GridEmitter(defined({ width: json.width, height: json.height, column: json.column, row: json.row }));
+    }
+}
+// --- Value / Color generators ---
+// Our Zod-inferred types are structurally identical to quarks' FunctionJSON
+// but TypeScript can't unify them, so we cast through the untyped bridge.
+function valueGen(json) {
+    return ValueGeneratorFromJSON(json);
+}
+function colorGen(json) {
+    return ColorGeneratorFromJSON(json);
+}
+// --- Behaviors ---
+function createBehavior(json) {
+    switch (json.type) {
+        case 'ApplyForce':
+            return new ApplyForce(new QVector3(json.direction[0], json.direction[1], json.direction[2]), valueGen(json.magnitude));
+        case 'ColorOverLife':
+            return new ColorOverLife(colorGen(json.color));
+        case 'SizeOverLife':
+            return new SizeOverLife(valueGen(json.size));
+        case 'SpeedOverLife':
+            return new SpeedOverLife(valueGen(json.speed));
+        case 'RotationOverLife':
+            return new RotationOverLife(valueGen(json.angularVelocity));
+        case 'ForceOverLife':
+            return new ForceOverLife(valueGen(json.x), valueGen(json.y), valueGen(json.z));
+        case 'OrbitOverLife':
+            return new OrbitOverLife(valueGen(json.orbitSpeed), json.axis ? new QVector3(json.axis[0], json.axis[1], json.axis[2]) : undefined);
+        case 'Noise':
+            return new Noise(valueGen(json.frequency), valueGen(json.power), json.positionAmount ? valueGen(json.positionAmount) : undefined, json.rotationAmount ? valueGen(json.rotationAmount) : undefined);
+        case 'TurbulenceField':
+            return new TurbulenceField(new QVector3(json.scale[0], json.scale[1], json.scale[2]), json.octaves, new QVector3(json.velocityMultiplier[0], json.velocityMultiplier[1], json.velocityMultiplier[2]), new QVector3(json.timeScale[0], json.timeScale[1], json.timeScale[2]));
+        case 'FrameOverLife':
+            return new FrameOverLife(valueGen(json.frame));
+        case 'LimitSpeedOverLife':
+            return new LimitSpeedOverLife(valueGen(json.speed), json.dampen);
+        case 'ChangeEmitDirection':
+            return new ChangeEmitDirection(valueGen(json.angle));
+        case 'GravityForce':
+            return new GravityForce(new QVector3(json.center[0], json.center[1], json.center[2]), json.magnitude);
+        case 'WidthOverLength':
+            return new WidthOverLength(valueGen(json.width));
+    }
+}
+// --- Material ---
+function createParticleMaterial(mat) {
+    const textures = {};
+    if (mat.map)
+        textures['map'] = loadParticleTexture(mat.map);
+    const blending = mat.blending === 'normal' ? THREE.NormalBlending : THREE.AdditiveBlending;
+    const transparent = mat.transparent !== false;
+    const depthWrite = mat.depthWrite ?? false;
+    const side = mat.side === 'back'
+        ? THREE.BackSide
+        : mat.side === 'double'
+            ? THREE.DoubleSide
+            : THREE.FrontSide;
+    if (mat.type === 'standard') {
+        return new THREE.MeshStandardMaterial({
+            color: mat.color ?? '#ffffff',
+            ...textures,
+            blending,
+            transparent,
+            depthWrite,
+            side,
+        });
+    }
+    return new THREE.MeshBasicMaterial({
+        color: mat.color ?? '#ffffff',
+        ...textures,
+        blending,
+        transparent,
+        depthWrite,
+        side,
+    });
+}
+// --- Default sprite texture (soft radial gradient) ---
+let _defaultSpriteTex = null;
+function getDefaultSpriteTex() {
+    if (_defaultSpriteTex)
+        return _defaultSpriteTex;
+    const canvas = document.createElement('canvas');
+    canvas.width = 16;
+    canvas.height = 16;
+    const c2d = canvas.getContext('2d');
+    const grad = c2d.createRadialGradient(8, 8, 0, 8, 8, 8);
+    grad.addColorStop(0, 'rgba(255,255,255,1)');
+    grad.addColorStop(1, 'rgba(255,255,255,0)');
+    c2d.fillStyle = grad;
+    c2d.fillRect(0, 0, 16, 16);
+    _defaultSpriteTex = new THREE.CanvasTexture(canvas);
+    return _defaultSpriteTex;
+}
+/**
+ * Create a three.quarks ParticleSystem from ParticlesDescriptor JSON data.
+ *
+ * `objects` carries the pieces a JSON descriptor cannot: a plugin emitter
+ * shape, a mesh-mode instancing geometry, and the default-sprite toggle. It is
+ * optional and additive — a call with only `data` behaves exactly as before.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward field-by-field mapping
+export function createParticleSystemFromData(data, objects) {
+    const material = createParticleMaterial(data.material);
+    // Apply default sprite if no texture specified (unless the caller opts out to
+    // keep a map-less material faithful to its source).
+    if ((objects?.defaultSprite ?? true) && !data.material.map && 'map' in material) {
+        material.map = getDefaultSpriteTex();
+    }
+    // Build params, strip undefined keys for exactOptionalPropertyTypes compat
+    const params = { material };
+    if (data.autoDestroy != null)
+        params['autoDestroy'] = data.autoDestroy;
+    if (data.looping != null)
+        params['looping'] = data.looping;
+    if (data.prewarm != null)
+        params['prewarm'] = data.prewarm;
+    if (data.duration != null)
+        params['duration'] = data.duration;
+    // A pre-built shape (a distribution the JSON cannot express) wins over the
+    // descriptor's own shape; otherwise build the shape from JSON.
+    if (objects?.shape)
+        params['shape'] = objects.shape;
+    else if (data.shape)
+        params['shape'] = createEmitterShape(data.shape);
+    if (objects?.instancingGeometry)
+        params['instancingGeometry'] = objects.instancingGeometry;
+    if (data.startLife)
+        params['startLife'] = valueGen(data.startLife);
+    if (data.startSpeed)
+        params['startSpeed'] = valueGen(data.startSpeed);
+    if (data.startSize)
+        params['startSize'] = valueGen(data.startSize);
+    if (data.startRotation)
+        params['startRotation'] = valueGen(data.startRotation);
+    if (data.startColor)
+        params['startColor'] = colorGen(data.startColor);
+    if (data.startTileIndex)
+        params['startTileIndex'] = valueGen(data.startTileIndex);
+    // Trail mode requires startLength inside rendererEmitterSettings, not as a top-level param
+    if (data.renderMode === 'trail' && data.startLength) {
+        params['rendererEmitterSettings'] = { startLength: valueGen(data.startLength) };
+    }
+    if (data.emissionOverTime)
+        params['emissionOverTime'] = valueGen(data.emissionOverTime);
+    if (data.emissionOverDistance)
+        params['emissionOverDistance'] = valueGen(data.emissionOverDistance);
+    if (data.emissionBursts) {
+        params['emissionBursts'] = data.emissionBursts.map((b) => ({
+            time: b.time,
+            count: valueGen(b.count),
+            cycle: b.cycle ?? 1,
+            interval: b.interval ?? 0,
+            probability: b.probability ?? 1,
+        }));
+    }
+    if (data.behaviors)
+        params['behaviors'] = data.behaviors.map(createBehavior);
+    if (data.renderMode != null)
+        params['renderMode'] = RENDER_MODE_MAP[data.renderMode];
+    if (data.worldSpace != null)
+        params['worldSpace'] = data.worldSpace;
+    if (data.renderOrder != null)
+        params['renderOrder'] = data.renderOrder;
+    if (data.uTileCount != null)
+        params['uTileCount'] = data.uTileCount;
+    if (data.vTileCount != null)
+        params['vTileCount'] = data.vTileCount;
+    if (data.blendTiles != null)
+        params['blendTiles'] = data.blendTiles;
+    if (data.softParticles != null)
+        params['softParticles'] = data.softParticles;
+    if (data.softFarFade != null)
+        params['softFarFade'] = data.softFarFade;
+    if (data.softNearFade != null)
+        params['softNearFade'] = data.softNearFade;
+    const ps = new ParticleSystem(params);
+    return { emitter: ps.emitter, system: ps };
+}
+/**
+ * Patch a RUNNING ParticleSystem in place from ParticlesDescriptor JSON — the
+ * editor's live-tune path (W1b). Unlike `createParticleSystemFromData`, this
+ * does NOT recreate the system: the particle pool, per-particle ages, and the
+ * emission clock all survive, so a curve-key drag reshapes the live emitter
+ * with no restart stutter.
+ *
+ * Covers the live-tunable subset: lifecycle scalars (duration/looping/
+ * prewarm), emitter shape, start-value generators, emission rates + bursts,
+ * and the behavior stack (behavior instances are rebuilt from JSON — quarks
+ * behaviors read their generators per-update, so existing particles pick the
+ * new curves up on the next frame).
+ *
+ * NOT covered (these change the render batch and must go through the normal
+ * teardown/rebuild path): material, renderMode, tiling/soft-particle render
+ * settings, worldSpace.
+ */
+export function applyParticlesDataLive(system, data) {
+    if (data.duration != null)
+        system.duration = data.duration;
+    if (data.looping != null)
+        system.looping = data.looping;
+    if (data.prewarm != null)
+        system.prewarm = data.prewarm;
+    if (data.shape)
+        system.emitterShape = createEmitterShape(data.shape);
+    if (data.startLife)
+        system.startLife = valueGen(data.startLife);
+    if (data.startSpeed)
+        system.startSpeed = valueGen(data.startSpeed);
+    if (data.startSize)
+        system.startSize = valueGen(data.startSize);
+    if (data.startRotation)
+        system.startRotation = valueGen(data.startRotation);
+    if (data.startColor)
+        system.startColor = colorGen(data.startColor);
+    if (data.startTileIndex)
+        system.startTileIndex = valueGen(data.startTileIndex);
+    if (data.emissionOverTime)
+        system.emissionOverTime = valueGen(data.emissionOverTime);
+    if (data.emissionOverDistance)
+        system.emissionOverDistance = valueGen(data.emissionOverDistance);
+    system.emissionBursts = (data.emissionBursts ?? []).map((b) => ({
+        time: b.time,
+        count: valueGen(b.count),
+        cycle: b.cycle ?? 1,
+        interval: b.interval ?? 0,
+        probability: b.probability ?? 1,
+    }));
+    system.behaviors = (data.behaviors ?? []).map(createBehavior);
+}
+/**
+ * Scrub a ParticleSystem to an absolute time by deterministic re-simulation:
+ * restart, then advance in fixed steps to `time`, then pause. Used by the
+ * editor's emitter-transport time scrub. `update` is TS-private on
+ * ParticleSystem but is exactly what BatchedRenderer.update calls per system.
+ */
+export function scrubParticleSystemTo(system, time, step = 1 / 60) {
+    system.restart();
+    const target = Math.max(0, time);
+    let t = 0;
+    while (t < target) {
+        const dt = Math.min(step, target - t);
+        system.update(dt);
+        t += dt;
+    }
+    system.pause();
+}
+/**
+ * Register a particle system with a BatchedRenderer.
+ */
+export function registerParticleSystem(batchedRenderer, system) {
+    batchedRenderer.addSystem(system);
+}
+/**
+ * Unregister a particle system from a BatchedRenderer.
+ */
+export function unregisterParticleSystem(batchedRenderer, system) {
+    batchedRenderer.deleteSystem(system);
+}
+/**
+ * Default particle data for creating a new particle emitter via AddSectionMenu.
+ */
+export function defaultParticlesData() {
+    return {
+        looping: true,
+        duration: 2,
+        shape: { type: 'cone', radius: 0.1, angle: 0.3 },
+        startLife: { type: 'IntervalValue', a: 0.5, b: 1.5 },
+        startSpeed: { type: 'IntervalValue', a: 1, b: 3 },
+        startSize: { type: 'IntervalValue', a: 0.05, b: 0.15 },
+        startColor: {
+            type: 'ConstantColor',
+            color: { r: 1, g: 0.8, b: 0.2, a: 1 },
+        },
+        emissionOverTime: { type: 'ConstantValue', value: 30 },
+        behaviors: [
+            {
+                type: 'SizeOverLife',
+                size: {
+                    type: 'PiecewiseBezier',
+                    functions: [{ function: { p0: 1, p1: 0.67, p2: 0.33, p3: 0 }, start: 0 }],
+                },
+            },
+        ],
+        material: {
+            type: 'basic',
+            blending: 'additive',
+            transparent: true,
+            depthWrite: false,
+        },
+    };
+}

package/dist/render/render-batch-system.d.ts

@@ -0,0 +1,33 @@
+import * as THREE from 'three';
+import type { ResolvedRenderSettings } from './render-settings';
+export declare class RenderBatchSystem {
+    private scene;
+    private settings;
+    private root;
+    private groups;
+    private dynamicGroups;
+    private parentOf;
+    private membersOf;
+    constructor(scene: THREE.Scene, settings: ResolvedRenderSettings);
+    /** Scan the scene and build instanced groups. Idempotent (rebuilds). */
+    build(): void;
+    private makeGroup;
+    /**
+     * Per-frame sync for DYNAMIC groups only (static are detached & immutable → free).
+     * Called in the preRender phase. Refreshes world matrices once (the engine's movers
+     * set matrixWorldNeedsUpdate via physics/animation), then re-writes only the instances
+     * whose source moved (element-wise cache compare). No-op when there are no movers.
+     */
+    update(): void;
+    /**
+     * Raycast against the batched instances, mapping a hit back to the logical source
+     * Object3D (so editor/gameplay picking still resolves a detached entity).
+     */
+    raycast(raycaster: THREE.Raycaster): THREE.Mesh | null;
+    /** Number of draw calls the batcher contributes (1 per group). */
+    get drawCalls(): number;
+    /** How many source meshes were collapsed into instances. */
+    get batchedCount(): number;
+    teardown(): void;
+}
+//# sourceMappingURL=render-batch-system.d.ts.map

package/dist/render/render-batch-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-batch-system.d.ts","sourceRoot":"","sources":["../../src/render/render-batch-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAgGhE,qBAAa,iBAAiB;IAU1B,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAVlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAe;IAEpC,OAAO,CAAC,QAAQ,CAA6C;IAE7D,OAAO,CAAC,SAAS,CAAoD;gBAG3D,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,QAAQ,EAAE,sBAAsB;IAM1C,wEAAwE;IACxE,KAAK,IAAI,IAAI;IA0Bb,OAAO,CAAC,SAAS;IAyCjB;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAyBd;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI;IAStD,kEAAkE;IAClE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,4DAA4D;IAC5D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,QAAQ,IAAI,IAAI;CAiBjB"}

package/dist/render/render-batch-system.js

@@ -0,0 +1,223 @@
+import * as THREE from 'three';
+import { getUserData } from '../ecs/user-data';
+// Structural signature — groups meshes that are VALUE-identical, not object-identical.
+// The engine scene-loader instantiates a fresh geometry+material per entity (no dedup),
+// so keying on .uuid would never batch a real scene. Keying on geometry type+parameters
+// and material type+key-props groups identical authored primitives (e.g. 10k boxes of
+// the same size+color → one batch). Non-primitive geometry (GLTF, no `.parameters`)
+// falls back to uuid → it simply won't group, which is the safe default.
+const geoKey = (g) => {
+    const params = g.parameters;
+    return params ? `${g.type}:${JSON.stringify(params)}` : `uuid:${g.uuid}`;
+};
+const matKey = (m) => {
+    const s = m;
+    const col = s.color?.getHexString?.() ?? '';
+    const map = s.map?.uuid ?? '';
+    return `${m.type}:${col}:${s.roughness ?? ''}:${s.metalness ?? ''}:${map}:${m.side}:${m.transparent}:${m.vertexColors}`;
+};
+const SIG = (m) => 
+// include shadow flags: meshes with different cast/receive must not share a batch
+// (the InstancedMesh carries one flag for the whole group).
+`${geoKey(m.geometry)}|${matKey(m.material)}|${m.castShadow ? 1 : 0}${m.receiveShadow ? 1 : 0}`;
+/** Match Three.js renderer visibility: a hidden ancestor hides the whole subtree. */
+function isEffectivelyVisible(obj) {
+    let cur = obj;
+    while (cur) {
+        if (!cur.visible)
+            return false;
+        cur = cur.parent;
+    }
+    return true;
+}
+function isBatchCandidate(object, batchRoot) {
+    const mesh = object;
+    if (!mesh.isMesh)
+        return false;
+    if (mesh.isInstancedMesh)
+        return false;
+    if (mesh.isSkinnedMesh)
+        return false;
+    if (mesh.isBatchedMesh)
+        return false;
+    if (!isEffectivelyVisible(mesh))
+        return false;
+    if (!mesh.geometry || !mesh.material || Array.isArray(mesh.material))
+        return false;
+    if (mesh.material.transparent)
+        return false;
+    return batchRoot !== mesh.parent;
+}
+/**
+ * Static-batching eligibility: only objects that won't move are safe to freeze
+ * and instance. An object (or an ancestor) carrying its own animation mixer is
+ * a likely mover → left as an ordinary draw. Plain scenery is eligible. This is
+ * the safe, transparent default; a future dynamic-batch path (markMoved-driven)
+ * can include movers.
+ */
+function isLikelyStatic(obj) {
+    let cur = obj;
+    while (cur) {
+        if (getUserData(cur, '_animMixer'))
+            return false;
+        cur = cur.parent;
+    }
+    return true;
+}
+export class RenderBatchSystem {
+    scene;
+    settings;
+    root = new THREE.Group();
+    groups = [];
+    dynamicGroups = []; // subset needing per-frame sync
+    // Original parent of each detached (static) source, to re-attach on teardown.
+    parentOf = new WeakMap();
+    // instanceId mapping for raycast: which group + slot an InstancedMesh belongs to.
+    membersOf = new WeakMap();
+    constructor(scene, settings) {
+        this.scene = scene;
+        this.settings = settings;
+        this.root.name = 'RenderBatchSystem';
+        this.root.matrixAutoUpdate = false; // instances carry world matrices directly
+    }
+    /** Scan the scene and build instanced groups. Idempotent (rebuilds). */
+    build() {
+        this.teardown();
+        this.scene.add(this.root);
+        this.scene.updateMatrixWorld(true);
+        // collect eligible candidates, grouped by (geometry, material)
+        const buckets = new Map();
+        this.scene.traverse((obj) => {
+            if (!isBatchCandidate(obj, this.root))
+                return;
+            const key = SIG(obj);
+            const arr = buckets.get(key) ?? [];
+            arr.push(obj);
+            buckets.set(key, arr);
+        });
+        // Each signature bucket is partitioned into STATIC (detached, zero-cost) and
+        // DYNAMIC (kept in-place, dirty-synced) members, each ≥2 forming its own batch.
+        for (const bucket of buckets.values()) {
+            const staticMembers = [];
+            const dynamicMembers = [];
+            for (const m of bucket)
+                (isLikelyStatic(m) ? staticMembers : dynamicMembers).push(m);
+            if (staticMembers.length >= 2)
+                this.makeGroup(staticMembers, false);
+            if (dynamicMembers.length >= 2)
+                this.makeGroup(dynamicMembers, true);
+        }
+    }
+    makeGroup(sources, dynamic) {
+        const frustum = this.settings['frustumCulling'] !== false;
+        const tmp = new THREE.Matrix4();
+        const proto = sources[0];
+        const inst = new THREE.InstancedMesh(proto.geometry, proto.material, sources.length);
+        inst.frustumCulled = frustum && !dynamic; // moving batches can leave the padded sphere
+        // Inherit shadow flags from the prototype so batched objects still cast/receive
+        // shadows (otherwise detaching the sources would silently drop them from shadows).
+        inst.castShadow = proto.castShadow;
+        inst.receiveShadow = proto.receiveShadow;
+        const cache = dynamic ? new Float32Array(sources.length * 16) : undefined;
+        for (let i = 0; i < sources.length; i++) {
+            const s = sources[i];
+            tmp.copy(s.matrixWorld);
+            inst.setMatrixAt(i, tmp);
+            if (dynamic) {
+                // keep the source in the graph (physics/animation still updates its matrixWorld),
+                // just hide its own draw; we copy its world matrix into the instance each frame.
+                cache.set(tmp.elements, i * 16);
+                s.visible = false;
+            }
+            else if (s.parent) {
+                // static: detach entirely so the renderer never walks it (zero per-frame cost)
+                this.parentOf.set(s, s.parent);
+                s.parent.remove(s);
+            }
+        }
+        inst.instanceMatrix.needsUpdate = true;
+        if (frustum && !dynamic)
+            inst.computeBoundingSphere();
+        this.membersOf.set(inst, sources);
+        this.root.add(inst);
+        const group = cache
+            ? { instanced: inst, sources, dynamic, cache }
+            : { instanced: inst, sources, dynamic };
+        this.groups.push(group);
+        if (dynamic)
+            this.dynamicGroups.push(group);
+    }
+    /**
+     * Per-frame sync for DYNAMIC groups only (static are detached & immutable → free).
+     * Called in the preRender phase. Refreshes world matrices once (the engine's movers
+     * set matrixWorldNeedsUpdate via physics/animation), then re-writes only the instances
+     * whose source moved (element-wise cache compare). No-op when there are no movers.
+     */
+    update() {
+        if (this.dynamicGroups.length === 0)
+            return;
+        this.scene.updateMatrixWorld(false); // refresh moved subtrees (force=false → cheap)
+        for (const g of this.dynamicGroups) {
+            const cache = g.cache;
+            let dirty = false;
+            for (let i = 0; i < g.sources.length; i++) {
+                const el = g.sources[i].matrixWorld.elements;
+                const off = i * 16;
+                let changed = false;
+                for (let k = 0; k < 16; k++) {
+                    if (el[k] !== cache[off + k]) {
+                        changed = true;
+                        break;
+                    }
+                }
+                if (!changed)
+                    continue;
+                g.instanced.setMatrixAt(i, g.sources[i].matrixWorld);
+                cache.set(el, off);
+                dirty = true;
+            }
+            if (dirty)
+                g.instanced.instanceMatrix.needsUpdate = true;
+        }
+    }
+    /**
+     * Raycast against the batched instances, mapping a hit back to the logical source
+     * Object3D (so editor/gameplay picking still resolves a detached entity).
+     */
+    raycast(raycaster) {
+        const hits = raycaster.intersectObject(this.root, true);
+        for (const h of hits) {
+            const members = this.membersOf.get(h.object);
+            if (members && h.instanceId != null)
+                return members[h.instanceId] ?? null;
+        }
+        return null;
+    }
+    /** Number of draw calls the batcher contributes (1 per group). */
+    get drawCalls() {
+        return this.groups.length;
+    }
+    /** How many source meshes were collapsed into instances. */
+    get batchedCount() {
+        return this.groups.reduce((n, g) => n + g.sources.length, 0);
+    }
+    teardown() {
+        for (const g of this.groups) {
+            for (const s of g.sources) {
+                if (g.dynamic)
+                    s.visible = true; // dynamic sources stayed in-graph, hidden
+                else {
+                    const parent = this.parentOf.get(s); // static sources were detached — re-attach
+                    if (parent)
+                        parent.add(s);
+                }
+            }
+            g.instanced.dispose();
+            this.root.remove(g.instanced);
+        }
+        this.groups = [];
+        this.dynamicGroups = [];
+        if (this.root.parent)
+            this.root.parent.remove(this.root);
+    }
+}

package/dist/render/render-features.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/**
+ * The render-feature registry — single source of truth for every togglable render
+ * setting. The scene schema (`SceneEnvironment.rendering`, `SceneEntity.render`),
+ * the cascade resolver (`resolveRenderSettings`), the editor UI, and the stats
+ * overlay are all derived from this list, so "everything togglable" stays
+ * consistent by construction (same posture as the component/material/instancer
+ * registries). Adding a feature here gives it a schema field + cascade entry for
+ * free..
+ */
+export type RenderFeatureValue = boolean | number | string;
+export interface RenderFeature {
+    /** Stable key used in schema, cascade, and UI. */
+    key: string;
+    /** Editor display label. */
+    label: string;
+    /** Schema `.describe()` text (powers JSON Schema / inspector docs). */
+    description: string;
+    /** Control shape. */
+    kind: 'toggle' | 'number' | 'enum';
+    /** Engine default — the "fast by default" baseline. */
+    default: RenderFeatureValue;
+    /**
+     * `live` re-applies on change; `reload` needs a renderer re-init (e.g. backend,
+     * antialias). The editor badges `reload` features and re-inits the viewport.
+     */
+    apply: 'live' | 'reload';
+    /** Whether this feature may be overridden per-entity (the entity cascade layer). */
+    perEntity: boolean;
+    /** Allowed values for `enum` kind. */
+    options?: readonly string[];
+    /** [min, max] for `number` kind. */
+    range?: readonly [number, number];
+}
+export declare const RENDER_FEATURES: readonly RenderFeature[];
+/** Map for O(1) lookup by key. */
+export declare const RENDER_FEATURE_BY_KEY: ReadonlyMap<string, RenderFeature>;
+/**
+ * Build a Zod object for the render settings, derived from the registry so the
+ * schema can never drift from the feature list. All fields optional — absence
+ * means "inherit" in the cascade. `perEntityOnly` builds the per-entity override
+ * schema (only features whose `perEntity` is true).
+ */
+export declare function buildRenderingZod(opts?: {
+    perEntityOnly?: boolean;
+}): z.ZodTypeAny;
+//# sourceMappingURL=render-features.d.ts.map

package/dist/render/render-features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-features.d.ts","sourceRoot":"","sources":["../../src/render/render-features.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACnC,uDAAuD;IACvD,OAAO,EAAE,kBAAkB,CAAC;IAC5B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,oCAAoC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EA6EnD,CAAC;AAEF,kCAAkC;AAClC,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAEpE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,CAAC,CAAC,UAAU,CAiBtF"}