@woosh/meep-engine 2.155.0 → 2.157.0

package/src/engine/sound/ecs/audio/LiveEmitterSet.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The live/dormant lifecycle for spatial audio emitters (P5.2). Wraps a {@link SpatialAudioIndex} (the
+ * BVH broadphase) and, on each {@link refresh}, promotes the nearest in-range emitters — up to a global
+ * voice budget — to live sopra {@link EventInstance}s, demoting the rest. This bounds the live-instance
+ * count (and therefore WebAudio nodes + the per-frame tick) to the budget, no matter how many emitters
+ * are registered. A registered-but-dormant emitter costs only its BVH leaf: no instance, no nodes, no
+ * per-frame work.
+ *
+ * "Voice slots" are the budget, allocated at promotion. Stealing is by distance: at budget, a closer
+ * emitter bumps a farther live one (demoted). A small stickiness keeps the live set stable so emitters
+ * near the budget cutoff don't flicker promote/demote each frame (rank hysteresis — the audible kind;
+ * range-edge churn at `distanceMax` is inaudible, gain ≈ 0 there, and is handled later with chain
+ * pooling).
+ *
+ * Demotion policy: a hard **cut** when an emitter is culled out of range (already inaudible — gain ≈ 0
+ * past `distanceMax`), a click-safe **fade** when a still-in-range live emitter loses its slot to a
+ * closer one (contention). Phase reconstruction on promote is P5.4. Intended for persistent (looping)
+ * emitters; a finite event that self-ends is dropped from the live set via its `onEnded`.
+ *
+ * Budget vs per-event polyphony — they are INDEPENDENT, composed caps. `budget` bounds the global live
+ * count; sopra's {@link VoiceManager} `EventDescription.maxInstances` (keyed by event CONTENT) bounds
+ * concurrent instances of one content-equal event. If a managed event's `maxInstances` is below the
+ * number of its content-equal emitters that can be live at once, sopra gates the budget: with
+ * `stealMode None` a promote is denied (`playEvent` → null) and the emitter stays dormant (retried each
+ * refresh — see the test); with `stealMode Oldest` sopra steals between them and the two layers fight
+ * (churn). So for spatial ambience where you want up to `budget` copies of one sound audible, give that
+ * event a `maxInstances` ≥ that count (this is a content/wiring decision finalised in P5.6).
+ */
+export class LiveEmitterSet {
+    /**
+     * @param {SopraEngine} sopra
+     * @param {{budget?:number, liveStickiness?:number, fadeOutSeconds?:number}} [options]
+     */
+    constructor(sopra: SopraEngine, { budget, liveStickiness, fadeOutSeconds }?: {
+        budget?: number;
+        liveStickiness?: number;
+        fadeOutSeconds?: number;
+    });
+    /**
+     * @returns {number} live (sounding) emitter count
+     */
+    get liveCount(): number;
+    /**
+     * @returns {number} registered emitter count
+     */
+    get size(): number;
+    /**
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    isLive(entity: number): boolean;
+    /**
+     * @param {number} entity
+     * @returns {EventInstance|undefined} the live instance, or undefined if dormant/unknown
+     */
+    instanceOf(entity: number): EventInstance | undefined;
+    /**
+     * Register an emitter (dormant until a refresh promotes it).
+     * @param {number} entity
+     * @param {EventDescription} event
+     * @param {Vector3} position shared position vector (tracked reactively by the spatial index)
+     * @param {number} [gainDb] per-emitter instance gain in dB, applied on every promotion (default 0 = unity)
+     */
+    add(entity: number, event: EventDescription, position: Vector3, gainDb?: number): void;
+    /**
+     * Set the per-emitter instance gain (dB). Updates the stored value so a future promotion replays it,
+     * and applies it immediately if the emitter is currently live. A no-op for an unknown entity, and for
+     * a fading (contention-demoted) instance — it is out of the live map, so it finishes its fade
+     * untouched and the new gain only takes effect on the next promotion.
+     * @param {number} entity
+     * @param {number} gainDb
+     */
+    setGainDb(entity: number, gainDb: number): void;
+    /**
+     * Unregister an emitter, demoting it first if live.
+     * @param {number} entity
+     */
+    remove(entity: number): void;
+    /**
+     * Recompute the live set for the current listener position: promote the nearest in-range emitters up
+     * to the budget, demote the rest. Cheap enough to call every tick — the BVH point-query is
+     * O(log n + candidates) and the diff is re-derived from {@link #live} each call (no maintained state
+     * to drift), so there is no reason to throttle it. Allocation-free apart from the per-candidate rank
+     * entries: the scratch containers are reused across calls.
+     * @param {Vector3} listenerPosition
+     */
+    refresh(listenerPosition: Vector3): void;
+    #private;
+}
+//# sourceMappingURL=LiveEmitterSet.d.ts.map

package/src/engine/sound/ecs/audio/LiveEmitterSet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LiveEmitterSet.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/LiveEmitterSet.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IA+DI;;;OAGG;IACH,6EAFW;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAA;KAAC,EAO1E;IAED;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;IAED;;;;;;OAMG;IACH,YALW,MAAM,uDAGN,MAAM,QAOhB;IAED;;;;;;;OAOG;IACH,kBAHW,MAAM,UACN,MAAM,QAehB;IAED;;;OAGG;IACH,eAFW,MAAM,QAShB;IAED;;;;;;;OAOG;IACH,yCAwDC;;CAgEJ"}

package/src/engine/sound/ecs/audio/LiveEmitterSet.js

@@ -0,0 +1,324 @@
+import { EventInstanceState } from "../../sopra/runtime/EventInstance.js";
+import { SpatialAudioIndex } from "./SpatialAudioIndex.js";
+
+/**
+ * Sort rank entries nearest-first by effective (stickiness-discounted) distance.
+ * @param {{effective:number}} a
+ * @param {{effective:number}} b
+ * @returns {number}
+ */
+function compareByEffective(a, b) {
+    return a.effective - b.effective;
+}
+
+/**
+ * The live/dormant lifecycle for spatial audio emitters (P5.2). Wraps a {@link SpatialAudioIndex} (the
+ * BVH broadphase) and, on each {@link refresh}, promotes the nearest in-range emitters — up to a global
+ * voice budget — to live sopra {@link EventInstance}s, demoting the rest. This bounds the live-instance
+ * count (and therefore WebAudio nodes + the per-frame tick) to the budget, no matter how many emitters
+ * are registered. A registered-but-dormant emitter costs only its BVH leaf: no instance, no nodes, no
+ * per-frame work.
+ *
+ * "Voice slots" are the budget, allocated at promotion. Stealing is by distance: at budget, a closer
+ * emitter bumps a farther live one (demoted). A small stickiness keeps the live set stable so emitters
+ * near the budget cutoff don't flicker promote/demote each frame (rank hysteresis — the audible kind;
+ * range-edge churn at `distanceMax` is inaudible, gain ≈ 0 there, and is handled later with chain
+ * pooling).
+ *
+ * Demotion policy: a hard **cut** when an emitter is culled out of range (already inaudible — gain ≈ 0
+ * past `distanceMax`), a click-safe **fade** when a still-in-range live emitter loses its slot to a
+ * closer one (contention). Phase reconstruction on promote is P5.4. Intended for persistent (looping)
+ * emitters; a finite event that self-ends is dropped from the live set via its `onEnded`.
+ *
+ * Budget vs per-event polyphony — they are INDEPENDENT, composed caps. `budget` bounds the global live
+ * count; sopra's {@link VoiceManager} `EventDescription.maxInstances` (keyed by event CONTENT) bounds
+ * concurrent instances of one content-equal event. If a managed event's `maxInstances` is below the
+ * number of its content-equal emitters that can be live at once, sopra gates the budget: with
+ * `stealMode None` a promote is denied (`playEvent` → null) and the emitter stays dormant (retried each
+ * refresh — see the test); with `stealMode Oldest` sopra steals between them and the two layers fight
+ * (churn). So for spatial ambience where you want up to `budget` copies of one sound audible, give that
+ * event a `maxInstances` ≥ that count (this is a content/wiring decision finalised in P5.6).
+ */
+export class LiveEmitterSet {
+
+    /**
+     * @type {SopraEngine}
+     */
+    #sopra;
+
+    /**
+     * @type {SpatialAudioIndex}
+     */
+    #index = new SpatialAudioIndex();
+
+    /**
+     * @type {number}
+     */
+    #budget;
+
+    /**
+     * Live-emitter distance discount in [0, 1]; a live emitter at distance d competes as `d * stickiness`
+     * so a newcomer must be more than that much closer to steal its slot.
+     * @type {number}
+     */
+    #stickiness;
+
+    /**
+     * Fade-out duration (seconds) when a still-in-range live emitter loses its slot to a closer one
+     * (contention) — a hard cut there would click. Demotion by cull (out of range) is an immediate stop.
+     * @type {number}
+     */
+    #fadeOutSeconds;
+
+    /**
+     * entity -> { event, position, gainDb, playingSince }. `gainDb` is the per-emitter instance gain
+     * (e.g. the owning `AudioEmitter.volume` in dB) re-applied on every promotion so it survives a
+     * demote→re-promote cycle; `playingSince` carries the continuous-clock phase (see {@link add}).
+     * @type {Map<number, {event: EventDescription, position: Vector3, gainDb: number, playingSince: number}>}
+     */
+    #emitters = new Map();
+
+    /**
+     * entity -> the live instance
+     * @type {Map<number, EventInstance>}
+     */
+    #live = new Map();
+
+    /**
+     * Reused candidate buffer for {@link SpatialAudioIndex.queryAudible} (grows, never shrinks; only
+     * `[0, count)` is valid each refresh) — keeps the cull allocation-free.
+     * @type {number[]}
+     */
+    #candidates = [];
+
+    /**
+     * Reused refresh scratch (the cull runs every tick, so it must not allocate containers per frame):
+     * `#ranked` collects `{entity, effective}` for in-range candidates to sort by distance; `#inRange` and
+     * `#target` are the in-range and nearest-budget sets; `#demoteScratch` snapshots the live entities to
+     * demote (so `#demote` can mutate `#live` mid-loop). All cleared at the top of each {@link refresh}.
+     */
+    #ranked = [];
+    #inRange = new Set();
+    #target = new Set();
+    #demoteScratch = [];
+
+    /**
+     * @param {SopraEngine} sopra
+     * @param {{budget?:number, liveStickiness?:number, fadeOutSeconds?:number}} [options]
+     */
+    constructor(sopra, { budget = 64, liveStickiness = 0.8, fadeOutSeconds = 0.15 } = {}) {
+        this.#sopra = sopra;
+        this.#budget = budget;
+        this.#stickiness = liveStickiness;
+        this.#fadeOutSeconds = fadeOutSeconds;
+    }
+
+    /**
+     * @returns {number} live (sounding) emitter count
+     */
+    get liveCount() {
+        return this.#live.size;
+    }
+
+    /**
+     * @returns {number} registered emitter count
+     */
+    get size() {
+        return this.#emitters.size;
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    isLive(entity) {
+        return this.#live.has(entity);
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {EventInstance|undefined} the live instance, or undefined if dormant/unknown
+     */
+    instanceOf(entity) {
+        return this.#live.get(entity);
+    }
+
+    /**
+     * Register an emitter (dormant until a refresh promotes it).
+     * @param {number} entity
+     * @param {EventDescription} event
+     * @param {Vector3} position shared position vector (tracked reactively by the spatial index)
+     * @param {number} [gainDb] per-emitter instance gain in dB, applied on every promotion (default 0 = unity)
+     */
+    add(entity, event, position, gainDb = 0) {
+        this.#index.add(entity, event, position);
+        // playingSince: continuous-clock semantics — the emitter has been "playing" since it linked, so a
+        // later promotion resumes the loop at the phase it should be at (see #promote + EventInstance startTime).
+        this.#emitters.set(entity, { event, position, gainDb, playingSince: this.#sopra.currentTime });
+    }
+
+    /**
+     * Set the per-emitter instance gain (dB). Updates the stored value so a future promotion replays it,
+     * and applies it immediately if the emitter is currently live. A no-op for an unknown entity, and for
+     * a fading (contention-demoted) instance — it is out of the live map, so it finishes its fade
+     * untouched and the new gain only takes effect on the next promotion.
+     * @param {number} entity
+     * @param {number} gainDb
+     */
+    setGainDb(entity, gainDb) {
+        const record = this.#emitters.get(entity);
+
+        if (record === undefined) {
+            return;
+        }
+
+        record.gainDb = gainDb;
+
+        const instance = this.#live.get(entity);
+        if (instance !== undefined) {
+            instance.setGainDb(gainDb);
+        }
+    }
+
+    /**
+     * Unregister an emitter, demoting it first if live.
+     * @param {number} entity
+     */
+    remove(entity) {
+        if (this.#live.has(entity)) {
+            this.#demote(entity, false); // unlink = the entity is gone -> hard cut
+        }
+
+        this.#index.remove(entity);
+        this.#emitters.delete(entity);
+    }
+
+    /**
+     * Recompute the live set for the current listener position: promote the nearest in-range emitters up
+     * to the budget, demote the rest. Cheap enough to call every tick — the BVH point-query is
+     * O(log n + candidates) and the diff is re-derived from {@link #live} each call (no maintained state
+     * to drift), so there is no reason to throttle it. Allocation-free apart from the per-candidate rank
+     * entries: the scratch containers are reused across calls.
+     * @param {Vector3} listenerPosition
+     */
+    refresh(listenerPosition) {
+        const candidates = this.#candidates;
+        const candidateCount = this.#index.queryAudible(candidates, 0, listenerPosition);
+
+        // rank truly-in-range candidates by effective distance (live emitters get a stickiness discount)
+        const ranked = this.#ranked;
+        ranked.length = 0;
+        const inRange = this.#inRange;
+        inRange.clear();
+        for (let i = 0; i < candidateCount; i++) {
+            const entity = candidates[i];
+            const record = this.#emitters.get(entity);
+            const distance = record.position.distanceTo(listenerPosition);
+
+            // queryAudible's leaf is a conservative cube; keep only the true (spherical) in-range set
+            if (distance > record.event.distanceMax) {
+                continue;
+            }
+
+            inRange.add(entity);
+
+            const sticky = this.#live.has(entity) ? this.#stickiness : 1;
+            ranked.push({ entity, effective: distance * sticky });
+        }
+
+        ranked.sort(compareByEffective);
+
+        const target = this.#target;
+        target.clear();
+        const limit = Math.min(this.#budget, ranked.length);
+        for (let i = 0; i < limit; i++) {
+            target.add(ranked[i].entity);
+        }
+
+        // demote live emitters not in the target (snapshot first — #demote mutates #live). A demoted
+        // emitter still in range lost its slot to a closer one (contention) -> fade; one that left range
+        // is already inaudible -> hard cut.
+        const demote = this.#demoteScratch;
+        demote.length = 0;
+        for (const entity of this.#live.keys()) {
+            if (!target.has(entity)) {
+                demote.push(entity);
+            }
+        }
+        for (let i = 0; i < demote.length; i++) {
+            const entity = demote[i];
+            this.#demote(entity, inRange.has(entity));
+        }
+
+        // promote target emitters not yet live (re-derived from #live, so a denied/self-ended promotion
+        // is retried next refresh automatically)
+        for (const entity of target) {
+            if (!this.#live.has(entity)) {
+                this.#promote(entity);
+            }
+        }
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #promote(entity) {
+        const record = this.#emitters.get(entity);
+        const event = record.event;
+
+        // a looping event is persistent; a finite one self-releases when it finishes
+        const oneShot = !event.rootClip.loops();
+
+        // startTime resumes the loop at the phase it should be at given real elapsed time (continuous clock)
+        const instance = this.#sopra.playEvent(event, {
+            busId: event.busId,
+            position: record.position,
+            oneShot,
+            startTime: record.playingSince
+        });
+
+        if (instance === null) {
+            // denied by the per-event voice limit (stealMode None) — stay dormant, retry next refresh
+            return;
+        }
+
+        if (instance.state === EventInstanceState.Stopped) {
+            // a finite event whose play time already elapsed under the continuous clock self-stopped
+            // during start (playhead past its end) — nothing to track. (Loops never hit this.)
+            return;
+        }
+
+        this.#live.set(entity, instance);
+
+        // replay the emitter's gain onto the fresh instance (it starts at the event's nominal gain)
+        instance.setGainDb(record.gainDb);
+
+        // if the instance ends on its own (finite content / asset-load failure), drop the stale entry
+        instance.onEnded.add(() => {
+            if (this.#live.get(entity) === instance) {
+                this.#live.delete(entity);
+            }
+        });
+    }
+
+    /**
+     * @param {number} entity
+     * @param {boolean} fade fade out (contention — still audible) vs hard stop (culled out of range)
+     */
+    #demote(entity, fade) {
+        const instance = this.#live.get(entity);
+
+        // delete BEFORE stopping: stop() fires onEnded synchronously and that handler keys off whether
+        // this entity still maps to this instance, so removing it first makes the handler a no-op. (A
+        // faded instance keeps playing until its audio-clock deadline; it is already out of #live, so it
+        // no longer occupies a budget slot, and if the same entity is re-promoted meanwhile the new
+        // instance is a different object — the old fade's onEnded still no-ops.)
+        this.#live.delete(entity);
+
+        if (fade) {
+            instance.fadeOutAndStop(this.#fadeOutSeconds);
+        } else {
+            instance.stop();
+        }
+    }
+}

package/src/engine/sound/ecs/audio/SpatialAudioIndex.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Spatial broadphase for 3D audio emitters (P5.1, cull-only).
+ *
+ * Holds a dynamic BVH whose leaves are each emitter's AUDIBLE region — an axis-aligned box of
+ * half-extent `event.distanceMax` centred on the emitter. So "which emitters can possibly be heard
+ * from point P" is one O(log n + k) BVH point-query instead of an O(n) scan over every emitter. This
+ * is the registered/dormant tier: a registered emitter is a record plus one BVH leaf — no
+ * `EventInstance`, no WebAudio nodes, no per-frame work. Promoting in-range emitters to live instances
+ * (voice slots, stealing, fades) is layered on top later; this class only answers the cull.
+ *
+ * Leaf bounds track the emitter REACTIVELY: each leaf subscribes to its position's `onChanged`, so a
+ * still emitter costs nothing per frame and a moving one refits only when it actually moves. (meep is
+ * fully dynamic — there is no static/dynamic distinction and no per-tick refit loop.)
+ *
+ * The cull is conservative: the leaf is a cube of half-extent `distanceMax`, so its corners admit a
+ * few emitters whose true (spherical) distance slightly exceeds `distanceMax`. That is correct
+ * broadphase behaviour — the exact distance test belongs to the narrowphase (the live instance).
+ */
+export class SpatialAudioIndex {
+    /**
+     * @returns {number} number of registered emitters
+     */
+    get size(): number;
+    /**
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    has(entity: number): boolean;
+    /**
+     * Register an emitter: insert a BVH leaf sized to its audible region and start tracking its
+     * position. The entity id is the leaf's user data (so queries return entity ids).
+     *
+     * @param {number} entity non-negative integer id
+     * @param {EventDescription} event read for `distanceMax` (and retained for later promotion)
+     * @param {Vector3} position shared position vector — its `onChanged` drives leaf refits
+     */
+    add(entity: number, event: EventDescription, position: Vector3): void;
+    /**
+     * Unregister an emitter: stop tracking its position and drop its BVH leaf. No-op for an unknown
+     * entity.
+     * @param {number} entity
+     */
+    remove(entity: number): void;
+    /**
+     * Write the entity ids whose audible region contains `listenerPosition` into `out` (starting at
+     * `out_offset`) and return how many — every emitter that can possibly be heard from there (a
+     * conservative superset; see the class note), in unspecified order. Allocation-free: `out` is a
+     * caller-owned reusable buffer, grown as needed (never shrunk), so only `out[out_offset .. out_offset
+     * + count)` is meaningful — entries elsewhere may be stale from a prior query and must be ignored.
+     *
+     * @param {number[]} out caller-owned result buffer, reused across calls (grows, never shrinks)
+     * @param {number} out_offset index in `out` to start writing at
+     * @param {Vector3} listenerPosition
+     * @returns {number} number of matches written to `out`
+     */
+    queryAudible(out: number[], out_offset: number, listenerPosition: Vector3): number;
+    #private;
+}
+//# sourceMappingURL=SpatialAudioIndex.d.ts.map

package/src/engine/sound/ecs/audio/SpatialAudioIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpatialAudioIndex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/SpatialAudioIndex.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAyBI;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,YAJW,MAAM,oDAoBhB;IAED;;;;OAIG;IACH,eAFW,MAAM,QAahB;IAcD;;;;;;;;;;;OAWG;IACH,kBALW,MAAM,EAAE,cACR,MAAM,8BAEJ,MAAM,CASlB;;CACJ"}

package/src/engine/sound/ecs/audio/SpatialAudioIndex.js

@@ -0,0 +1,140 @@
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import { BvhClient } from "../../../../core/bvh2/bvh3/BvhClient.js";
+import { BVHQueryIntersectsSphere } from "../../../../core/bvh2/bvh3/query/BVHQueryIntersectsSphere.js";
+import { bvh_query_user_data_generic } from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_generic.js";
+
+/**
+ * Spatial broadphase for 3D audio emitters (P5.1, cull-only).
+ *
+ * Holds a dynamic BVH whose leaves are each emitter's AUDIBLE region — an axis-aligned box of
+ * half-extent `event.distanceMax` centred on the emitter. So "which emitters can possibly be heard
+ * from point P" is one O(log n + k) BVH point-query instead of an O(n) scan over every emitter. This
+ * is the registered/dormant tier: a registered emitter is a record plus one BVH leaf — no
+ * `EventInstance`, no WebAudio nodes, no per-frame work. Promoting in-range emitters to live instances
+ * (voice slots, stealing, fades) is layered on top later; this class only answers the cull.
+ *
+ * Leaf bounds track the emitter REACTIVELY: each leaf subscribes to its position's `onChanged`, so a
+ * still emitter costs nothing per frame and a moving one refits only when it actually moves. (meep is
+ * fully dynamic — there is no static/dynamic distinction and no per-tick refit loop.)
+ *
+ * The cull is conservative: the leaf is a cube of half-extent `distanceMax`, so its corners admit a
+ * few emitters whose true (spherical) distance slightly exceeds `distanceMax`. That is correct
+ * broadphase behaviour — the exact distance test belongs to the narrowphase (the live instance).
+ */
+export class SpatialAudioIndex {
+
+    /**
+     * @type {BVH}
+     */
+    #bvh = new BVH();
+
+    /**
+     * entity id -> { entity, event, position, bvhClient, onMove }
+     * @type {Map<number, {entity:number, event:EventDescription, position:Vector3, bvhClient:BvhClient, onMove:function}>}
+     */
+    #records = new Map();
+
+    /**
+     * Reused point-query. The sphere `[x, y, z, radius]` is mutated in place each query; radius stays 0,
+     * so the test is "listener point inside the leaf AABB".
+     * @type {number[]}
+     */
+    #querySphere = [0, 0, 0, 0];
+
+    /**
+     * @type {BVHQueryIntersectsSphere}
+     */
+    #query = BVHQueryIntersectsSphere.from(this.#querySphere);
+
+    /**
+     * @returns {number} number of registered emitters
+     */
+    get size() {
+        return this.#records.size;
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    has(entity) {
+        return this.#records.has(entity);
+    }
+
+    /**
+     * Register an emitter: insert a BVH leaf sized to its audible region and start tracking its
+     * position. The entity id is the leaf's user data (so queries return entity ids).
+     *
+     * @param {number} entity non-negative integer id
+     * @param {EventDescription} event read for `distanceMax` (and retained for later promotion)
+     * @param {Vector3} position shared position vector — its `onChanged` drives leaf refits
+     */
+    add(entity, event, position) {
+        if (this.#records.has(entity)) {
+            throw new Error(`SpatialAudioIndex: entity ${entity} already registered`);
+        }
+
+        const bvhClient = new BvhClient();
+
+        const record = { entity, event, position, bvhClient, onMove: null };
+
+        this.#writeBounds(record);          // size the leaf AABB before linking (resize no-ops the write pre-link)
+        bvhClient.link(this.#bvh, entity);  // user_data = entity id
+
+        record.onMove = () => this.#writeBounds(record);
+        position.onChanged.add(record.onMove);
+
+        this.#records.set(entity, record);
+    }
+
+    /**
+     * Unregister an emitter: stop tracking its position and drop its BVH leaf. No-op for an unknown
+     * entity.
+     * @param {number} entity
+     */
+    remove(entity) {
+        const record = this.#records.get(entity);
+
+        if (record === undefined) {
+            return;
+        }
+
+        record.position.onChanged.remove(record.onMove);
+        record.bvhClient.unlink();
+
+        this.#records.delete(entity);
+    }
+
+    /**
+     * Refit a record's leaf to `position ± distanceMax`. Called once at registration and again
+     * (reactively) whenever the position changes.
+     * @param {{event:EventDescription, position:Vector3, bvhClient:BvhClient}} record
+     */
+    #writeBounds(record) {
+        const p = record.position;
+        const d = record.event.distanceMax;
+
+        record.bvhClient.resize(p.x - d, p.y - d, p.z - d, p.x + d, p.y + d, p.z + d);
+    }
+
+    /**
+     * Write the entity ids whose audible region contains `listenerPosition` into `out` (starting at
+     * `out_offset`) and return how many — every emitter that can possibly be heard from there (a
+     * conservative superset; see the class note), in unspecified order. Allocation-free: `out` is a
+     * caller-owned reusable buffer, grown as needed (never shrunk), so only `out[out_offset .. out_offset
+     * + count)` is meaningful — entries elsewhere may be stale from a prior query and must be ignored.
+     *
+     * @param {number[]} out caller-owned result buffer, reused across calls (grows, never shrinks)
+     * @param {number} out_offset index in `out` to start writing at
+     * @param {Vector3} listenerPosition
+     * @returns {number} number of matches written to `out`
+     */
+    queryAudible(out, out_offset, listenerPosition) {
+        this.#querySphere[0] = listenerPosition.x;
+        this.#querySphere[1] = listenerPosition.y;
+        this.#querySphere[2] = listenerPosition.z;
+        // radius stays 0 -> point-in-AABB
+
+        return bvh_query_user_data_generic(out, out_offset, this.#bvh, this.#bvh.root, this.#query);
+    }
+}