@woosh/meep-engine 2.154.0 → 2.156.0

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

@@ -0,0 +1,238 @@
+import { GameAssetType } from "../../../asset/GameAssetType.js";
+import { SoundAssetLoader } from "../../../asset/loaders/SoundAssetLoader.js";
+import { System } from "../../../ecs/System.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { AssetManagerBufferProvider } from "../../sopra/asset/AssetManagerBufferProvider.js";
+import { EventInstanceState } from "../../sopra/runtime/EventInstance.js";
+import { volume2dB } from "../../volume2dB.js";
+import SoundListener from "../SoundListener.js";
+import { AudioEmitter } from "./AudioEmitter.js";
+import { LiveEmitterSet } from "./LiveEmitterSet.js";
+
+/**
+ * Drives {@link AudioEmitter} components through the shared sopra engine — the native counterpart to
+ * the legacy `SoundEmitterSystem`. Each emitter owns its {@link EventDescription} directly (no track
+ * translation); the entity's {@link Transform} feeds position; `volume` changes plumb to the instance
+ * gain. Each frame it forwards the listener pose, refreshes the spatial live set, and ticks sopra.
+ *
+ * **Two play paths**, chosen once at {@link link} (routing is fixed for the lifetime of the link —
+ * mutating `autoplay`/`is3D` afterward does nothing without an unlink/relink):
+ * - **Spatially managed** (`autoplay && is3D && looping`): registered with a {@link LiveEmitterSet} and
+ *   left *dormant* until a refresh promotes the nearest in-range emitters up to a global voice budget —
+ *   this is what lets the system carry far more emitters than can sound at once (the 100k-bird case). A
+ *   dormant emitter costs only a BVH leaf; no instance, no nodes, no per-frame work. NOTE: for a crowd
+ *   of content-equal managed events to all sound, their `maxInstances` must be ≥ the live budget — they
+ *   share one sopra polyphony bucket (keyed by event content), so a lower cap gates the budget. Only
+ *   *looping* events are managed: the live set models a persistent source whose phase is reconstructed
+ *   on (re-)promotion — meaningless for a finite one-shot, and a dead one-shot would otherwise keep
+ *   re-promoting and occupying a budget slot — so finite events take the direct path.
+ * - **Direct** (any other `autoplay` event — 2D sounds, or finite 3D one-shots): played immediately on
+ *   link, stopped on unlink. 2D sounds (music, ambience beds) have nothing to cull by distance; a finite
+ *   3D one-shot still spatializes (its instance attenuates by position) and self-releases when it ends.
+ *
+ * Non-autoplay emitters are inert: neither played nor registered, awaiting a future explicit trigger.
+ *
+ * Shares the single {@link SopraEngine} owned by {@link SoundEngine} (created on demand, idempotent),
+ * so it coexists with the legacy `SoundEmitterSystem` during the strangler migration.
+ */
+export class AudioEmitterSystem extends System {
+    /**
+     * @param {AssetManager} assetManager
+     * @param {SoundEngine} soundEngine owns the AudioContext + master destination + sopra engine
+     * @param {{budget?:number, liveStickiness?:number, fadeOutSeconds?:number}} [liveEmitterSetOptions]
+     *        forwarded to the {@link LiveEmitterSet} that manages 3D emitters
+     */
+    constructor(assetManager, soundEngine, liveEmitterSetOptions = {}) {
+        super();
+
+        this.dependencies = [AudioEmitter, Transform];
+
+        /**
+         * @type {SoundEngine}
+         */
+        this.soundEngine = soundEngine;
+
+        /**
+         * @type {AudioContext}
+         */
+        this.webAudioContext = soundEngine.context;
+
+        /**
+         * @type {AssetManager}
+         */
+        this.assetManager = assetManager;
+
+        // Self-sufficient: register the Sound asset loader if nothing has yet (so this system works
+        // standalone, without the legacy SoundEmitterSystem). Guarded against double-registration (D7).
+        if (!assetManager.hasLoaderForType(GameAssetType.Sound)) {
+            assetManager.registerLoader(GameAssetType.Sound, new SoundAssetLoader(soundEngine.context));
+        }
+
+        /**
+         * The shared sopra engine (idempotent create — reused if the legacy system already made it).
+         * @type {SopraEngine}
+         */
+        this.sopra = soundEngine.createSopra(new AssetManagerBufferProvider(assetManager));
+
+        /**
+         * Spatial lifecycle for 3D ("managed") emitters: BVH cull → promote nearest-in-range up to the
+         * budget, demote the rest. 2D emitters bypass this and play directly.
+         * @type {LiveEmitterSet}
+         */
+        this.liveSet = new LiveEmitterSet(this.sopra, liveEmitterSetOptions);
+
+        /**
+         * Per-entity records: { emitter, transform, managed, instance, onVolume }. For a managed (3D)
+         * emitter the playing instance lives in {@link liveSet} (record.instance stays null); for a
+         * direct (2D) emitter it is held here.
+         * @type {object[]}
+         */
+        this.data = [];
+    }
+
+    /**
+     * @param {AudioEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(emitter, transform, entity) {
+        // Spatially managed = a persistent (looping) 3D autoplay source. Finite 3D one-shots and all 2D
+        // sounds take the direct path; non-autoplay emitters are inert. Routing is fixed at link. See the
+        // class doc.
+        const managed = emitter.autoplay && emitter.event.is3D && emitter.event.rootClip.loops();
+
+        const record = { emitter, transform, managed, instance: null, onVolume: null };
+
+        if (managed) {
+            this.liveSet.add(entity, emitter.event, transform.position, volume2dB(emitter.volume.getValue()));
+            record.onVolume = () => this.liveSet.setGainDb(entity, volume2dB(emitter.volume.getValue()));
+        } else {
+            if (emitter.autoplay) {
+                record.instance = this.#play(emitter, transform);
+            }
+            record.onVolume = () => this.#applyVolume(record);
+        }
+
+        emitter.volume.onChanged.add(record.onVolume);
+
+        this.data[entity] = record;
+    }
+
+    /**
+     * @param {AudioEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(emitter, transform, entity) {
+        const record = this.data[entity];
+
+        if (record === undefined) {
+            return;
+        }
+
+        delete this.data[entity];
+
+        emitter.volume.onChanged.remove(record.onVolume);
+
+        if (record.managed) {
+            this.liveSet.remove(entity); // demotes (hard cut) if live, then unregisters
+        } else if (record.instance !== null) {
+            record.instance.stop();
+            record.instance = null;
+        }
+    }
+
+    /**
+     * The currently-playing instance for an entity, or null. For a managed (3D) emitter this is the live
+     * instance only while it is promoted (null while dormant or out of range); for a direct (2D) emitter
+     * it is the instance held since link.
+     * @param {number} entity
+     * @returns {EventInstance|null}
+     */
+    instanceFor(entity) {
+        const record = this.data[entity];
+
+        if (record === undefined) {
+            return null;
+        }
+
+        if (record.managed) {
+            const instance = this.liveSet.instanceOf(entity);
+            return instance === undefined ? null : instance;
+        }
+
+        return record.instance;
+    }
+
+    /**
+     * @param {AudioEmitter} emitter
+     * @param {Transform} transform
+     * @returns {EventInstance|null}
+     */
+    #play(emitter, transform) {
+        const event = emitter.event;
+
+        // A looping event is a persistent source (plays until unlink); a finite event is a one-shot that
+        // self-releases when it finishes. oneShot ALSO arms the max-lifetime backstop, so marking a loop
+        // oneShot would wrongly kill it after maxLifetimeSeconds.
+        const oneShot = !event.rootClip.loops();
+
+        const instance = this.sopra.playEvent(event, {
+            busId: event.busId,
+            position: transform.position, // shared Vector3 — tracks the entity as it moves
+            oneShot
+        });
+
+        if (instance !== null) {
+            instance.setGainDb(volume2dB(emitter.volume.getValue()));
+        }
+
+        return instance;
+    }
+
+    /**
+     * @param {object} record
+     */
+    #applyVolume(record) {
+        const instance = record.instance;
+
+        if (instance !== null && instance.state !== EventInstanceState.Stopped) {
+            instance.setGainDb(volume2dB(record.emitter.volume.getValue()));
+        }
+    }
+
+    update(timeDelta) {
+        const sopra = this.sopra;
+
+        const ecd = this.entityManager.dataset;
+
+        let listenerPosition = null;
+
+        if (ecd !== null) {
+            const soundListener = ecd.getAnyComponent(SoundListener);
+
+            if (soundListener.entity !== -1) {
+                // A SoundListener entity is expected to also carry a Transform (SoundListenerSystem
+                // depends on both). Tolerate a misconfigured one rather than throwing every frame and
+                // freezing all audio: a missing Transform is treated as "no usable listener" (below).
+                const listenerTransform = ecd.getComponent(soundListener.entity, Transform);
+
+                if (listenerTransform !== undefined) {
+                    listenerPosition = listenerTransform.position;
+                    sopra.setListener(listenerPosition);
+                }
+            }
+        }
+
+        // Promote/demote the spatial live set (throttled internally). Refresh BEFORE the tick so a
+        // freshly-promoted instance spatializes on the same frame. With no usable listener the live set
+        // is not refreshed: never-promoted managed emitters stay dormant, while any already-live ones
+        // keep playing against the last known listener pose until a listener returns. The direct (2D)
+        // instances and the sopra tick run regardless.
+        if (listenerPosition !== null) {
+            this.liveSet.refresh(listenerPosition);
+        }
+
+        sopra.update(this.webAudioContext.currentTime);
+    }
+}

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();
+        }
+    }
+}