@vgai/engine 0.2.0 → 0.3.0

package/dist/react/use-selection.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * W3.1 of docs/DATA-TOOLS-DESIGN.md §3.3 — `useSelection()`, the third
+ * tool-hooks contract member (alongside `useData`/`writeData` from
+ * `use-data.ts`). Where those two hooks are about DATA ASSETS, this one is
+ * about the currently-selected ENTITY and the components authored on it —
+ * the gap a real consumer (`critter-types-w3b`'s `critter-type.tool.tsx`,
+ * §9.4) hit hard: with no way to read a component's own authored config, it
+ * had to recover species from `node.label` (a display string, not data).
+ *
+ * Scope, v1:
+ *  - INSPECTOR-placement tools only (`placement: 'inspector'`,
+ *    `define-tool.ts`). `EditorSelectionProvider` is host plumbing —
+ *    `InspectorToolSection` wraps every tool render in it; dock tools
+ *    (`ToolHost`/`BottomPanel`) have no adapter/selection in scope and never
+ *    get a provider. Calling `useSelection()` there throws a teaching error,
+ *    contained by the tool's `ToolErrorBoundary` (the editor survives).
+ *  - READ-only. `config` is a shallow copy of the authored record; write
+ *    through `InspectorProvider.set('components.<Type>.<field>', v)` /
+ *    `writeData` (the existing paths), never by mutating what this hook
+ *    returns. Per-entity WRITE-from-tool is deferred with `useTunable` (§10).
+ *  - Honest degrades, not errors, when the adapter is thinner than the vgai
+ *    first-party one: no `components` provider at all ⇒ `components: []`;
+ *    a `components` provider present but with no optional `config()`
+ *    accessor ⇒ each entry still appears (from `list()`) but with
+ *    `config: null`. Both mirror the `AuthoringAdapter` optional-provider
+ *    doctrine (§4) — an ingest/UI adapter that never implements `components`
+ *    was already legal, and stays legal.
+ *
+ * Liveness — two existing paths reused, no new mechanism (§4's "reuse that
+ * path" rule):
+ *  1. Selection changes: `Inspector.tsx`'s own
+ *     `useSyncExternalStore(store.subscribe, store.getSnapshot)` re-renders
+ *     the panel, each matched `Section` gets the new `nodeId` prop, and
+ *     `InspectorToolSection` re-creates this provider's context value.
+ *  2. Config edits while the SAME node stays selected: `adapter.subscribe`
+ *     fires (the vgai adapter's store notifies on every `updateEntity`,
+ *     which is what `InspectorProvider.set` goes through) — this hook keeps
+ *     a local version counter bumped per notification (exactly
+ *     `game-state.tsx`'s `useWorldObservation` pattern: the adapter has no
+ *     snapshot/version of its own, `subscribe` is fire-only) and recomputes.
+ */
+import { createContext, useContext, useMemo, useRef, useSyncExternalStore, } from 'react';
+const SelectionContext = createContext(null);
+/**
+ * EDITOR-side host plumbing: `InspectorToolSection` wraps a tool's rendered
+ * `<Component/>` in this, passing the adapter + nodeId it already holds.
+ * Project tools never render this themselves — it exists so `useSelection()`
+ * has something to read.
+ */
+export function EditorSelectionProvider({ adapter, nodeId, children, }) {
+    const value = useMemo(() => ({ adapter, nodeId }), [adapter, nodeId]);
+    return _jsx(SelectionContext.Provider, { value: value, children: children });
+}
+/**
+ * The selected entity, live: its node, and every component attached to it
+ * with that component's own authored config (read-only — see module doc).
+ *
+ * Throws outside an `EditorSelectionProvider` — inspector tools always render
+ * inside one; a dock tool or game-code caller does not, and the error names
+ * the fix rather than failing silently.
+ */
+export function useSelection() {
+    const ctx = useContext(SelectionContext);
+    if (!ctx) {
+        throw new Error('useSelection: no editor selection in context — this hook only works inside an editor-hosted ' +
+            "INSPECTOR tool (placement: 'inspector', docs/DATA-TOOLS-DESIGN.md §3.3/§3.2). Dock tools and " +
+            'game code have no selection to read.');
+    }
+    const { adapter, nodeId } = ctx;
+    // Local version counter bumped per adapter notification — the adapter has
+    // no snapshot/version of its own, `subscribe` is fire-only (same pattern
+    // as `useWorldObservation`'s `versionRef`, game-state.tsx).
+    const versionRef = useRef(0);
+    const version = useSyncExternalStore((onStoreChange) => adapter.subscribe?.(() => {
+        versionRef.current++;
+        onStoreChange();
+    }) ?? (() => { }), () => versionRef.current);
+    return useMemo(() => {
+        const node = nodeId ? adapter.hierarchy.node(nodeId) : null;
+        const types = nodeId ? (adapter.components?.list(nodeId) ?? []) : [];
+        const components = types.map(({ type }) => ({
+            type,
+            config: nodeId ? (adapter.components?.config?.(nodeId, type) ?? null) : null,
+        }));
+        return { nodeId, node, components };
+        // `version` has no value of its own — only its CHANGE matters, as the
+        // liveness signal described above.
+    }, [adapter, nodeId, version]);
+}

package/dist/render/auto-batcher.d.ts

@@ -0,0 +1,34 @@
+import * as THREE from 'three';
+export declare class AutoBatcher {
+    /** Root the batcher owns under the scene (instanced meshes when on, entities when off). */
+    readonly root: THREE.Group<THREE.Object3DEventMap>;
+    private entities;
+    private batches;
+    private enabled;
+    /** Indices of entities whose transform changed since last sync. */
+    private dirty;
+    private touchedBatches;
+    private indexOf;
+    private optOut;
+    private batchOf;
+    private membersOf;
+    constructor(parent: THREE.Object3D, enabled?: boolean);
+    /** Register an entity (a Mesh) as the logical handle. Call build() after adding. */
+    add(entity: THREE.Mesh, optOut?: boolean): void;
+    /** Mark an entity moved this frame (dirty-tracking input). */
+    markMoved(entity: THREE.Mesh): void;
+    /** (Re)build the render representation for the current enabled state. */
+    build(): void;
+    /** Apply the dirty set to the instance buffers. Cheap when few moved. */
+    sync(): void;
+    /** Live toggle: rebuilds the representation (one-time cost, not per-frame). */
+    setEnabled(on: boolean): void;
+    isEnabled(): boolean;
+    /** Map a raycast hit on a batch back to the logical entity (editor/gameplay picking). */
+    resolvePick(intersection: THREE.Intersection): THREE.Mesh | null;
+    /** Per-frame draw-call count this batcher contributes (for stats). */
+    get drawCallCount(): number;
+    private get optOutCount();
+    private clearRoot;
+}
+//# sourceMappingURL=auto-batcher.d.ts.map

package/dist/render/auto-batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-batcher.d.ts","sourceRoot":"","sources":["../../src/render/auto-batcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAiC/B,qBAAa,WAAW;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,sCAAqB;IAElC,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAAU;IACzB,mEAAmE;IACnE,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,cAAc,CAAoB;IAG1C,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,OAAO,CAAkE;IACjF,OAAO,CAAC,SAAS,CAAoD;gBAEzD,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,UAAO;IAMlD,oFAAoF;IACpF,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,UAAQ,GAAG,IAAI;IAM7C,8DAA8D;IAC9D,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,GAAG,IAAI;IAKnC,yEAAyE;IACzE,KAAK,IAAI,IAAI;IAuCb,yEAAyE;IACzE,IAAI,IAAI,IAAI;IAmBZ,+EAA+E;IAC/E,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAM7B,SAAS,IAAI,OAAO;IAIpB,yFAAyF;IACzF,WAAW,CAAC,YAAY,EAAE,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI;IAShE,sEAAsE;IACtE,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,OAAO,KAAK,WAAW,GAItB;IAED,OAAO,CAAC,SAAS;CAOlB"}

package/dist/render/auto-batcher.js

@@ -0,0 +1,140 @@
+import * as THREE from 'three';
+const SIG = (m) => {
+    const mat = Array.isArray(m.material) ? m.material[0] : m.material;
+    return `${m.geometry.uuid}|${mat.uuid}`;
+};
+export class AutoBatcher {
+    /** Root the batcher owns under the scene (instanced meshes when on, entities when off). */
+    root = new THREE.Group();
+    entities = [];
+    batches = new Map();
+    enabled;
+    /** Indices of entities whose transform changed since last sync. */
+    dirty = new Set();
+    touchedBatches = new Set();
+    // Per-mesh bookkeeping is kept in WeakMaps, NOT on userData (the typed userData
+    // registry is reserved for documented engine keys — see user-data.ts).
+    indexOf = new WeakMap();
+    optOut = new WeakSet();
+    batchOf = new WeakMap();
+    membersOf = new WeakMap();
+    constructor(parent, enabled = true) {
+        this.enabled = enabled;
+        this.root.name = 'AutoBatcher';
+        parent.add(this.root);
+    }
+    /** Register an entity (a Mesh) as the logical handle. Call build() after adding. */
+    add(entity, optOut = false) {
+        this.indexOf.set(entity, this.entities.length);
+        if (optOut)
+            this.optOut.add(entity);
+        this.entities.push(entity);
+    }
+    /** Mark an entity moved this frame (dirty-tracking input). */
+    markMoved(entity) {
+        const i = this.indexOf.get(entity);
+        if (i !== undefined)
+            this.dirty.add(i);
+    }
+    /** (Re)build the render representation for the current enabled state. */
+    build() {
+        this.clearRoot();
+        this.batches.clear();
+        if (!this.enabled) {
+            for (const e of this.entities)
+                this.root.add(e);
+            return;
+        }
+        const m = new THREE.Matrix4();
+        // group eligible entities; opt-outs render individually
+        const groups = new Map();
+        for (const e of this.entities) {
+            if (this.optOut.has(e)) {
+                this.root.add(e);
+                continue;
+            }
+            const key = SIG(e);
+            const arr = groups.get(key) ?? [];
+            arr.push(e);
+            groups.set(key, arr);
+        }
+        for (const [key, members] of groups) {
+            const proto = members[0];
+            const mat = Array.isArray(proto.material) ? proto.material[0] : proto.material;
+            const inst = new THREE.InstancedMesh(proto.geometry, mat, members.length);
+            inst.frustumCulled = false;
+            for (let i = 0; i < members.length; i++) {
+                const e = members[i];
+                e.updateMatrix();
+                m.copy(e.matrix);
+                inst.setMatrixAt(i, m);
+                this.batchOf.set(e, { key, localIndex: i });
+            }
+            inst.instanceMatrix.needsUpdate = true;
+            this.membersOf.set(inst, members); // localIndex → entity (picking)
+            this.root.add(inst);
+            this.batches.set(key, { key, instanced: inst, members });
+        }
+    }
+    /** Apply the dirty set to the instance buffers. Cheap when few moved. */
+    sync() {
+        if (!this.enabled)
+            return;
+        const m = new THREE.Matrix4();
+        this.touchedBatches.clear();
+        for (const i of this.dirty) {
+            const e = this.entities[i];
+            const info = this.batchOf.get(e);
+            if (!info)
+                continue; // opt-out or not batched
+            const batch = this.batches.get(info.key);
+            if (!batch)
+                continue;
+            e.updateMatrix();
+            m.copy(e.matrix);
+            batch.instanced.setMatrixAt(info.localIndex, m);
+            this.touchedBatches.add(batch);
+        }
+        for (const b of this.touchedBatches)
+            b.instanced.instanceMatrix.needsUpdate = true;
+        this.dirty.clear();
+    }
+    /** Live toggle: rebuilds the representation (one-time cost, not per-frame). */
+    setEnabled(on) {
+        if (on === this.enabled)
+            return;
+        this.enabled = on;
+        this.build();
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    /** Map a raycast hit on a batch back to the logical entity (editor/gameplay picking). */
+    resolvePick(intersection) {
+        const obj = intersection.object;
+        if (obj.isInstancedMesh && intersection.instanceId != null) {
+            const members = this.membersOf.get(obj);
+            return members?.[intersection.instanceId] ?? null;
+        }
+        return obj instanceof THREE.Mesh ? obj : null;
+    }
+    /** Per-frame draw-call count this batcher contributes (for stats). */
+    get drawCallCount() {
+        return this.enabled ? this.batches.size + this.optOutCount : this.entities.length;
+    }
+    get optOutCount() {
+        let n = 0;
+        for (const e of this.entities)
+            if (this.optOut.has(e))
+                n++;
+        return n;
+    }
+    clearRoot() {
+        for (let i = this.root.children.length - 1; i >= 0; i--) {
+            const c = this.root.children[i];
+            this.root.remove(c);
+            if (c.isInstancedMesh)
+                c.dispose();
+        }
+    }
+}

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;AAoGhE,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;IAmCb,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,230 @@
+import * as THREE from 'three';
+import { getUserData } from '../scene/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}`;
+/** Nearest self/ancestor entity descriptor, if any. */
+function nearestEntity(obj) {
+    let cur = obj;
+    while (cur) {
+        const entity = getUserData(cur, 'entity');
+        if (entity)
+            return entity;
+        cur = cur.parent;
+    }
+    return undefined;
+}
+/** Explicit per-entity opt-out (`render.autoBatch === false`). */
+function entityOptOut(obj) {
+    return nearestEntity(obj)?.render?.autoBatch === false;
+}
+/**
+ * Static-batching eligibility: only entities that won't move are safe to freeze
+ * and instance. An entity with physics, behavior components, or its own animation
+ * is a likely mover → left as an ordinary draw. Plain scenery (no def, or a def
+ * with none of those) is eligible. This is the safe, transparent default; a future
+ * dynamic-batch path (markMoved-driven) can include movers.
+ */
+function isLikelyStatic(obj) {
+    const e = nearestEntity(obj);
+    if (!e)
+        return true; // un-tagged scenery
+    if (e.physics)
+        return false;
+    if (e.animation)
+        return false;
+    if (e.components && Object.keys(e.components).length > 0)
+        return false;
+    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) => {
+            const m = obj;
+            if (!m.isMesh)
+                return;
+            if (m.isInstancedMesh)
+                return;
+            if (m.isSkinnedMesh)
+                return;
+            if (m.isBatchedMesh)
+                return;
+            if (!m.visible)
+                return;
+            if (!m.geometry || !m.material || Array.isArray(m.material))
+                return;
+            if (m.material.transparent)
+                return;
+            if (this.root === m.parent)
+                return; // our own instances
+            if (entityOptOut(m))
+                return;
+            const key = SIG(m);
+            const arr = buckets.get(key) ?? [];
+            arr.push(m);
+            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. See docs/research/RENDER-SETTINGS-UX.md.
+ */
+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"}