@woosh/meep-engine 3.2.0 → 3.4.0

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

@@ -1,314 +1,338 @@
-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 {
-    dependencies = [AudioEmitter, Transform];
-
-    /**
-     * Live direct-path instances (2D + finite 3D one-shots). Tracked separately so the per-frame
-     * acoustic pass enumerates only the few direct instances + the managed live set — never all
-     * registered emitters.
-     * @type {Set<EventInstance>}
-     */
-    directInstances = new Set();
-
-    /**
-     * Reused scratch array of live acoustic instances fed to {@link acousticSim} each frame.
-     * @type {EventInstance[]}
-     */
-    acousticLive = [];
-
-    /**
-     * 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[]}
-     */
-    data = [];
-
-    /**
-     * Optional probe-baked reverb renderer (acoustic-owned, separate from sopra's static reverb).
-     * When set, it is driven once per frame from the listener position. Null = no probe reverb.
-     * @type {ProbeReverbRenderer|null}
-     */
-    probeReverb = null;
-
-    /**
-     * @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 = {}, acousticSim = null) {
-        super();
-
-        /**
-         * Optional acoustic simulation engine. When set, the system drives `acousticSim.apply(...)` over
-         * its bounded live-voice set each frame (between the live-set refresh and the sopra tick), so
-         * acoustic emitters get occlusion / transmission / medium. Null = no acoustic simulation (default).
-         * @type {AcousticSimulator|null}
-         */
-        this.acousticSim = acousticSim;
-
-        /**
-         * @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.obtainSopra(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);
-    }
-
-    /**
-     * @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) {
-            const pathing = emitter.acoustic && this.acousticSim !== null && this.acousticSim.pathing;
-            this.liveSet.add(entity, emitter.event, transform.position, volume2dB(emitter.volume.getValue()), emitter.acoustic, pathing, emitter.sourceRadius, transform.rotation, emitter.directivity);
-            record.onVolume = () => this.liveSet.setGainDb(entity, volume2dB(emitter.volume.getValue()));
-        } else {
-            if (emitter.autoplay) {
-                record.instance = this.#play(emitter, transform);
-
-                if (record.instance !== null) {
-                    this.directInstances.add(record.instance);
-                }
-            }
-            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) {
-            this.directInstances.delete(record.instance);
-            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,
-            acoustic: emitter.acoustic,
-            pathing: emitter.acoustic && this.acousticSim !== null && this.acousticSim.pathing,
-            sourceRadius: emitter.sourceRadius,
-            orientation: transform.rotation, // shared Quaternion — tracks the entity as it turns
-            directivity: emitter.directivity
-        });
-
-        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;
-        let listenerRotation = 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;
-                    listenerRotation = listenerTransform.rotation;
-                    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);
-        }
-
-        // Drive the acoustic simulation over the bounded live set (direct one-shots + managed live
-        // instances), BEFORE the tick so a fresh solution spatializes the same frame. Enumerates only the
-        // few direct instances + ≤ budget managed ones — never all registered emitters.
-        if (this.acousticSim !== null && listenerPosition !== null) {
-            const live = this.acousticLive;
-            live.length = 0;
-
-            for (const instance of this.directInstances) {
-                if (instance.state !== EventInstanceState.Playing) {
-                    this.directInstances.delete(instance); // self-ended one-shot — drop
-                    continue;
-                }
-
-                if (instance.acoustic) {
-                    live.push(instance);
-                }
-            }
-
-            this.liveSet.forEachLive((instance) => {
-                if (instance.acoustic) {
-                    live.push(instance);
-                }
-            });
-
-            this.acousticSim.apply(live, listenerPosition);
-        }
-
-        // Drive the probe-baked reverb from the listener (listener-centric: one shared reverb). The
-        // orientation is passed for a directional (FOA) renderer to steer + rotate the wet field by; the
-        // scalar `ProbeReverbRenderer` ignores it.
-        if (this.probeReverb !== null && listenerPosition !== null) {
-            this.probeReverb.update(listenerPosition.x, listenerPosition.y, listenerPosition.z, listenerRotation);
-        }
-
-        sopra.update(this.webAudioContext.currentTime);
-    }
-}
+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. 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),
+ * and is the sole owner of the per-frame sopra tick and listener pose.
+ */
+export class AudioEmitterSystem extends System {
+    dependencies = [AudioEmitter, Transform];
+
+    /**
+     * Live direct-path instances (2D + finite 3D one-shots). Tracked separately so the per-frame
+     * acoustic pass enumerates only the few direct instances + the managed live set — never all
+     * registered emitters.
+     * @type {Set<EventInstance>}
+     */
+    directInstances = new Set();
+
+    /**
+     * Reused scratch array of live acoustic instances fed to {@link acousticSim} each frame.
+     * @type {EventInstance[]}
+     */
+    acousticLive = [];
+
+    /**
+     * 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[]}
+     */
+    data = [];
+
+    /**
+     * Optional probe-baked reverb renderer (acoustic-owned, separate from sopra's static reverb).
+     * When set, it is driven once per frame from the listener position. Null = no probe reverb.
+     * @type {ProbeReverbRenderer|null}
+     */
+    probeReverb = null;
+
+    /**
+     * @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 = {}, acousticSim = null) {
+        super();
+
+        /**
+         * Optional acoustic simulation engine. When set, the system drives `acousticSim.apply(...)` over
+         * its bounded live-voice set each frame (between the live-set refresh and the sopra tick), so
+         * acoustic emitters get occlusion / transmission / medium. Null = no acoustic simulation (default).
+         * @type {AcousticSimulator|null}
+         */
+        this.acousticSim = acousticSim;
+
+        /**
+         * @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. 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 another sound system already made it).
+         * @type {SopraEngine}
+         */
+        this.sopra = soundEngine.obtainSopra(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);
+    }
+
+    /**
+     * @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, onEnded: null };
+
+        if (managed) {
+            const pathing = emitter.acoustic && this.acousticSim !== null && this.acousticSim.pathing;
+            this.liveSet.add(entity, emitter.event, transform.position, volume2dB(emitter.volume.getValue()), emitter.acoustic, pathing, emitter.sourceRadius, transform.rotation, emitter.directivity);
+            record.onVolume = () => this.liveSet.setGainDb(entity, volume2dB(emitter.volume.getValue()));
+        } else {
+            if (emitter.autoplay) {
+                record.instance = this.#play(emitter, transform, record);
+
+                if (record.instance !== null) {
+                    this.directInstances.add(record.instance);
+                }
+            }
+            record.onVolume = () => this.#applyVolume(record);
+        }
+
+        emitter.volume.onChanged.add(record.onVolume);
+
+        this.data[entity] = record;
+
+        // A one-shot whose buffers are already decoded resolves its timeline inside playEvent and can
+        // finish there and then — before the subscription in #play exists, and while the record is still
+        // unreachable. Report that end here instead, once the link is complete, so an `on.ended` handler
+        // that destroys the entity never runs against a half-linked emitter.
+        if (record.instance !== null && record.instance.state === EventInstanceState.Stopped) {
+            emitter.on.ended.send1(emitter);
+        }
+    }
+
+    /**
+     * @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) {
+            this.directInstances.delete(record.instance);
+
+            // stop ≠ ended: EventInstance.onEnded fires for ANY stop, teardown included. Detach the
+            // component-level end handler BEFORE stopping so unlinking a sound that was still playing
+            // never reports an end that did not happen.
+            if (record.onEnded !== null) {
+                record.instance.onEnded.remove(record.onEnded);
+            }
+
+            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
+     * @param {object} record the per-entity record this instance belongs to
+     * @returns {EventInstance|null}
+     */
+    #play(emitter, transform, record) {
+        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,
+            acoustic: emitter.acoustic,
+            pathing: emitter.acoustic && this.acousticSim !== null && this.acousticSim.pathing,
+            sourceRadius: emitter.sourceRadius,
+            orientation: transform.rotation, // shared Quaternion — tracks the entity as it turns
+            directivity: emitter.directivity
+        });
+
+        if (instance !== null) {
+            instance.setGainDb(volume2dB(emitter.volume.getValue()));
+
+            // Component-level end observation (see AudioEmitter.on): the direct route is the only one
+            // that can end — a managed emitter is looping by definition of the route, and its instance
+            // is stopped by demotion rather than by finishing. unlink() detaches this again before its
+            // own stop(), so teardown is not reported as an end.
+            record.onEnded = () => emitter.on.ended.send1(emitter);
+            instance.onEnded.addOne(record.onEnded);
+        }
+
+        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;
+        let listenerRotation = 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;
+                    listenerRotation = listenerTransform.rotation;
+                    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);
+        }
+
+        // Drive the acoustic simulation over the bounded live set (direct one-shots + managed live
+        // instances), BEFORE the tick so a fresh solution spatializes the same frame. Enumerates only the
+        // few direct instances + ≤ budget managed ones — never all registered emitters.
+        if (this.acousticSim !== null && listenerPosition !== null) {
+            const live = this.acousticLive;
+            live.length = 0;
+
+            for (const instance of this.directInstances) {
+                if (instance.state !== EventInstanceState.Playing) {
+                    this.directInstances.delete(instance); // self-ended one-shot — drop
+                    continue;
+                }
+
+                if (instance.acoustic) {
+                    live.push(instance);
+                }
+            }
+
+            this.liveSet.forEachLive((instance) => {
+                if (instance.acoustic) {
+                    live.push(instance);
+                }
+            });
+
+            this.acousticSim.apply(live, listenerPosition);
+        }
+
+        // Drive the probe-baked reverb from the listener (listener-centric: one shared reverb). The
+        // orientation is passed for a directional (FOA) renderer to steer + rotate the wet field by; the
+        // scalar `ProbeReverbRenderer` ignores it.
+        if (this.probeReverb !== null && listenerPosition !== null) {
+            this.probeReverb.update(listenerPosition.x, listenerPosition.y, listenerPosition.z, listenerRotation);
+        }
+
+        sopra.update(this.webAudioContext.currentTime);
+    }
+}