@woosh/meep-engine 2.155.0 → 2.157.0

package/src/engine/sound/ecs/emitter/SoundEmitterComponentContext.js

@@ -1,202 +1,235 @@
-import { loadSoundTrackAsset } from "./loadSoundTrackAsset.js";
+import { EventInstanceState } from "../../sopra/runtime/EventInstance.js";
+import { soundTrackToEventDescription } from "../../sopra/legacy/soundEmitterToEventDescription.js";
+import { volume2dB } from "../../volume2dB.js";
 import { SoundTrackFlags } from "./SoundTrackFlags.js";
 
+/**
+ * Per-entity translation record: turns a legacy {@link SoundEmitter}'s mutable track list into sopra
+ * {@link EventInstance}s and keeps them in sync. This is NOT a WebAudio renderer anymore — sopra owns
+ * the audio graph. One persistent/looping track ⇒ one persistent instance; a non-looping track ⇒ a
+ * one-shot instance that self-ends (firing the track's `on.ended`).
+ */
 export class SoundEmitterComponentContext {
-    constructor() {
-
-        /**
-         *
-         * @type {SoundEmitter}
-         */
-        this.emitter = null;
-
-        /**
-         *
-         * @type {Transform}
-         */
-        this.transform = null;
-
-        /**
-         *
-         * @type {SoundEmitterSystem}
-         */
-        this.system = null;
-
-        /**
-         *
-         * @type {AudioNode}
-         */
-        this.targetNode = null;
-
-        /**
-         *
-         * @type {boolean}
-         * @private
-         */
-        this.__isConnected = false;
-    }
 
     /**
-     *
-     * @param {SoundEmitterComponentContext} other
+     * @type {SoundEmitter}
      */
-    compare(other) {
-        return this.emitter.compare(other.emitter);
-    }
+    emitter = null;
+
+    /**
+     * @type {Transform}
+     */
+    transform = null;
+
+    /**
+     * @type {SoundEmitterSystem}
+     */
+    system = null;
 
-    update() {
+    /**
+     * @type {SopraEngine}
+     */
+    sopra = null;
+
+    /**
+     * track → its live sopra instance
+     * @type {Map<SoundTrack, EventInstance>}
+     */
+    #instances = new Map();
 
-        const position = this.transform.position;
+    #boundAddTrack = (track) => this.addTrack(track);
+    #boundRemoveTrack = (track) => this.removeTrack(track);
+    #boundUpdateVolume = () => this.#updateVolume();
 
-        /**
-         *
-         * @type {SoundEmitter}
-         */
+    link() {
         const emitter = this.emitter;
 
-        const x = position.x;
-        const y = position.y;
-        const z = position.z;
+        // back-reference so the emitter's deprecated fade/stop helpers can reach the live instances
+        emitter.__soundRuntime = this;
 
-        emitter.updatePosition(x, y, z);
-    }
+        // snapshot the initial tracks before adding: addTrack can synchronously remove a track (a
+        // zero-duration / synchronously-failed one-shot self-ends inside playEvent), and List.forEach
+        // is NOT safe against re-entrant removal (it iterates by a fixed index over the live array).
+        const initial = [];
+        emitter.tracks.forEach((track) => initial.push(track));
+        for (let i = 0; i < initial.length; i++) {
+            this.addTrack(initial[i]);
+        }
 
-    /**
-     *
-     * @param {SoundTrack} soundTrack
-     */
-    addTrack(soundTrack) {
-        const system = this.system;
+        emitter.tracks.on.added.add(this.#boundAddTrack);
+        emitter.tracks.on.removed.add(this.#boundRemoveTrack);
+        emitter.volume.onChanged.add(this.#boundUpdateVolume);
+    }
 
+    unlink() {
         const emitter = this.emitter;
 
-        const context = system.webAudioContext;
-        const assetManager = system.assetManager;
-        const targetNode = emitter.nodes.volume;
+        emitter.tracks.on.added.remove(this.#boundAddTrack);
+        emitter.tracks.on.removed.remove(this.#boundRemoveTrack);
+        emitter.volume.onChanged.remove(this.#boundUpdateVolume);
 
-        soundTrack.initializeNodes(context);
+        this.stopAll();
 
-        const nodes = soundTrack.nodes;
+        emitter.__soundRuntime = null;
+    }
 
-        //connect to target
-        nodes.volume.connect(targetNode);
+    /**
+     * @param {SoundTrack} track
+     */
+    addTrack(track) {
+        const emitter = this.emitter;
 
-        nodes.volume.gain.setValueAtTime(soundTrack.volume, 0);
+        const description = soundTrackToEventDescription(emitter, track);
 
-        loadSoundTrackAsset(soundTrack, assetManager, (asset) => {
+        // a looping track is persistent; a one-shot self-ends (and then fires track.on.ended)
+        const oneShot = !track.getFlag(SoundTrackFlags.Loop);
 
-            soundTrack.buffer = asset.create();
+        const instance = this.sopra.playEvent(description, {
+            busId: description.busId,
+            position: this.transform.position, // shared Vector3 — tracks the entity as it moves
+            oneShot
+        });
 
-            if (soundTrack.getFlag(SoundTrackFlags.StartWhenReady)) {
+        if (instance === null) {
+            // play denied (instance limit) — drop, matching the steal/limit policy
+            return;
+        }
 
-                if (this.__isConnected) {
-                    soundTrack.start(context.currentTime);
-                } else {
-                    soundTrack.setFlag(SoundTrackFlags.Playing);
-                }
-            }
+        this.#bind(track, instance);
 
+        // live volume = emitter.volume × track.volume, carried by the instance gain
+        instance.setGainDb(this.#trackGainDb(track));
 
-        }, console.error);
+        instance.onEnded.addOne(() => this.#onInstanceEnded(track, instance));
 
-        soundTrack.on.ended.add(emitter.tracks.removeOneOf, emitter.tracks);
+        // A zero-duration (or synchronously-failed) one-shot self-ends inside playEvent's start(),
+        // firing onEnded BEFORE the subscription above — so run the end path now, else the instance
+        // leaks in #instances and the dead track never leaves the list.
+        if (instance.state === EventInstanceState.Stopped) {
+            this.#onInstanceEnded(track, instance);
+        }
     }
 
     /**
-     *
      * @param {SoundTrack} track
      */
     removeTrack(track) {
-        /**
-         *
-         * @type {GainNode}
-         */
-        const volume = track.nodes.volume;
+        const instance = this.#instances.get(track);
 
-        volume.disconnect();
+        if (instance === undefined) {
+            return;
+        }
 
-        const emitter = this.emitter;
+        // detach BEFORE stopping so the onEnded handler (which stop() fires synchronously) bails out
+        this.#unbind(track);
 
-        track.on.ended.remove(emitter.tracks.removeOneOf, emitter.tracks);
+        instance.stop();
     }
 
     /**
-     * @param {SoundTrack} t
+     * Bind a track to its live instance.
+     * @param {SoundTrack} track
+     * @param {EventInstance} instance
      */
-    suspendTrack(t) {
-        if (t.getFlag(SoundTrackFlags.Playing)) {
-            t.suspend();
-        }
+    #bind(track, instance) {
+        track.__instance = instance;
+        track.__soundRuntime = this;
+        this.#instances.set(track, instance);
     }
 
     /**
-     *
-     * @param {SoundTrack} t
+     * Detach a track from its (now gone) instance.
+     * @param {SoundTrack} track
      */
-    resumeTrack(t) {
-
-        if (t.getFlag(SoundTrackFlags.Playing)) {
-            t.start();
-        }
+    #unbind(track) {
+        this.#instances.delete(track);
+        track.__instance = null;
+        track.__soundRuntime = null;
     }
 
-    connect() {
-        if (this.__isConnected) {
+    /**
+     * @param {SoundTrack} track
+     * @param {EventInstance} instance
+     */
+    #onInstanceEnded(track, instance) {
+        if (this.#instances.get(track) !== instance) {
+            // already removed via removeTrack() — nothing to do
             return;
         }
 
-        const emitter = this.emitter;
-        const targetNode = emitter.getTargetNode();
-
-        targetNode.connect(this.targetNode);
+        this.#unbind(track);
 
-        // update all track times
-        emitter.tracks.forEach(this.resumeTrack);
+        // legacy contract: a finished track fires on.ended and leaves the list. Remove by IDENTITY
+        // (not value-equality) so a value-equal sibling track is never removed by mistake.
+        track.on.ended.send1(track);
 
-        this.__isConnected = true;
+        const tracks = this.emitter.tracks;
+        const index = tracks.indexOf(track);
+        if (index !== -1) {
+            tracks.remove(index);
+        }
     }
 
-    disconnect() {
-        if (!this.__isConnected) {
-            return;
-        }
+    #updateVolume() {
+        this.#instances.forEach((instance, track) => {
+            instance.setGainDb(this.#trackGainDb(track));
+        });
+    }
 
-        const emitter = this.emitter;
-        const targetNode = emitter.getTargetNode();
+    /**
+     * Re-apply a single track's live volume to its instance gain. Called by SoundTrack's volume setter
+     * (via the track's __soundRuntime back-ref) so a mid-playback `track.volume = x` is heard live.
+     * @param {SoundTrack} track
+     */
+    refreshTrackVolume(track) {
+        const instance = this.#instances.get(track);
 
-        if (targetNode !== null) {
-            targetNode.disconnect();
+        if (instance === undefined) {
+            return;
         }
 
-        /*
-         The reason we suspend all tracks is to be able to track progression of a track after it is disconnected
-         From experiments it appears that at least on Chrome v111 disconnected sources do not advance time, which leads to dis-synchronization when we later reconnected
-         To circumvent this issue we introduced "Suspended" flag to keep track of timing on disconnected tracks
-         */
-        emitter.tracks.forEach(this.suspendTrack, this)
-
-        this.__isConnected = false;
+        instance.setGainDb(this.#trackGainDb(track));
     }
 
-    link() {
-        this.transform.position.onChanged.add(this.update, this);
-
-        this.emitter.tracks.forEach(this.addTrack, this);
+    /**
+     * Composed live gain for a track: emitter.volume × track.volume, in dB.
+     * @param {SoundTrack} track
+     * @returns {number}
+     */
+    #trackGainDb(track) {
+        return volume2dB(this.emitter.volume.getValue() * track.volume);
+    }
 
-        this.emitter.tracks.on.added.add(this.addTrack, this);
-        this.emitter.tracks.on.removed.add(this.removeTrack, this);
+    /**
+     * Fade every owned instance out and stop it (backs SoundEmitter.fadeOutAllTracks).
+     * @param {number} duration
+     */
+    fadeOutAll(duration) {
+        this.#instances.forEach((instance) => {
+            instance.fadeOutAndStop(duration);
+        });
     }
 
-    unlink() {
-        this.transform.position.onChanged.remove(this.update, this);
+    /**
+     * Stop every owned instance immediately (backs SoundEmitter.stopAllTracks + unlink).
+     *
+     * Detach the track↔instance bindings BEFORE stopping: stop() fires onEnded synchronously, and
+     * #onInstanceEnded must bail out (it keys off #instances) so teardown doesn't fire track.on.ended
+     * or mutate the emitter's authored track list.
+     */
+    stopAll() {
+        const instances = [];
 
-        this.emitter.tracks.on.added.remove(this.addTrack, this);
-        this.emitter.tracks.on.removed.remove(this.removeTrack, this);
+        this.#instances.forEach((instance, track) => {
+            track.__instance = null;
+            track.__soundRuntime = null;
+            instances.push(instance);
+        });
 
-        this.emitter.tracks.forEach(this.removeTrack, this);
+        this.#instances.clear();
 
-        this.disconnect();
+        for (let i = 0; i < instances.length; i++) {
+            instances[i].stop();
+        }
     }
-
-
 }

package/src/engine/sound/ecs/emitter/SoundEmitterSystem.d.ts

@@ -4,108 +4,85 @@ export namespace SoundEmitterChannels {
     let Music: string;
     let Ambient: string;
 }
+/**
+ * @deprecated Legacy emitter system — superseded by {@link AudioEmitterSystem} (which drives the native
+ * {@link AudioEmitter}). Retained to keep existing {@link SoundEmitter} content working during the
+ * strangler migration; not for new content.
+ *
+ * Routes the legacy {@link SoundEmitter} component through the sopra engine — sopra is the single
+ * renderer. The system no longer builds a WebAudio graph: it creates + owns-on-{@link SoundEngine} the
+ * sopra engine, and per linked emitter builds a {@link SoundEmitterComponentContext} translation record
+ * that turns the emitter's tracks into sopra event instances. Each frame it forwards the listener pose
+ * and ticks sopra.
+ *
+ * The channel ids (effects/music/ambient) are sopra bus ids 1:1 at the same legacy mix; the deprecated
+ * get/setChannelVolume proxy onto the sopra buses.
+ */
 export class SoundEmitterSystem extends System<any, any, any, any, any> {
     /**
-     *
      * @param {AssetManager} assetManager
-     * @param {AudioNode} destinationNode
-     * @param {AudioContext} context
+     * @param {SoundEngine} soundEngine owns the AudioContext + master destination + sopra engine
      * @constructor
-     * @property {AssetManager} assetManager
      */
-    constructor(assetManager: AssetManager, destinationNode: AudioNode, context: AudioContext);
+    constructor(assetManager: AssetManager, soundEngine: SoundEngine);
     dependencies: (typeof Transform | typeof SoundEmitter)[];
-    destinationNode: AudioNode;
     /**
-     *
+     * @type {SoundEngine}
+     */
+    soundEngine: SoundEngine;
+    /**
      * @type {AudioContext}
      */
     webAudioContext: AudioContext;
+    destinationNode: any;
     assetManager: AssetManager;
     /**
-     *
-     * @type {Object<SoundEmitterChannel>}
-     */
-    channels: any;
-    /**
-     *
-     * @type {SoundEmitterComponentContext[]}
-     */
-    data: SoundEmitterComponentContext[];
-    /**
-     *
-     * @type {IncrementalDeltaSet<SoundEmitterComponentContext>}
-     */
-    activeSet: IncrementalDeltaSet<SoundEmitterComponentContext>;
-    /**
-     * Spatial index
-     * @type {BVH}
-     * @private
+     * The sopra engine — the single renderer. Owned by SoundEngine; created here because we have
+     * the AssetManager. Reuses the single SoundAssetLoader registered above (no double registration).
+     * @type {SopraEngine}
      */
-    private __bvh;
+    sopra: SopraEngine;
     /**
-     * Number of currently linked entities
-     * @type {number}
-     * @private
+     * @deprecated channel ids are sopra bus ids now; retained as a name set for the editor's
+     * channel dropdown. Volume lives on the sopra buses (see get/setChannelVolume).
+     * @type {Object<string,string>}
      */
-    private __linkedCount;
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
+    channels: {
+        [x: string]: string;
+    };
     /**
-     *
-     * @param {SoundEmitterComponentContext} ctx
-     */
-    handleContextActivation(ctx: SoundEmitterComponentContext): void;
-    /**
-     *
-     * @param {SoundEmitterComponentContext} ctx
+     * Per-entity translation records.
+     * @type {SoundEmitterComponentContext[]}
      */
-    handleContextDeactivation(ctx: SoundEmitterComponentContext): void;
+    data: SoundEmitterComponentContext[];
     /**
-     *
+     * @deprecated channel volume is a sopra bus volume now; proxies to it.
      * @param {String} name
      * @returns {number}
      */
     getChannelVolume(name: string): number;
     /**
-     *
+     * @deprecated channel volume is a sopra bus volume now; proxies to it.
      * @param {String} name
      * @param {number} value
      */
     setChannelVolume(name: string, value: number): void;
-    addChannel(name: any): this;
     /**
-     *
-     * @param {String} name
-     * @returns {boolean}
-     */
-    hasChannel(name: string): boolean;
-    /**
-     *
      * @param {SoundEmitter} emitter
      * @param {Transform} transform
      * @param {number} entity
      */
     link(emitter: SoundEmitter, transform: Transform, entity: number): void;
     /**
-     *
      * @param {SoundEmitter} emitter
      * @param {Transform} transform
      * @param {number} entity
      */
     unlink(emitter: SoundEmitter, transform: Transform, entity: number): void;
-    /**
-     *
-     * @param {SoundEmitterComponentContext} emitter
-     * @returns {boolean}
-     */
-    emitter_in_hearing_range(emitter: SoundEmitterComponentContext): boolean;
     update(timeDelta: any): void;
-    #private;
 }
 import { System } from '../../../ecs/System.js';
 import { Transform } from '../../../ecs/transform/Transform.js';
 import { SoundEmitter } from './SoundEmitter.js';
 import { SoundEmitterComponentContext } from "./SoundEmitterComponentContext.js";
-import { IncrementalDeltaSet } from "../../../graphics/render/visibility/IncrementalDeltaSet.js";
 //# sourceMappingURL=SoundEmitterSystem.d.ts.map

package/src/engine/sound/ecs/emitter/SoundEmitterSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoundEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/emitter/SoundEmitterSystem.js"],"names":[],"mappings":"mCAmBU,MAAM;;;;;;AAchB;IACI;;;;;;;OAOG;IACH,yDALW,SAAS,WACT,YAAY,EA0DtB;IAnDG,yDAA6C;IAG7C,2BAAsC;IACtC;;;OAGG;IACH,iBAFU,YAAY,CAEQ;IAC9B,2BAAgC;IAEhC;;;OAGG;IACH,cAAkB;IAWlB;;;OAGG;IACH,MAFU,4BAA4B,EAAE,CAE1B;IAEd;;;OAGG;IACH,WAFU,oBAAoB,4BAA4B,CAAC,CAEE;IAE7D;;;;OAIG;IACH,cAAsB;IAEtB;;;;OAIG;IACH,sBAAsB;IAG1B,2CAGC;IAED,4CAGC;IAED;;;OAGG;IACH,6BAFW,4BAA4B,QAItC;IAED;;;OAGG;IACH,+BAFW,4BAA4B,QAItC;IAED;;;;OAIG;IACH,gCAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,sCAFW,MAAM,QAIhB;IAED,4BAeC;IAED;;;;OAIG;IACH,0BAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,cAJW,YAAY,aACZ,SAAS,UACT,MAAM,QA6DhB;IAED;;;;;OAKG;IACH,gBAJW,YAAY,aACZ,SAAS,UACT,MAAM,QAmBhB;IAED;;;;OAIG;IACH,kCAHW,4BAA4B,GAC1B,OAAO,CAKnB;IAQD,6BA6GC;;CAGJ;uBA7XsB,wBAAwB;0BACrB,qCAAqC;6BAGlC,mBAAmB;6CAEH,mCAAmC;oCAJ5C,4DAA4D"}
+{"version":3,"file":"SoundEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/emitter/SoundEmitterSystem.js"],"names":[],"mappings":"mCAWU,MAAM;;;;;;AAQhB;;;;;;;;;;;;;GAaG;AACH;IACI;;;;OAIG;IACH,kEA4CC;IAzCG,yDAA6C;IAE7C;;OAEG;IACH,yBAA8B;IAE9B;;OAEG;IACH,iBAFU,YAAY,CAEoB;IAE1C,qBAA8C;IAE9C,2BAAgC;IAIhC;;;;OAIG;IACH,mBAAkF;IAElF;;;;OAIG;IACH;YAFiB,MAAM,GAAC,MAAM;MAM7B;IAED;;;OAGG;IACH,MAFU,4BAA4B,EAAE,CAE1B;IAGlB;;;;OAIG;IACH,gCAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,sCAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,YAAY,aACZ,SAAS,UACT,MAAM,QAahB;IAED;;;;OAIG;IACH,gBAJW,YAAY,aACZ,SAAS,UACT,MAAM,QAUhB;IAED,6BAgBC;CACJ;uBAvJsB,wBAAwB;0BACrB,qCAAqC;6BAGlC,mBAAmB;6CACH,mCAAmC"}