@woosh/meep-engine 2.155.0 → 2.156.0

package/src/engine/sound/sopra/SopraEngine.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Default top-level bus ids, kept identical to the legacy {@link SoundEmitterChannels } for back-compat
+ * with the settings UI and `SoundEmitter.channel` strings.
+ */
+export type SopraDefaultBus = string;
+export namespace SopraDefaultBus {
+    let Master: string;
+    let Effects: string;
+    let Music: string;
+    let Ambient: string;
+}
+/**
+ * The ECS-AGNOSTIC sopra audio engine. It owns the mixer bus graph, parameter store and the set of
+ * active {@link EventInstance}s, and is driven by a single clock (the injected AudioContext's
+ * `currentTime`). It never creates an AudioContext — the meep `SoundEngine` owns that. Voices are
+ * recycled through the shared {@link VOICE_POOL}.
+ *
+ * The entire public surface is unit-testable with a mock AudioContext + a stub {@link BufferProvider}.
+ */
+export class SopraEngine {
+    /**
+     * The default bus tree: a master root with the three legacy channels at the legacy mix.
+     * @returns {BusDefinition[]}
+     */
+    static defaultBuses(): BusDefinition[];
+    /**
+     * @param {BaseAudioContext} audioContext
+     * @param {AudioNode} destinationNode master destination the bus root routes into
+     * @param {BufferProvider} bufferProvider
+     */
+    constructor(audioContext: BaseAudioContext, destinationNode: AudioNode, bufferProvider: BufferProvider);
+    /**
+     * @type {ParameterStore}
+     */
+    parameters: ParameterStore;
+    /**
+     * Shared playback context (seeded RNG + random-container history) used by instances that don't
+     * supply their own. In P3 each emitter supplies its own seeded context (entity id + tick).
+     * @type {SopraPlaybackContext}
+     */
+    defaultPlaybackContext: SopraPlaybackContext;
+    /**
+     * Per-event instance limits + voice stealing.
+     * @type {VoiceManager}
+     */
+    voiceManager: VoiceManager;
+    /**
+     * Listener world position for spatialization/attenuation. Null = no listener set yet (events play
+     * unattenuated). In P3 this is driven from the ECS SoundListener.
+     * @type {Vector3|null}
+     */
+    listenerPosition: Vector3 | null;
+    /**
+     * @type {BaseAudioContext}
+     */
+    audioContext: BaseAudioContext;
+    /**
+     * @type {AudioNode}
+     */
+    destination: AudioNode;
+    /**
+     * @type {BufferProvider}
+     */
+    bufferProvider: BufferProvider;
+    /**
+     * @type {BusGraph}
+     */
+    busGraph: BusGraph;
+    /**
+     * @returns {number} current context time (the engine's authoritative clock)
+     */
+    get currentTime(): number;
+    /**
+     * Replace the mixer with a new bus tree (rebuilds the WebAudio graph).
+     * @param {BusDefinition[]} busDefinitions
+     */
+    setBuses(busDefinitions: BusDefinition[]): void;
+    /**
+     * Create (but do not start) an instance of an event.
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, seed?:number, playbackContext?:SopraPlaybackContext}} [options]
+     * @returns {EventInstance}
+     */
+    createInstance(description: EventDescription, options?: {
+        busId?: string;
+        position?: Vector3;
+        oneShot?: boolean;
+        maxLifetime?: number;
+        seed?: number;
+        playbackContext?: SopraPlaybackContext;
+    }): EventInstance;
+    /**
+     * Create, start and track an instance.
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, seed?:number, playbackContext?:SopraPlaybackContext}} [options]
+     * @returns {EventInstance}
+     */
+    playEvent(description: EventDescription, options?: {
+        busId?: string;
+        position?: Vector3;
+        oneShot?: boolean;
+        maxLifetime?: number;
+        seed?: number;
+        playbackContext?: SopraPlaybackContext;
+    }): EventInstance;
+    /**
+     * Fire-and-forget: a one-shot that auto-releases when its content finishes (or on the
+     * lifetime/asset-failure fallback).
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, maxLifetime?:number}} [options]
+     * @returns {EventInstance}
+     */
+    playOneShot(description: EventDescription, options?: {
+        busId?: string;
+        position?: Vector3;
+        maxLifetime?: number;
+    }): EventInstance;
+    /**
+     * @param {EventInstance} instance
+     */
+    stop(instance: EventInstance): void;
+    /**
+     * Crossfade from a playing instance to a new event: start the new one at silence and fade it up to
+     * its nominal gain while fading the old one out and stopping it, over `duration`.
+     * @param {EventInstance|null} oldInstance instance to fade out (may be null)
+     * @param {EventDescription} description event to fade in
+     * @param {{busId?:string, position?:Vector3, duration?:number}} [options]
+     * @returns {EventInstance|null} the new instance (or null if the play was denied by limits)
+     */
+    crossfade(oldInstance: EventInstance | null, description: EventDescription, options?: {
+        busId?: string;
+        position?: Vector3;
+        duration?: number;
+    }): EventInstance | null;
+    /**
+     * @param {string} name
+     * @param {number} value
+     */
+    setParameter(name: string, value: number): void;
+    /**
+     * @param {string} name
+     * @returns {number|undefined}
+     */
+    getParameter(name: string): number | undefined;
+    /**
+     * Set the listener world position used for 3D attenuation/culling.
+     * @param {Vector3} position
+     */
+    setListener(position: Vector3): void;
+    /**
+     * Register a parameter with a default value.
+     * @param {string} name
+     * @param {number} [defaultValue]
+     */
+    defineParameter(name: string, defaultValue?: number): void;
+    /**
+     * Bind an arbitrary apply callback to a parameter (runs on change, and once now if already set).
+     * @param {string} name
+     * @param {function(number)} applyFn
+     */
+    bindParameter(name: string, applyFn: (arg0: number) => any): void;
+    /**
+     * Drive a bus's linear volume from a parameter through an {@link AnimationCurve}.
+     * @param {string} name
+     * @param {string} busId
+     * @param {AnimationCurve} curve maps parameter value -> linear bus gain
+     */
+    bindParameterToBusVolume(name: string, busId: string, curve: AnimationCurve): void;
+    /**
+     * @param {string} busId
+     * @returns {number} linear gain
+     */
+    getBusVolume(busId: string): number;
+    /**
+     * @param {string} busId
+     * @param {number} linear linear gain
+     */
+    setBusVolume(busId: string, linear: number): void;
+    /**
+     * Apply a {@link MixerSnapshot}: move each listed bus to its target gain. `duration` 0 snaps
+     * instantly; > 0 click-safely ramps (a mix-state blend).
+     * @param {MixerSnapshot} snapshot
+     * @param {{duration?:number}} [options]
+     */
+    applySnapshot(snapshot: MixerSnapshot, { duration }?: {
+        duration?: number;
+    }): void;
+    /**
+     * Capture the current gain of each given bus into a snapshot (e.g. to restore a mix later).
+     * @param {string} id
+     * @param {string[]} busIds
+     * @returns {MixerSnapshot}
+     */
+    captureSnapshot(id: string, busIds: string[]): MixerSnapshot;
+    /**
+     * Advance the engine. Drives per-instance lifetime bookkeeping (and, from P1, the scheduler).
+     * @param {number} [now] context time; defaults to the live clock
+     */
+    update(now?: number): void;
+    /**
+     * Register a ducking rule (e.g. duck `music` while anything plays on `dialogue`). Evaluated each
+     * {@link update}.
+     * @param {DuckingRule} rule
+     */
+    addDucker(rule: DuckingRule): void;
+    /**
+     * Remove all ducking rules (restoring any currently-ducked target to its captured nominal).
+     */
+    clearDuckers(): void;
+    /**
+     * @returns {number} count of live instances (for tests/diagnostics)
+     */
+    get activeInstanceCount(): number;
+    /**
+     * Internal: invoked by an {@link EventInstance} when it finishes. Uses the `__` prefix because it
+     * is a cross-class internal call, not part of the public API.
+     * @param {EventInstance} instance
+     */
+    __onInstanceFinished(instance: EventInstance): void;
+    #private;
+}
+import { ParameterStore } from "./runtime/ParameterStore.js";
+import { SopraPlaybackContext } from "./runtime/SopraPlaybackContext.js";
+import { VoiceManager } from "./runtime/VoiceManager.js";
+import { BusGraph } from "./runtime/BusGraph.js";
+import { BusDefinition } from "./definition/BusDefinition.js";
+import { EventInstance } from "./runtime/EventInstance.js";
+import { MixerSnapshot } from "./definition/MixerSnapshot.js";
+//# sourceMappingURL=SopraEngine.d.ts.map

package/src/engine/sound/sopra/SopraEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SopraEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/sopra/SopraEngine.js"],"names":[],"mappings":";;;;8BAcU,MAAM;;;;;;;AAahB;;;;;;;GAOG;AACH;IA6EI;;;OAGG;IACH,uBAFa,aAAa,EAAE,CAS3B;IAlDD;;;;OAIG;IACH,0BAJW,gBAAgB,mBAChB,SAAS,kCA4BnB;IAlED;;OAEG;IACH,YAFU,cAAc,CAEU;IAElC;;;;OAIG;IACH,wBAFU,oBAAoB,CAEsB;IAEpD;;;OAGG;IACH,cAFU,YAAY,CAEY;IAElC;;;;OAIG;IACH,kBAFU,UAAQ,IAAI,CAEE;IAuBpB;;OAEG;IACH,cAFU,gBAAgB,CAEM;IAEhC;;OAEG;IACH,aAFU,SAAS,CAEe;IAElC;;OAEG;IACH,+BAAoC;IAEpC;;OAEG;IACH,UAFU,QAAQ,CAEyC;IAI/D;;OAEG;IACH,0BAEC;IAeD;;;OAGG;IACH,yBAFW,aAAa,EAAE,QAKzB;IAED;;;;;OAKG;IACH;gBAHmB,MAAM;;kBAA8B,OAAO;sBAAe,MAAM;eAAQ,MAAM;0BAAmB,oBAAoB;QAC3H,aAAa,CAOzB;IAED;;;;;OAKG;IACH,mDAHW;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAS;QAAC,OAAO,CAAC,EAAC,OAAO,CAAC;QAAC,WAAW,CAAC,EAAC,MAAM,CAAC;QAAC,IAAI,CAAC,EAAC,MAAM,CAAC;QAAC,eAAe,CAAC,EAAC,oBAAoB,CAAA;KAAC,GAC5H,aAAa,CAuBzB;IAED;;;;;;OAMG;IACH,qDAHW;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAS;QAAC,WAAW,CAAC,EAAC,MAAM,CAAA;KAAC,GACrD,aAAa,CAIzB;IAED;;OAEG;IACH,eAFW,aAAa,QAIvB;IAED;;;;;;;OAOG;IACH,uBALW,aAAa,GAAC,IAAI;gBAEV,MAAM;;mBAA+B,MAAM;QACjD,aAAa,GAAC,IAAI,CAmB9B;IAED;;;OAGG;IACH,mBAHW,MAAM,SACN,MAAM,QAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,qCAEC;IAED;;;;OAIG;IACH,sBAHW,MAAM,iBACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,oBAHW,MAAM,kBACG,MAAM,gBAIzB;IAED;;;;;OAKG;IACH,+BAJW,MAAM,SACN,MAAM,+BAKhB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;;;;OAKG;IACH,wBAHW,aAAa,iBACb;QAAC,QAAQ,CAAC,EAAC,MAAM,CAAA;KAAC,QAe5B;IAED;;;;;OAKG;IACH,oBAJW,MAAM,UACN,MAAM,EAAE,GACN,aAAa,CAUzB;IAED;;;OAGG;IACH,aAFW,MAAM,QAahB;IAED;;;;OAIG;IACH,mCAEC;IAED;;OAEG;IACH,qBAWC;IAwCD;;OAEG;IACH,kCAEC;IAED;;;;OAIG;IACH,+BAFW,aAAa,QAKvB;;CACJ;+BA/Z8B,6BAA6B;qCACvB,mCAAmC;6BAC3C,2BAA2B;yBANd,uBAAuB;8BACnC,+BAA+B;8BAE/B,4BAA4B;8BAD5B,+BAA+B"}

package/src/engine/sound/sopra/SopraEngine.js

@@ -0,0 +1,423 @@
+import { assert } from "../../../core/assert.js";
+import { dB2Volume } from "../dB2Volume.js";
+import { volume2dB } from "../volume2dB.js";
+import { BUS_ROOT_PARENT, BusGraph } from "./runtime/BusGraph.js";
+import { BusDefinition } from "./definition/BusDefinition.js";
+import { MixerSnapshot } from "./definition/MixerSnapshot.js";
+import { EventInstance } from "./runtime/EventInstance.js";
+import { ParameterStore } from "./runtime/ParameterStore.js";
+import { SopraPlaybackContext } from "./runtime/SopraPlaybackContext.js";
+import { VoiceManager } from "./runtime/VoiceManager.js";
+
+/**
+ * Default top-level bus ids, kept identical to the legacy {@link SoundEmitterChannels} for back-compat
+ * with the settings UI and `SoundEmitter.channel` strings.
+ * @enum {string}
+ */
+export const SopraDefaultBus = {
+    Master: "master",
+    Effects: "effects",
+    Music: "music",
+    Ambient: "ambient"
+};
+
+// legacy default mix (verified SoundEmitterSystem constructor): Effects 1.2, Music 0.1, Ambient 1
+const LEGACY_EFFECTS_VOLUME = 1.2;
+const LEGACY_MUSIC_VOLUME = 0.1;
+
+/**
+ * The ECS-AGNOSTIC sopra audio engine. It owns the mixer bus graph, parameter store and the set of
+ * active {@link EventInstance}s, and is driven by a single clock (the injected AudioContext's
+ * `currentTime`). It never creates an AudioContext — the meep `SoundEngine` owns that. Voices are
+ * recycled through the shared {@link VOICE_POOL}.
+ *
+ * The entire public surface is unit-testable with a mock AudioContext + a stub {@link BufferProvider}.
+ */
+export class SopraEngine {
+
+    /**
+     * @type {ParameterStore}
+     */
+    parameters = new ParameterStore();
+
+    /**
+     * Shared playback context (seeded RNG + random-container history) used by instances that don't
+     * supply their own. In P3 each emitter supplies its own seeded context (entity id + tick).
+     * @type {SopraPlaybackContext}
+     */
+    defaultPlaybackContext = new SopraPlaybackContext();
+
+    /**
+     * Per-event instance limits + voice stealing.
+     * @type {VoiceManager}
+     */
+    voiceManager = new VoiceManager();
+
+    /**
+     * Listener world position for spatialization/attenuation. Null = no listener set yet (events play
+     * unattenuated). In P3 this is driven from the ECS SoundListener.
+     * @type {Vector3|null}
+     */
+    listenerPosition = null;
+
+    /**
+     * @type {Set<EventInstance>}
+     */
+    #activeInstances = new Set();
+
+    /**
+     * Active ducking rules + their runtime state.
+     * @type {{rule: DuckingRule, engaged: boolean, nominalDb: number}[]}
+     */
+    #duckers = [];
+
+    /**
+     * @param {BaseAudioContext} audioContext
+     * @param {AudioNode} destinationNode master destination the bus root routes into
+     * @param {BufferProvider} bufferProvider
+     */
+    constructor(audioContext, destinationNode, bufferProvider) {
+        assert.defined(audioContext, 'audioContext');
+        assert.defined(destinationNode, 'destinationNode');
+        assert.defined(bufferProvider, 'bufferProvider');
+
+        /**
+         * @type {BaseAudioContext}
+         */
+        this.audioContext = audioContext;
+
+        /**
+         * @type {AudioNode}
+         */
+        this.destination = destinationNode;
+
+        /**
+         * @type {BufferProvider}
+         */
+        this.bufferProvider = bufferProvider;
+
+        /**
+         * @type {BusGraph}
+         */
+        this.busGraph = new BusGraph(audioContext, destinationNode);
+        this.busGraph.build(SopraEngine.defaultBuses());
+    }
+
+    /**
+     * @returns {number} current context time (the engine's authoritative clock)
+     */
+    get currentTime() {
+        return this.audioContext.currentTime;
+    }
+
+    /**
+     * The default bus tree: a master root with the three legacy channels at the legacy mix.
+     * @returns {BusDefinition[]}
+     */
+    static defaultBuses() {
+        return [
+            BusDefinition.from(SopraDefaultBus.Master, { parentId: BUS_ROOT_PARENT, gainDb: 0 }),
+            BusDefinition.from(SopraDefaultBus.Effects, { parentId: SopraDefaultBus.Master, gainDb: volume2dB(LEGACY_EFFECTS_VOLUME) }),
+            BusDefinition.from(SopraDefaultBus.Music, { parentId: SopraDefaultBus.Master, gainDb: volume2dB(LEGACY_MUSIC_VOLUME) }),
+            BusDefinition.from(SopraDefaultBus.Ambient, { parentId: SopraDefaultBus.Master, gainDb: 0 })
+        ];
+    }
+
+    /**
+     * Replace the mixer with a new bus tree (rebuilds the WebAudio graph).
+     * @param {BusDefinition[]} busDefinitions
+     */
+    setBuses(busDefinitions) {
+        this.busGraph = new BusGraph(this.audioContext, this.destination);
+        this.busGraph.build(busDefinitions);
+    }
+
+    /**
+     * Create (but do not start) an instance of an event.
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, seed?:number, playbackContext?:SopraPlaybackContext}} [options]
+     * @returns {EventInstance}
+     */
+    createInstance(description, options = {}) {
+        const playbackContext = options.playbackContext
+            ?? (options.seed !== undefined ? new SopraPlaybackContext(options.seed) : this.defaultPlaybackContext);
+
+        return new EventInstance(this, description, { ...options, playbackContext });
+    }
+
+    /**
+     * Create, start and track an instance.
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, seed?:number, playbackContext?:SopraPlaybackContext}} [options]
+     * @returns {EventInstance}
+     */
+    playEvent(description, options = {}) {
+        if (!this.voiceManager.makeRoom(description)) {
+            // event instance limit reached and steal mode is None — drop this play
+            return null;
+        }
+
+        const instance = this.createInstance(description, options);
+
+        this.voiceManager.register(instance);
+        this.#activeInstances.add(instance);
+
+        try {
+            instance.start(this.currentTime);
+        } catch (e) {
+            // clean up registries before propagating (rethrows — not a silent catch)
+            this.voiceManager.unregister(instance);
+            this.#activeInstances.delete(instance);
+            throw e;
+        }
+
+        return instance;
+    }
+
+    /**
+     * Fire-and-forget: a one-shot that auto-releases when its content finishes (or on the
+     * lifetime/asset-failure fallback).
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, maxLifetime?:number}} [options]
+     * @returns {EventInstance}
+     */
+    playOneShot(description, options = {}) {
+        return this.playEvent(description, { ...options, oneShot: true });
+    }
+
+    /**
+     * @param {EventInstance} instance
+     */
+    stop(instance) {
+        instance.stop();
+    }
+
+    /**
+     * Crossfade from a playing instance to a new event: start the new one at silence and fade it up to
+     * its nominal gain while fading the old one out and stopping it, over `duration`.
+     * @param {EventInstance|null} oldInstance instance to fade out (may be null)
+     * @param {EventDescription} description event to fade in
+     * @param {{busId?:string, position?:Vector3, duration?:number}} [options]
+     * @returns {EventInstance|null} the new instance (or null if the play was denied by limits)
+     */
+    crossfade(oldInstance, description, options = {}) {
+        const duration = options.duration ?? 1;
+
+        const newInstance = this.playEvent(description, options);
+
+        if (newInstance !== null) {
+            const nominalDb = newInstance.gainDb;
+
+            newInstance.setGainDb(nominalDb - 60); // start ~silent
+            newInstance.fadeToGainDb(nominalDb, duration);
+        }
+
+        if (oldInstance !== null && oldInstance !== newInstance) {
+            oldInstance.fadeOutAndStop(duration);
+        }
+
+        return newInstance;
+    }
+
+    /**
+     * @param {string} name
+     * @param {number} value
+     */
+    setParameter(name, value) {
+        this.parameters.set(name, value);
+    }
+
+    /**
+     * @param {string} name
+     * @returns {number|undefined}
+     */
+    getParameter(name) {
+        return this.parameters.get(name);
+    }
+
+    /**
+     * Set the listener world position used for 3D attenuation/culling.
+     * @param {Vector3} position
+     */
+    setListener(position) {
+        this.listenerPosition = position;
+    }
+
+    /**
+     * Register a parameter with a default value.
+     * @param {string} name
+     * @param {number} [defaultValue]
+     */
+    defineParameter(name, defaultValue = 0) {
+        this.parameters.define(name, defaultValue);
+    }
+
+    /**
+     * Bind an arbitrary apply callback to a parameter (runs on change, and once now if already set).
+     * @param {string} name
+     * @param {function(number)} applyFn
+     */
+    bindParameter(name, applyFn) {
+        this.parameters.bind(name, applyFn);
+    }
+
+    /**
+     * Drive a bus's linear volume from a parameter through an {@link AnimationCurve}.
+     * @param {string} name
+     * @param {string} busId
+     * @param {AnimationCurve} curve maps parameter value -> linear bus gain
+     */
+    bindParameterToBusVolume(name, busId, curve) {
+        this.parameters.bind(name, (value) => this.setBusVolume(busId, curve.evaluate(value)));
+    }
+
+    /**
+     * @param {string} busId
+     * @returns {number} linear gain
+     */
+    getBusVolume(busId) {
+        return this.busGraph.getVolume(busId);
+    }
+
+    /**
+     * @param {string} busId
+     * @param {number} linear linear gain
+     */
+    setBusVolume(busId, linear) {
+        this.busGraph.setVolume(busId, linear);
+    }
+
+    /**
+     * Apply a {@link MixerSnapshot}: move each listed bus to its target gain. `duration` 0 snaps
+     * instantly; > 0 click-safely ramps (a mix-state blend).
+     * @param {MixerSnapshot} snapshot
+     * @param {{duration?:number}} [options]
+     */
+    applySnapshot(snapshot, { duration = 0 } = {}) {
+        const buses = snapshot.buses;
+
+        for (let i = 0; i < buses.length; i++) {
+            const entry = buses[i];
+            const linear = dB2Volume(entry.gainDb);
+
+            if (duration <= 0) {
+                this.busGraph.setVolume(entry.busId, linear);
+            } else {
+                this.busGraph.rampVolume(entry.busId, linear, duration);
+            }
+        }
+    }
+
+    /**
+     * Capture the current gain of each given bus into a snapshot (e.g. to restore a mix later).
+     * @param {string} id
+     * @param {string[]} busIds
+     * @returns {MixerSnapshot}
+     */
+    captureSnapshot(id, busIds) {
+        const buses = [];
+
+        for (let i = 0; i < busIds.length; i++) {
+            buses.push({ busId: busIds[i], gainDb: this.busGraph.getVolumeDb(busIds[i]) });
+        }
+
+        return MixerSnapshot.from(id, buses);
+    }
+
+    /**
+     * Advance the engine. Drives per-instance lifetime bookkeeping (and, from P1, the scheduler).
+     * @param {number} [now] context time; defaults to the live clock
+     */
+    update(now = this.currentTime) {
+        const listenerPosition = this.listenerPosition;
+
+        // snapshot — an instance may finish (and remove itself) during its own update
+        const instances = [...this.#activeInstances];
+
+        for (let i = 0; i < instances.length; i++) {
+            instances[i].update(now, listenerPosition);
+        }
+
+        this.#updateDuckers();
+    }
+
+    /**
+     * Register a ducking rule (e.g. duck `music` while anything plays on `dialogue`). Evaluated each
+     * {@link update}.
+     * @param {DuckingRule} rule
+     */
+    addDucker(rule) {
+        this.#duckers.push({ rule, engaged: false, nominalDb: 0 });
+    }
+
+    /**
+     * Remove all ducking rules (restoring any currently-ducked target to its captured nominal).
+     */
+    clearDuckers() {
+        const duckers = this.#duckers;
+
+        for (let i = 0; i < duckers.length; i++) {
+            const d = duckers[i];
+            if (d.engaged) {
+                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb), d.rule.release);
+            }
+        }
+
+        this.#duckers = [];
+    }
+
+    /**
+     * Edge-triggered duck engage/release: a target ducks while its trigger bus has any live instance,
+     * and restores to the gain captured at engage time when the trigger goes quiet.
+     */
+    #updateDuckers() {
+        const duckers = this.#duckers;
+
+        for (let i = 0; i < duckers.length; i++) {
+            const d = duckers[i];
+            const active = this.#busActiveCount(d.rule.triggerBusId) > 0;
+
+            if (active && !d.engaged) {
+                d.engaged = true;
+                d.nominalDb = this.busGraph.getVolumeDb(d.rule.targetBusId);
+                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb + d.rule.duckDb), d.rule.attack);
+            } else if (!active && d.engaged) {
+                d.engaged = false;
+                this.busGraph.approachVolume(d.rule.targetBusId, dB2Volume(d.nominalDb), d.rule.release);
+            }
+        }
+    }
+
+    /**
+     * @param {string} busId
+     * @returns {number} count of live instances routed to that bus
+     */
+    #busActiveCount(busId) {
+        let n = 0;
+
+        this.#activeInstances.forEach(instance => {
+            if (instance.busId === busId) {
+                n++;
+            }
+        });
+
+        return n;
+    }
+
+    /**
+     * @returns {number} count of live instances (for tests/diagnostics)
+     */
+    get activeInstanceCount() {
+        return this.#activeInstances.size;
+    }
+
+    /**
+     * Internal: invoked by an {@link EventInstance} when it finishes. Uses the `__` prefix because it
+     * is a cross-class internal call, not part of the public API.
+     * @param {EventInstance} instance
+     */
+    __onInstanceFinished(instance) {
+        this.#activeInstances.delete(instance);
+        this.voiceManager.unregister(instance);
+    }
+}

package/src/engine/sound/sopra/asset/AssetManagerBufferProvider.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Production {@link BufferProvider} that draws decoded {@link AudioBuffer}s from the meep
+ * {@link AssetManager}. Reuses the shared decode cache (one immutable AudioBuffer backs many voices)
+ * and the existing alias system.
+ */
+export class AssetManagerBufferProvider extends BufferProvider {
+    /**
+     * @param {AssetManager} assetManager
+     */
+    constructor(assetManager: AssetManager);
+    /**
+     * @type {AssetManager}
+     */
+    assetManager: AssetManager;
+    /**
+     * @private
+     * @param {string} url
+     * @param {boolean} usingAlias
+     * @returns {string|null} resolved path, or null if an alias could not be resolved
+     */
+    private __resolvePath;
+    tryGet(url: any, usingAlias: any): any;
+    get(url: any, usingAlias: any): any;
+}
+import { BufferProvider } from "./BufferProvider.js";
+//# sourceMappingURL=AssetManagerBufferProvider.d.ts.map

package/src/engine/sound/sopra/asset/AssetManagerBufferProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssetManagerBufferProvider.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/asset/AssetManagerBufferProvider.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI;;OAEG;IACH,wCAOC;IAJG;;OAEG;IACH,2BAAgC;IAGpC;;;;;OAKG;IACH,sBAYC;IAED,uCAcC;IAED,oCAYC;CACJ;+BArE8B,qBAAqB"}