npm - @woosh/meep-engine - Versions diffs - 3.15.0 → 3.16.0 - Mend

@woosh/meep-engine 3.15.0 → 3.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (952) hide show

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

@@ -1,338 +1,343 @@
-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);
-    }
-}
+import { GameAssetType } from "../../../asset/GameAssetType.js";
+import { SoundAssetLoader } from "../../../asset/loaders/SoundAssetLoader.js";
+import { System } from "../../../ecs/System.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.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";
+import { EventType } from "../../../ecs/EventType.js";
+/**
+ * Drives {@link AudioEmitter} components through the shared sopra engine. Each emitter owns its
+ * {@link EventDescription} directly (no track translation); the entity's {@link Transform64} 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, Transform64];
+    /**
+     * 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 {Transform64} 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.translation, 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 {Transform64} 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 {Transform64} 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,
+            // a live view over the transform's buffer, so it still tracks the entity as it moves
+            position: transform.translation,
+            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, Transform64);
+                if (listenerTransform !== undefined) {
+                    listenerPosition = listenerTransform.translation;
+                    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);
+    }
+}