@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -1,345 +1,356 @@
-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, acoustic: boolean, pathing: boolean, sourceRadius: number, orientation: Quaternion|null, directivity: AcousticDirectivity|null}>}
-     */
-    #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)
-     * @param {boolean} [acoustic] opt the promoted instances into the acoustic simulation (default false)
-     * @param {boolean} [pathing] opt the promoted instances into corner-leakage render (default false)
-     * @param {number} [sourceRadius] apparent acoustic radius for volumetric occlusion (default 0.5)
-     * @param {Quaternion|null} [orientation] shared source orientation ref (tracks the entity), for directivity
-     * @param {AcousticDirectivity|null} [directivity] source radiation directivity (null = omni)
-     */
-    add(entity, event, position, gainDb = 0, acoustic = false, pathing = false, sourceRadius = 0.5, orientation = null, directivity = null) {
-        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, acoustic, pathing, sourceRadius, orientation, directivity });
-    }
-
-    /**
-     * Invoke `callback` for each currently-live instance (bounded by the budget). Used by the
-     * `AudioEmitterSystem` to feed live spatial instances to the acoustic simulation.
-     * @param {function(EventInstance):void} callback
-     */
-    forEachLive(callback) {
-        for (const instance of this.#live.values()) {
-            callback(instance);
-        }
-    }
-
-    /**
-     * 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,
-            acoustic: record.acoustic,
-            pathing: record.pathing,
-            sourceRadius: record.sourceRadius,
-            orientation: record.orientation,
-            directivity: record.directivity
-        });
-
-        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();
-        }
-    }
-}
+import { EventInstanceState } from "../../sopra/runtime/EventInstance.js";
+import { SpatialAudioIndex } from "./SpatialAudioIndex.js";
+import { v3_distance } from "../../../../core/geom/vec3/v3_distance.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, acoustic: boolean, pathing: boolean, sourceRadius: number, orientation: Quaternion|null, directivity: AcousticDirectivity|null}>}
+     */
+    #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)
+     * @param {boolean} [acoustic] opt the promoted instances into the acoustic simulation (default false)
+     * @param {boolean} [pathing] opt the promoted instances into corner-leakage render (default false)
+     * @param {number} [sourceRadius] apparent acoustic radius for volumetric occlusion (default 0.5)
+     * @param {Quaternion|null} [orientation] shared source orientation ref (tracks the entity), for directivity
+     * @param {AcousticDirectivity|null} [directivity] source radiation directivity (null = omni)
+     */
+    add(entity, event, position, gainDb = 0, acoustic = false, pathing = false, sourceRadius = 0.5, orientation = null, directivity = null) {
+        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, acoustic, pathing, sourceRadius, orientation, directivity });
+    }
+
+    /**
+     * Invoke `callback` for each currently-live instance (bounded by the budget). Used by the
+     * `AudioEmitterSystem` to feed live spatial instances to the acoustic simulation.
+     * @param {function(EventInstance):void} callback
+     */
+    forEachLive(callback) {
+        for (const instance of this.#live.values()) {
+            callback(instance);
+        }
+    }
+
+    /**
+     * 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 {number[]|Float64Array} listenerPosition reads 3 elements
+     */
+    refresh(listenerPosition) {
+        // The translations are live views over the entities' transforms, so the positions are
+        // already current - only the BVH leaves are stale, and a transform has no signal to refit
+        // them on. One pass here costs what the per-move refits cost before.
+        this.#index.refresh_all();
+
+        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);
+            // both are Float64Array-addressed: the record holds a live translation view and the
+            // listener pose comes from a transform as well
+            const distance = v3_distance(
+                record.position[0], record.position[1], record.position[2],
+                listenerPosition[0], listenerPosition[1], listenerPosition[2]
+            );
+
+            // 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,
+            acoustic: record.acoustic,
+            pathing: record.pathing,
+            sourceRadius: record.sourceRadius,
+            orientation: record.orientation,
+            directivity: record.directivity
+        });
+
+        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();
+        }
+    }
+}