@vgai/engine 0.5.4 → 0.5.6

package/dist/dev/webgl-frame-capture.d.ts

@@ -0,0 +1,134 @@
+/**
+ * First-party WebGL2 single-frame draw-call capture (W4b, F11 frame debugger).
+ *
+ * WHY FIRST-PARTY, NOT spectorjs (recorded per the "use libraries directly, no
+ * wrappers" rule): the capture seam we need is the WebGL2 context this engine
+ * ALREADY owns end-to-end (`renderer.getContext()` in
+ * `setup-three-root-adapter.ts`). spectorjs is absent from node_modules, and its
+ * actual value is a bundled inspector UI we would discard — adopting it imports
+ * ~2MB of library to keep ~10% of it, and it wraps the context with its own
+ * global patching model rather than the instance-shadow-and-restore discipline
+ * the rest of dev/ uses (see `webgl-gpu-timer.ts`, the raw-context precedent
+ * this mirrors: instance shadowing, restore-in-finally, mock-GL unit test). So
+ * we instrument the real context directly, at the one seam we control.
+ *
+ * DISCIPLINE (mirrors webgl-gpu-timer.ts):
+ *  - Patching happens ONLY inside `beginPass()` and ONLY while `armed`. Every
+ *    patch is an OWN-property shadow on the context instance; the WebGL2
+ *    prototype is NEVER touched. `endPass()` restores every original in a
+ *    `finally` (own props reassigned, prototype-inherited methods `delete`d so
+ *    the real method shows through again), so a throwing draw cannot leave the
+ *    context wrapped.
+ *  - HONESTY (adapters never fabricate): a value we cannot measure at this seam
+ *    is recorded as `null` with the reason implied by the field, never zeroed
+ *    or guessed. Program/framebuffer LABELS are capture-local identity tags
+ *    (`program#N`), not the object's real GL debug name (raw WebGL2 exposes
+ *    none). Framebuffer dimensions are only reported when cheaply knowable
+ *    (renderbuffer color attachment); a texture-attachment FBO's size is not
+ *    queryable in raw WebGL2, so it is `null`, not invented (see below —
+ *    a documented deviation from the plan's non-nullable width/height).
+ *  - Draw attribution is a single pending-annotation slot consumed by the NEXT
+ *    draw and then cleared: a second draw with no fresh annotation records
+ *    `annotation: null` (counted as unattributed), never the previous draw's.
+ */
+/** The five WebGL2 draw entry points this instrument wraps. */
+export type FrameCaptureEntryPoint = 'drawArrays' | 'drawElements' | 'drawArraysInstanced' | 'drawElementsInstanced' | 'drawRangeElements';
+/** Per-draw attribution supplied by {@link WebGLFrameCapture.annotateNextDraw}
+ *  (the render adapter derives it from the three.js object about to draw). */
+export interface DrawAnnotation {
+    object: {
+        name: string;
+        type: string;
+        entityId?: string;
+    };
+    geometry: {
+        type: string;
+        name: string;
+        attributes: string[];
+        indexed: boolean;
+    };
+    material: {
+        type: string;
+        name: string;
+    };
+}
+/** Where a draw rendered: the default framebuffer (canvas) or a bound FBO. */
+export type DrawTarget = {
+    kind: 'canvas';
+} | {
+    kind: 'framebuffer';
+    /** Color-attachment width, or `null` when not cheaply queryable
+     *  (texture attachment — raw WebGL2 has no size query). */
+    width: number | null;
+    height: number | null;
+    /** Capture-local identity tag (`framebuffer#N`), not a GL debug name. */
+    label: string | null;
+};
+export interface FrameCaptureDrawCall {
+    readonly index: number;
+    readonly entryPoint: FrameCaptureEntryPoint;
+    /** Decoded primitive mode, e.g. `'TRIANGLES'`, `'LINES'` (raw enum when
+     *  unrecognised). */
+    readonly mode: string;
+    /** Vertex/index count passed to the draw. */
+    readonly count: number;
+    /** Instance count for the instanced entry points, else `null` (not 0 —
+     *  a non-instanced draw has no instance count to report). */
+    readonly instanceCount: number | null;
+    /** Capture-local program identity (`program#N`), or `null` when no program
+     *  was bound via `useProgram`. */
+    readonly programLabel: string | null;
+    readonly target: DrawTarget;
+    /** Shadow-tracked viewport `[x, y, w, h]` at draw time. */
+    readonly viewport: readonly [number, number, number, number];
+    readonly state: {
+        readonly blend: boolean;
+        readonly depthTest: boolean;
+        readonly depthWrite: boolean;
+        readonly cull: 'front' | 'back' | 'none';
+        readonly scissor: boolean;
+    };
+    /** The annotation this draw consumed, or `null` when none was pending
+     *  (unattributed — e.g. a shadow/composer pass draw). */
+    readonly annotation: DrawAnnotation | null;
+}
+export interface FrameCapture {
+    readonly id: number;
+    /** Injected capture timestamp (ms) — see `createWebGLFrameCapture` options. */
+    readonly capturedAt: number;
+    readonly drawCalls: readonly FrameCaptureDrawCall[];
+    readonly totals: {
+        /** Draws RECORDED (excludes any dropped past the cap). */
+        readonly drawCalls: number;
+        /** Recorded draws with `annotation: null`. */
+        readonly unattributed: number;
+        /** Draws dropped because the cap was hit (0 when nothing was dropped). */
+        readonly truncated: number;
+    };
+    readonly notes: readonly string[];
+}
+export interface WebGLFrameCaptureOptions {
+    /** Injected clock for `capturedAt`; defaults to `Date.now`. Injectable so a
+     *  test gets deterministic timestamps (mirrors the profiler stamping time
+     *  through a single `now()` indirection rather than a module-level call). */
+    now?: () => number;
+    /** Hard cap on recorded draws (default 5000). Draws past it are dropped and
+     *  counted in `totals.truncated`, with a note. */
+    maxDrawCalls?: number;
+}
+export interface WebGLFrameCapture {
+    /** Arm a single capture; the NEXT `beginPass()` patches the context. */
+    arm(): void;
+    readonly armed: boolean;
+    /** If armed, shadow-patch the context. No-op otherwise (zero patching when
+     *  not armed). Must be paired with `endPass()`. */
+    beginPass(): void;
+    /** Restore all patches (in `finally`) and, if a pass was patched, return the
+     *  assembled {@link FrameCapture}. Returns `null` if `beginPass` did not
+     *  patch (was not armed). One-shot: disarms after. */
+    endPass(): FrameCapture | null;
+    /** Set the annotation the next draw will consume (then cleared). */
+    annotateNextDraw(annotation: DrawAnnotation): void;
+}
+export declare function createWebGLFrameCapture(gl: WebGL2RenderingContext, options?: WebGLFrameCaptureOptions): WebGLFrameCapture;
+//# sourceMappingURL=webgl-frame-capture.d.ts.map

package/dist/dev/webgl-frame-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl-frame-capture.d.ts","sourceRoot":"","sources":["../../src/dev/webgl-frame-capture.ts"],"names":[],"mappings":"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"}

package/dist/dev/webgl-frame-capture.js

@@ -0,0 +1,270 @@
+/**
+ * First-party WebGL2 single-frame draw-call capture (W4b, F11 frame debugger).
+ *
+ * WHY FIRST-PARTY, NOT spectorjs (recorded per the "use libraries directly, no
+ * wrappers" rule): the capture seam we need is the WebGL2 context this engine
+ * ALREADY owns end-to-end (`renderer.getContext()` in
+ * `setup-three-root-adapter.ts`). spectorjs is absent from node_modules, and its
+ * actual value is a bundled inspector UI we would discard — adopting it imports
+ * ~2MB of library to keep ~10% of it, and it wraps the context with its own
+ * global patching model rather than the instance-shadow-and-restore discipline
+ * the rest of dev/ uses (see `webgl-gpu-timer.ts`, the raw-context precedent
+ * this mirrors: instance shadowing, restore-in-finally, mock-GL unit test). So
+ * we instrument the real context directly, at the one seam we control.
+ *
+ * DISCIPLINE (mirrors webgl-gpu-timer.ts):
+ *  - Patching happens ONLY inside `beginPass()` and ONLY while `armed`. Every
+ *    patch is an OWN-property shadow on the context instance; the WebGL2
+ *    prototype is NEVER touched. `endPass()` restores every original in a
+ *    `finally` (own props reassigned, prototype-inherited methods `delete`d so
+ *    the real method shows through again), so a throwing draw cannot leave the
+ *    context wrapped.
+ *  - HONESTY (adapters never fabricate): a value we cannot measure at this seam
+ *    is recorded as `null` with the reason implied by the field, never zeroed
+ *    or guessed. Program/framebuffer LABELS are capture-local identity tags
+ *    (`program#N`), not the object's real GL debug name (raw WebGL2 exposes
+ *    none). Framebuffer dimensions are only reported when cheaply knowable
+ *    (renderbuffer color attachment); a texture-attachment FBO's size is not
+ *    queryable in raw WebGL2, so it is `null`, not invented (see below —
+ *    a documented deviation from the plan's non-nullable width/height).
+ *  - Draw attribution is a single pending-annotation slot consumed by the NEXT
+ *    draw and then cleared: a second draw with no fresh annotation records
+ *    `annotation: null` (counted as unattributed), never the previous draw's.
+ */
+const DEFAULT_MAX_DRAW_CALLS = 5000;
+/** GL primitive-mode enum → name (decoded once, from the live context). */
+function buildModeTable(gl) {
+    return new Map([
+        [gl.POINTS, 'POINTS'],
+        [gl.LINES, 'LINES'],
+        [gl.LINE_LOOP, 'LINE_LOOP'],
+        [gl.LINE_STRIP, 'LINE_STRIP'],
+        [gl.TRIANGLES, 'TRIANGLES'],
+        [gl.TRIANGLE_STRIP, 'TRIANGLE_STRIP'],
+        [gl.TRIANGLE_FAN, 'TRIANGLE_FAN'],
+    ]);
+}
+export function createWebGLFrameCapture(gl, options = {}) {
+    const nowFn = options.now ?? (() => Date.now());
+    const maxDrawCalls = options.maxDrawCalls ?? DEFAULT_MAX_DRAW_CALLS;
+    const modeTable = buildModeTable(gl);
+    // Persistent identity maps (stable labels across passes).
+    const programLabels = new Map();
+    const framebufferLabels = new Map();
+    let nextProgramId = 0;
+    let nextFramebufferId = 0;
+    let captureId = 0;
+    // Shadow-tracked GL state (updated by the wrapped setters during a pass).
+    let currentProgram = null;
+    let currentFramebuffer = null;
+    let currentViewport = [0, 0, 0, 0];
+    // Per-pass accumulators.
+    let armed = false;
+    let patched = false;
+    let drawCalls = [];
+    let truncated = 0;
+    let notes = [];
+    let pendingAnnotation = null;
+    // Saved originals for restore. Value is the original fn; a key present in
+    // `wasOwn` means it was an own property (restore by assignment), otherwise
+    // it was prototype-inherited (restore by delete).
+    const originals = new Map();
+    const wasOwn = new Set();
+    function decodeMode(mode) {
+        return modeTable.get(mode) ?? `0x${mode.toString(16)}`;
+    }
+    function labelForProgram(program) {
+        if (!program)
+            return null;
+        let label = programLabels.get(program);
+        if (label === undefined) {
+            label = `program#${nextProgramId++}`;
+            programLabels.set(program, label);
+        }
+        return label;
+    }
+    /** Best-effort color-attachment dimensions for a bound draw FBO. Only a
+     *  RENDERBUFFER color attachment is cheaply queryable in raw WebGL2; a
+     *  texture attachment is not, so this returns nulls (honest absence). All
+     *  reads are guarded — a mock/foreign context returns nulls, never throws. */
+    function measureFramebufferSize() {
+        try {
+            const type = gl.getFramebufferAttachmentParameter(gl.DRAW_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE);
+            if (type === gl.RENDERBUFFER) {
+                const rb = gl.getFramebufferAttachmentParameter(gl.DRAW_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME);
+                if (!rb)
+                    return { width: null, height: null };
+                const prev = gl.getParameter(gl.RENDERBUFFER_BINDING);
+                gl.bindRenderbuffer(gl.RENDERBUFFER, rb);
+                const width = gl.getRenderbufferParameter(gl.RENDERBUFFER, gl.RENDERBUFFER_WIDTH);
+                const height = gl.getRenderbufferParameter(gl.RENDERBUFFER, gl.RENDERBUFFER_HEIGHT);
+                gl.bindRenderbuffer(gl.RENDERBUFFER, prev);
+                return { width, height };
+            }
+        }
+        catch {
+            // Foreign/mock context or an attachment we can't introspect — degrade
+            // to unknown dimensions rather than throwing mid-capture.
+        }
+        return { width: null, height: null };
+    }
+    function currentTarget() {
+        if (!currentFramebuffer)
+            return { kind: 'canvas' };
+        let label = framebufferLabels.get(currentFramebuffer);
+        if (label === undefined) {
+            label = `framebuffer#${nextFramebufferId++}`;
+            framebufferLabels.set(currentFramebuffer, label);
+        }
+        const { width, height } = measureFramebufferSize();
+        return { kind: 'framebuffer', width, height, label };
+    }
+    function readCull() {
+        if (!gl.getParameter(gl.CULL_FACE))
+            return 'none';
+        return gl.getParameter(gl.CULL_FACE_MODE) === gl.FRONT ? 'front' : 'back';
+    }
+    function recordDraw(entryPoint, mode, count, instanceCount) {
+        if (drawCalls.length >= maxDrawCalls) {
+            truncated++;
+            pendingAnnotation = null;
+            return;
+        }
+        const annotation = pendingAnnotation;
+        pendingAnnotation = null;
+        drawCalls.push({
+            index: drawCalls.length,
+            entryPoint,
+            mode: decodeMode(mode),
+            count,
+            instanceCount,
+            programLabel: labelForProgram(currentProgram),
+            target: currentTarget(),
+            viewport: [...currentViewport],
+            state: {
+                blend: Boolean(gl.getParameter(gl.BLEND)),
+                depthTest: Boolean(gl.getParameter(gl.DEPTH_TEST)),
+                depthWrite: Boolean(gl.getParameter(gl.DEPTH_WRITEMASK)),
+                cull: readCull(),
+                scissor: Boolean(gl.getParameter(gl.SCISSOR_TEST)),
+            },
+            annotation: annotation ?? null,
+        });
+    }
+    // Cast to an index signature to shadow methods without fighting the DOM lib
+    // types on every wrapped name.
+    const target = gl;
+    function patch(name, wrapper) {
+        const original = target[name];
+        originals.set(name, original);
+        if (Object.hasOwn(gl, name))
+            wasOwn.add(name);
+        target[name] = wrapper(original.bind(gl));
+    }
+    function restoreAll() {
+        for (const [name, original] of originals) {
+            if (wasOwn.has(name))
+                target[name] = original;
+            else
+                delete target[name];
+        }
+        originals.clear();
+        wasOwn.clear();
+    }
+    function installPatches() {
+        // Seed shadow state from the live context so the first draw's viewport /
+        // framebuffer / program reflect reality even before any setter fires.
+        try {
+            const vp = gl.getParameter(gl.VIEWPORT);
+            if (vp && vp.length >= 4)
+                currentViewport = [vp[0], vp[1], vp[2], vp[3]];
+            currentFramebuffer = gl.getParameter(gl.FRAMEBUFFER_BINDING);
+            currentProgram = gl.getParameter(gl.CURRENT_PROGRAM);
+        }
+        catch {
+            // Mock context without full getParameter coverage — start from defaults.
+        }
+        patch('useProgram', (original) => (program) => {
+            currentProgram = program ?? null;
+            return original(program);
+        });
+        patch('bindFramebuffer', (original) => (bindTarget, framebuffer) => {
+            // Track the DRAW framebuffer binding (FRAMEBUFFER and DRAW_FRAMEBUFFER
+            // both affect it; READ_FRAMEBUFFER does not).
+            if (bindTarget === gl.FRAMEBUFFER || bindTarget === gl.DRAW_FRAMEBUFFER) {
+                currentFramebuffer = framebuffer ?? null;
+            }
+            return original(bindTarget, framebuffer);
+        });
+        patch('viewport', (original) => (x, y, w, h) => {
+            currentViewport = [x, y, w, h];
+            return original(x, y, w, h);
+        });
+        patch('drawArrays', (original) => (mode, first, count) => {
+            recordDraw('drawArrays', mode, count, null);
+            return original(mode, first, count);
+        });
+        patch('drawElements', (original) => (mode, count, type, offset) => {
+            recordDraw('drawElements', mode, count, null);
+            return original(mode, count, type, offset);
+        });
+        patch('drawArraysInstanced', (original) => (mode, first, count, instanceCount) => {
+            recordDraw('drawArraysInstanced', mode, count, instanceCount);
+            return original(mode, first, count, instanceCount);
+        });
+        patch('drawElementsInstanced', (original) => (mode, count, type, offset, instanceCount) => {
+            recordDraw('drawElementsInstanced', mode, count, instanceCount);
+            return original(mode, count, type, offset, instanceCount);
+        });
+        patch('drawRangeElements', (original) => (mode, start, end, count, type, offset) => {
+            recordDraw('drawRangeElements', mode, count, null);
+            return original(mode, start, end, count, type, offset);
+        });
+    }
+    return {
+        arm() {
+            armed = true;
+        },
+        get armed() {
+            return armed;
+        },
+        beginPass() {
+            if (!armed || patched)
+                return;
+            patched = true;
+            drawCalls = [];
+            truncated = 0;
+            notes = [];
+            pendingAnnotation = null;
+            installPatches();
+        },
+        endPass() {
+            if (!patched) {
+                armed = false;
+                return null;
+            }
+            try {
+                if (truncated > 0) {
+                    notes.push(`Draw list capped at ${maxDrawCalls}; ${truncated} later draw(s) were not recorded.`);
+                }
+                const unattributed = drawCalls.reduce((n, d) => n + (d.annotation === null ? 1 : 0), 0);
+                return {
+                    id: ++captureId,
+                    capturedAt: nowFn(),
+                    drawCalls: drawCalls.slice(),
+                    totals: { drawCalls: drawCalls.length, unattributed, truncated },
+                    notes: notes.slice(),
+                };
+            }
+            finally {
+                restoreAll();
+                patched = false;
+                armed = false;
+                pendingAnnotation = null;
+            }
+        },
+        annotateNextDraw(annotation) {
+            pendingAnnotation = annotation;
+        },
+    };
+}

package/dist/dev/webgl-gpu-timer.d.ts

@@ -0,0 +1,8 @@
+/** Non-blocking WebGL2 timer query; results are consumed on later frames. */
+export declare function createWebGLGpuTimer(context: WebGLRenderingContext | WebGL2RenderingContext): {
+    begin(): void;
+    end(): void;
+    poll(): number | null;
+    dispose(): void;
+};
+//# sourceMappingURL=webgl-gpu-timer.d.ts.map

package/dist/dev/webgl-gpu-timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl-gpu-timer.d.ts","sourceRoot":"","sources":["../../src/dev/webgl-gpu-timer.ts"],"names":[],"mappings":"AAKA,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,sBAAsB;;;YAsB/E,MAAM,GAAG,IAAI;;EAwBxB"}

package/dist/dev/webgl-gpu-timer.js

@@ -0,0 +1,52 @@
+/** Non-blocking WebGL2 timer query; results are consumed on later frames. */
+export function createWebGLGpuTimer(context) {
+    const gl = context;
+    const extension = gl.getExtension('EXT_disjoint_timer_query_webgl2');
+    const supported = extension !== null && typeof gl.createQuery === 'function';
+    const pending = [];
+    let active = null;
+    let latestMs = null;
+    return {
+        begin() {
+            if (!supported || active)
+                return;
+            active = gl.createQuery();
+            if (active)
+                gl.beginQuery(extension.TIME_ELAPSED_EXT, active);
+        },
+        end() {
+            if (!supported || !active)
+                return;
+            gl.endQuery(extension.TIME_ELAPSED_EXT);
+            pending.push(active);
+            active = null;
+        },
+        poll() {
+            if (!supported)
+                return null;
+            if (gl.getParameter(extension.GPU_DISJOINT_EXT)) {
+                for (const query of pending.splice(0))
+                    gl.deleteQuery(query);
+                return null;
+            }
+            while (pending.length > 0) {
+                const query = pending[0];
+                if (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE))
+                    break;
+                pending.shift();
+                latestMs = gl.getQueryParameter(query, gl.QUERY_RESULT) / 1_000_000;
+                gl.deleteQuery(query);
+            }
+            return latestMs;
+        },
+        dispose() {
+            if (active) {
+                gl.endQuery(extension.TIME_ELAPSED_EXT);
+                gl.deleteQuery(active);
+                active = null;
+            }
+            for (const query of pending.splice(0))
+                gl.deleteQuery(query);
+        },
+    };
+}

package/dist/ecs/scene-index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * `createSceneIndex` — the LIVE scene index (punchlist P2, `observe`).
+ *
+ * `scene-query.ts` answers "which objects carry tag X?" by walking the whole
+ * graph on every call, and it tells nobody when the answer changes. This
+ * module is the notified half: a tag/entity-id index kept current as objects
+ * join and leave the scene, plus the change signals a game needs so it never
+ * has to poll.
+ *
+ * ## The one event primitive is `EventTarget`
+ *
+ * There is no bus, no emitter class, no `subscribe()` returning a closure.
+ * `index.events` is a plain `EventTarget` dispatching `CustomEvent`s, and
+ * **unsubscribe is `AbortSignal`** — the platform's own answer:
+ *
+ * ```ts
+ * const ac = new AbortController();
+ * ctx.sceneIndex.events.addEventListener(
+ *   'tagadded',
+ *   (e) => console.log((e as SceneIndexEvent<'tagadded'>).detail.object.name),
+ *   { signal: ac.signal },
+ * );
+ * ac.abort(); // done — nothing to remember, nothing to leak
+ * ```
+ *
+ * {@link onSceneIndexEvent} is the same call with the detail typed for you.
+ * `index.eventsFor(obj)` is the per-object target (Roblox's `inst.Changed`):
+ * the same events, already filtered to one object, so a listener that only
+ * cares about one entity does not filter by hand.
+ *
+ * ## How the index stays live: three's own parent events, not a monkeypatch
+ *
+ * three r155+ dispatches `childadded`/`childremoved` on the **parent** from
+ * `Object3D.add`/`remove` (and therefore from `attach`, `clear`,
+ * `removeFromParent`, and R3F's reconciler, which all go through those two).
+ * The index subscribes to those two events on every object it indexes; on
+ * `childadded` it walks the new subtree, indexes it, and subscribes each
+ * node, and on `childremoved` it does the inverse. `Object3D.prototype` is
+ * NOT patched — nothing in this repo patches a library prototype.
+ *
+ * Consequences worth knowing:
+ *
+ * - **The quiet-frame cost is zero.** The index registers no system and runs
+ *   no per-frame reconcile; it does work only when three tells it something
+ *   moved. Nothing here ticks.
+ * - **Reparenting nets out to one entry.** `parent.add(obj)` removes `obj`
+ *   from its old parent first, so a move inside the indexed tree fires
+ *   `childremoved` then `childadded` — unindex, then index. The object ends
+ *   up indexed exactly once (and a listener sees an `entityremoved` followed
+ *   by an `entityadded`, which is the truth about what happened).
+ * - **Splicing `parent.children` by hand is invisible to the index**, because
+ *   it is invisible to three as well. Use `add`/`remove`.
+ *
+ * ## Tags are stored where they always were
+ *
+ * `addTag`/`removeTag` write the existing `userData['tags']` array, so
+ * `queryByTag` keeps returning the truth and nothing has to be migrated. The
+ * index is the fast, notified path over the same storage. A game that writes
+ * `userData['tags']` by hand gets a stale index — that is not prevented, it is
+ * repaired: call {@link SceneIndex.reindex} on the object.
+ *
+ * ## Attributes
+ *
+ * `getAttribute`/`setAttribute`/`deleteAttribute` are typed accessors over ONE
+ * new reserved userData key, `attributes` (registered in `ecs/user-data.ts`,
+ * `Record<string, string | number | boolean>`). They emit `attributechanged`
+ * only when the value actually changes, so a re-set of the same value is
+ * silent.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * - **No property-level `Changed` on transforms.** three does not notify on
+ *   `position.set(...)`; faking it means diffing every transform every frame,
+ *   and a signal that is really a per-frame poll is worse than no signal —
+ *   it hides its own cost. Read the transform when you need it, or drive the
+ *   change from the code that made it.
+ * - **No `Touched`.** Contact/trigger events are Rapier's, dispatched through
+ *   `ctx.collisions.onCollision`. A second path would be a second truth.
+ * - **No 2D index.** This module indexes a three graph only.
+ */
+import type * as THREE from 'three';
+/** The value types an attribute may hold — deliberately JSON-simple, so an
+ *  attribute survives serialization and network replication unchanged. */
+export type AttributeValue = string | number | boolean;
+/** The `detail` payload of every scene-index event, keyed by event type.
+ *  Every detail carries `object`, so a scene-wide listener filters without a
+ *  second lookup. */
+export interface SceneIndexEventDetails {
+    /** An object (and, one event each, its descendants) joined the indexed tree. */
+    entityadded: {
+        object: THREE.Object3D;
+    };
+    /** An object (and, one event each, its descendants) left the indexed tree. */
+    entityremoved: {
+        object: THREE.Object3D;
+    };
+    /** A tag was added via {@link SceneIndex.addTag}. */
+    tagadded: {
+        object: THREE.Object3D;
+        tag: string;
+    };
+    /** A tag was removed via {@link SceneIndex.removeTag}. */
+    tagremoved: {
+        object: THREE.Object3D;
+        tag: string;
+    };
+    /** An attribute's value changed (`value` is `undefined` after a delete;
+     *  `previous` is `undefined` when it was previously unset). */
+    attributechanged: {
+        object: THREE.Object3D;
+        name: string;
+        value: AttributeValue | undefined;
+        previous: AttributeValue | undefined;
+    };
+}
+/** Every event type `index.events` / `index.eventsFor(obj)` dispatches. */
+export type SceneIndexEventType = keyof SceneIndexEventDetails;
+/** The `CustomEvent` a given scene-index event type dispatches. */
+export type SceneIndexEvent<K extends SceneIndexEventType = SceneIndexEventType> = CustomEvent<SceneIndexEventDetails[K]>;
+/** Event-type → event, for callers that want a typed `addEventListener` map. */
+export type SceneIndexEventMap = {
+    [K in SceneIndexEventType]: SceneIndexEvent<K>;
+};
+/**
+ * `addEventListener` with the detail typed — the ONLY convenience over the
+ * platform call, and it returns nothing on purpose: unsubscribe stays
+ * `AbortSignal` (`{ signal }`), never a returned closure.
+ */
+export declare function onSceneIndexEvent<K extends SceneIndexEventType>(target: EventTarget, type: K, listener: (detail: SceneIndexEventDetails[K], event: SceneIndexEvent<K>) => void, options?: {
+    signal?: AbortSignal;
+    once?: boolean;
+}): void;
+/** The live scene index — see this module's header. */
+export interface SceneIndex {
+    /** The scene-wide signal target. Listen with `addEventListener(type, fn,
+     *  { signal })`, or {@link onSceneIndexEvent} for a typed `detail`. */
+    readonly events: EventTarget;
+    /** The per-object signal target (Roblox's `inst.Changed`): the same events,
+     *  filtered to `obj`. Created lazily and held weakly. */
+    eventsFor(obj: THREE.Object3D): EventTarget;
+    /** Every indexed object carrying `tag`, in index order. Never traverses. */
+    byTag(tag: string): readonly THREE.Object3D[];
+    /** The indexed object whose `userData['entityId']` is `id` (the first, in
+     *  index order, if a project has minted the id twice). Never traverses. */
+    byEntityId(id: string): THREE.Object3D | undefined;
+    /** True when `obj` is currently in the indexed tree. */
+    has(obj: THREE.Object3D): boolean;
+    /** Add `tag` to `obj`'s `userData['tags']` and the index; emits `tagadded`.
+     *  A no-op (and silent) when the tag is already present. Legal on an object
+     *  that has not joined the scene yet — the tag is stored, and the index
+     *  picks it up when the object is added. */
+    addTag(obj: THREE.Object3D, tag: string): void;
+    /** Remove `tag`; emits `tagremoved`. A no-op (and silent) when absent. */
+    removeTag(obj: THREE.Object3D, tag: string): void;
+    /** True when `obj` carries `tag` (reads `userData['tags']`, so it is
+     *  truthful even for an object that is not in the scene yet). */
+    hasTag(obj: THREE.Object3D, tag: string): boolean;
+    /** Read one attribute (`undefined` when unset). */
+    getAttribute(obj: THREE.Object3D, name: string): AttributeValue | undefined;
+    /** Write one attribute; emits `attributechanged` only if the value changed. */
+    setAttribute(obj: THREE.Object3D, name: string, value: AttributeValue): void;
+    /** Delete one attribute; emits `attributechanged` with `value: undefined`. */
+    deleteAttribute(obj: THREE.Object3D, name: string): void;
+    /** Re-read `obj`'s subtree from `userData` — the escape hatch for code that
+     *  wrote `userData['tags']`/`userData['entityId']` by hand. Indexes anything
+     *  in the subtree that is not indexed yet (emitting `entityadded`) and
+     *  re-syncs the tag/id entries of everything that is. */
+    reindex(obj: THREE.Object3D): void;
+    /** Drop every listener this index installed and forget everything it knows.
+     *  Called from the owning root's teardown; safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Build a live index over `root` and everything currently under it. One index
+ * per three root; the root adapter creates it and exposes it as
+ * `ctx.sceneIndex`.
+ */
+export declare function createSceneIndex(root: THREE.Object3D): SceneIndex;
+//# sourceMappingURL=scene-index.d.ts.map

package/dist/ecs/scene-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-index.d.ts","sourceRoot":"","sources":["../../src/ecs/scene-index.ts"],"names":[],"mappings":"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"}