@woosh/meep-engine 3.2.0 → 3.4.0

package/src/engine/sound/SoundEngine.js

@@ -1,124 +1,124 @@
-import { SopraEngine } from "./sopra/SopraEngine.js";
-
-/**
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-class SoundEngine {
-    /**
-     * The sopra (FMOD/Wwise-style) engine, created and owned here once the AssetManager-backed
-     * buffer provider is available (see {@link obtainSopra}, called from SoundEmitterSystem).
-     * @type {SopraEngine|null}
-     */
-    sopra = null;
-
-    /**
-     *
-     * @constructor
-     */
-    constructor() {
-        // Fix up prefixing
-        let AudioContext = (
-            window.AudioContext ||
-            null
-        );
-
-        if (!AudioContext) {
-            throw new Error("AudioContext not supported!");
-        }
-
-        // Create a new audio context.
-        const context = this.context = new AudioContext({
-            /*
-             * The type of playback that the context will be used for, as a value from the AudioContextLatencyCategory enum or a double-precision floating-point value indicating the preferred maximum latency of the context in seconds. The user agent may or may not choose to meet this request; check the value of AudioContext.baseLatency to determine the true latency after creating the context.
-             *
-             * Values:
-             *
-             * "balanced"	    The user agent should balance audio output latency and power consumption when selecting a latency value.
-             * "interactive"	The audio is involved in interactive elements, such as responding to user actions or needing to coincide with visual cues such as a video or game action. The user agent should select the lowest possible latency that doesn't cause glitches in the audio. This is likely to require increased power consumption. This is the default value.
-             * "playback"	    The user agent should select a latency that will maximize playback time by minimizing power consumption at the expense of latency. Useful for non-interactive playback, such as playing music.
-             */
-            latencyHint: 'interactive'
-        });
-
-        //start suspended to keep chrome satisfied, otherwise it prints a warning
-        context.suspend();
-
-        // master volume
-        const gainNode = context.createGain();
-
-        // Dynamic compressor makes quiet sounds louder and loud quieter
-        const compressor = context.createDynamicsCompressor();
-        this.destination = gainNode;
-        gainNode.connect(compressor);
-        compressor.connect(context.destination);
-
-        // master channel
-        Object.defineProperties(this, {
-            volume: {
-                get: function () {
-                    return gainNode.gain.value;
-                },
-                set: function (val) {
-                    gainNode.gain.setValueAtTime(val, context.currentTime, 0);
-                }
-            }
-        });
-    }
-
-    /**
-     * Create and own the sopra engine, built on this SoundEngine's existing AudioContext + master
-     * destination (never a second context). Wired in by the sound systems, which supply an
-     * AssetManager-backed buffer provider.
-     *
-     * Idempotent: the SopraEngine is a singleton on the SoundEngine, so the first caller creates it and
-     * later callers reuse it (the `bufferProvider` of later calls is ignored). This lets multiple
-     * systems — e.g. the legacy SoundEmitterSystem and the native AudioEmitterSystem — share one engine.
-     * @param {BufferProvider} bufferProvider
-     * @returns {SopraEngine}
-     */
-    obtainSopra(bufferProvider) {
-        if (this.sopra === null) {
-            this.sopra = new SopraEngine(this.context, this.destination, bufferProvider);
-        }
-
-        return this.sopra;
-    }
-
-    /**
-     *
-     * @return {number}
-     */
-    getCurrentTime() {
-        return this.context.currentTime;
-    }
-
-    /**
-     * Audio context needs to be resumed as it is created in suspended state by default
-     * @see https://developers.google.com/web/updates/2017/09/autoplay-policy-changes#webaudio
-     * @returns {Promise<void>}
-     */
-    resumeContext() {
-        const pResumed = this.context.resume();
-
-        return pResumed;
-    }
-
-    /**
-     *
-     * @returns {Promise<any>}
-     */
-    start() {
-
-        return new Promise((resolve, reject) => {
-            //don't want for context to be resumed
-            const promise = this.resumeContext();
-
-
-            resolve();
-        });
-    }
-}
-
-export default SoundEngine;
+import { SopraEngine } from "./sopra/SopraEngine.js";
+
+/**
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+class SoundEngine {
+    /**
+     * The sopra (FMOD/Wwise-style) engine, created and owned here once the AssetManager-backed
+     * buffer provider is available (see {@link obtainSopra}, called from the sound systems).
+     * @type {SopraEngine|null}
+     */
+    sopra = null;
+
+    /**
+     *
+     * @constructor
+     */
+    constructor() {
+        // Fix up prefixing
+        let AudioContext = (
+            window.AudioContext ||
+            null
+        );
+
+        if (!AudioContext) {
+            throw new Error("AudioContext not supported!");
+        }
+
+        // Create a new audio context.
+        const context = this.context = new AudioContext({
+            /*
+             * The type of playback that the context will be used for, as a value from the AudioContextLatencyCategory enum or a double-precision floating-point value indicating the preferred maximum latency of the context in seconds. The user agent may or may not choose to meet this request; check the value of AudioContext.baseLatency to determine the true latency after creating the context.
+             *
+             * Values:
+             *
+             * "balanced"	    The user agent should balance audio output latency and power consumption when selecting a latency value.
+             * "interactive"	The audio is involved in interactive elements, such as responding to user actions or needing to coincide with visual cues such as a video or game action. The user agent should select the lowest possible latency that doesn't cause glitches in the audio. This is likely to require increased power consumption. This is the default value.
+             * "playback"	    The user agent should select a latency that will maximize playback time by minimizing power consumption at the expense of latency. Useful for non-interactive playback, such as playing music.
+             */
+            latencyHint: 'interactive'
+        });
+
+        //start suspended to keep chrome satisfied, otherwise it prints a warning
+        context.suspend();
+
+        // master volume
+        const gainNode = context.createGain();
+
+        // Dynamic compressor makes quiet sounds louder and loud quieter
+        const compressor = context.createDynamicsCompressor();
+        this.destination = gainNode;
+        gainNode.connect(compressor);
+        compressor.connect(context.destination);
+
+        // master channel
+        Object.defineProperties(this, {
+            volume: {
+                get: function () {
+                    return gainNode.gain.value;
+                },
+                set: function (val) {
+                    gainNode.gain.setValueAtTime(val, context.currentTime, 0);
+                }
+            }
+        });
+    }
+
+    /**
+     * Create and own the sopra engine, built on this SoundEngine's existing AudioContext + master
+     * destination (never a second context). Wired in by the sound systems, which supply an
+     * AssetManager-backed buffer provider.
+     *
+     * Idempotent: the SopraEngine is a singleton on the SoundEngine, so the first caller creates it and
+     * later callers reuse it (the `bufferProvider` of later calls is ignored). This lets multiple
+     * systems — e.g. AudioEmitterSystem and AudioEventTriggerSystem — share one engine.
+     * @param {BufferProvider} bufferProvider
+     * @returns {SopraEngine}
+     */
+    obtainSopra(bufferProvider) {
+        if (this.sopra === null) {
+            this.sopra = new SopraEngine(this.context, this.destination, bufferProvider);
+        }
+
+        return this.sopra;
+    }
+
+    /**
+     *
+     * @return {number}
+     */
+    getCurrentTime() {
+        return this.context.currentTime;
+    }
+
+    /**
+     * Audio context needs to be resumed as it is created in suspended state by default
+     * @see https://developers.google.com/web/updates/2017/09/autoplay-policy-changes#webaudio
+     * @returns {Promise<void>}
+     */
+    resumeContext() {
+        const pResumed = this.context.resume();
+
+        return pResumed;
+    }
+
+    /**
+     *
+     * @returns {Promise<any>}
+     */
+    start() {
+
+        return new Promise((resolve, reject) => {
+            //don't want for context to be resumed
+            const promise = this.resumeContext();
+
+
+            resolve();
+        });
+    }
+}
+
+export default SoundEngine;

package/src/engine/sound/ecs/audio/AudioEmitter.d.ts

@@ -59,6 +59,25 @@ export class AudioEmitter {
      * @type {AcousticDirectivity}
      */
     directivity: AcousticDirectivity;
+    /**
+     * Observation surface, not authored state — deliberately absent from {@link toJSON}, {@link equals}
+     * and {@link hash}: two emitters that differ only in who is listening are the same emitter, and a
+     * subscriber must never change what a save contains or which polyphony bucket a voice lands in.
+     *
+     * `ended` fires (with this emitter) when a **direct** instance finishes on its own — the
+     * component-level end the legacy `SoundTrack.on.ended` provided, which is what lets an entity builder
+     * destroy a fire-and-forget sound entity the moment it stops sounding instead of reaching into
+     * {@link AudioEmitterSystem} for its instance. Two things it deliberately does not do: it does not
+     * fire when the emitter is unlinked (stop ≠ ended), and it never fires for a spatially managed
+     * emitter — that route carries looping events only, so there is no end to report, and its instances
+     * come and go with promotion and demotion.
+     *
+     * @readonly
+     * @type {{ended: Signal<AudioEmitter>}}
+     */
+    readonly on: {
+        ended: Signal<AudioEmitter>;
+    };
     /**
      * @param {AudioEmitter} other
      * @returns {boolean}
@@ -103,4 +122,5 @@ export namespace AudioEmitter {
 import { EventDescription } from "../../sopra/definition/EventDescription.js";
 import Vector1 from "../../../../core/geom/Vector1.js";
 import { AcousticDirectivity } from "../../simulation/definition/AcousticDirectivity.js";
+import Signal from "../../../../core/events/signal/Signal.js";
 //# sourceMappingURL=AudioEmitter.d.ts.map

package/src/engine/sound/ecs/audio/AudioEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AudioEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitter.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH;IAwGI;;;OAGG;IACH,4BAFa,YAAY,CAMxB;IA9GD;;;;;;;;;;;;OAYG;IACH,OAFU,gBAAgB,CAEK;IAE/B;;;OAGG;IACH,QAFU,OAAO,CAEO;IAExB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;OAKG;IACH,cAFU,MAAM,CAEI;IAEpB;;;;;OAKG;IACH,aAFU,mBAAmB,CAEW;IAExC;;;OAGG;IACH,cAHW,YAAY,GACV,OAAO,CASnB;IAED,eASC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MASC;IAED,0BAaC;CAWJ;;;;iCA5HgC,4CAA4C;oBAHzD,kCAAkC;oCAElB,oDAAoD"}
+{"version":3,"file":"AudioEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitter.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IA4HI;;;OAGG;IACH,4BAFa,YAAY,CAMxB;IAlID;;;;;;;;;;;;OAYG;IACH,OAFU,gBAAgB,CAEK;IAE/B;;;OAGG;IACH,QAFU,OAAO,CAEO;IAExB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;OAKG;IACH,cAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,aAFU,mBAAmB,CAEW;IAExC;;;;;;;;;;;;;;;OAeG;IACH,aAFU;QAAC,KAAK,EAAE,OAAO,YAAY,CAAC,CAAA;KAAC,CAIrC;IAEF;;;OAGG;IACH,cAHW,YAAY,GACV,OAAO,CASnB;IAED,eASC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MASC;IAED,0BAaC;CAWJ;;;;iCAlJgC,4CAA4C;oBAHzD,kCAAkC;oCAElB,oDAAoD;mBAHrE,0CAA0C"}

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

@@ -1,9 +1,12 @@
 import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import Signal from "../../../../core/events/signal/Signal.js";
 import Vector1 from "../../../../core/geom/Vector1.js";
 import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
 import { AcousticDirectivity } from "../../simulation/definition/AcousticDirectivity.js";
 import { EventDescription } from "../../sopra/definition/EventDescription.js";
 
+const DEFAULT_SOURCE_RADIUS = 0.05;
+
 /**
  * Native ECS sound component (the user-facing replacement for the legacy `SoundEmitter`). Unlike
  * `SoundEmitter` — which holds a list of tracks that get *translated* into sopra events — an
@@ -57,7 +60,7 @@ export class AudioEmitter {
      * meaningful when {@link acoustic}. Carried onto the played {@link EventInstance}.
      * @type {number}
      */
-    sourceRadius = 0.05;
+    sourceRadius = DEFAULT_SOURCE_RADIUS;
 
     /**
      * Radiation directivity of this source (which way it "points" its sound). Default omni (monopole) — no
@@ -67,6 +70,26 @@ export class AudioEmitter {
      */
     directivity = new AcousticDirectivity();
 
+    /**
+     * Observation surface, not authored state — deliberately absent from {@link toJSON}, {@link equals}
+     * and {@link hash}: two emitters that differ only in who is listening are the same emitter, and a
+     * subscriber must never change what a save contains or which polyphony bucket a voice lands in.
+     *
+     * `ended` fires (with this emitter) when a **direct** instance finishes on its own — the
+     * component-level end the legacy `SoundTrack.on.ended` provided, which is what lets an entity builder
+     * destroy a fire-and-forget sound entity the moment it stops sounding instead of reaching into
+     * {@link AudioEmitterSystem} for its instance. Two things it deliberately does not do: it does not
+     * fire when the emitter is unlinked (stop ≠ ended), and it never fires for a spatially managed
+     * emitter — that route carries looping events only, so there is no end to report, and its instances
+     * come and go with promotion and demotion.
+     *
+     * @readonly
+     * @type {{ended: Signal<AudioEmitter>}}
+     */
+    on = {
+        ended: new Signal()
+    };
+
     /**
      * @param {AudioEmitter} other
      * @returns {boolean}
@@ -111,7 +134,7 @@ export class AudioEmitter {
         }
         this.autoplay = json.autoplay !== undefined ? json.autoplay : true;
         this.acoustic = json.acoustic !== undefined ? json.acoustic : false;
-        this.sourceRadius = json.sourceRadius !== undefined ? json.sourceRadius : 0.5;
+        this.sourceRadius = json.sourceRadius !== undefined ? json.sourceRadius : DEFAULT_SOURCE_RADIUS;
         if (json.directivity !== undefined) {
             this.directivity.fromJSON(json.directivity);
         }

package/src/engine/sound/ecs/audio/AudioEmitterSystem.d.ts

@@ -1,8 +1,8 @@
 /**
- * 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.
+ * 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):
@@ -22,7 +22,7 @@
  * 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.
+ * and is the sole owner of the per-frame sopra tick and listener pose.
  */
 export class AudioEmitterSystem extends System<any> {
     /**
@@ -82,7 +82,7 @@ export class AudioEmitterSystem extends System<any> {
      */
     assetManager: AssetManager;
     /**
-     * The shared sopra engine (idempotent create — reused if the legacy system already made it).
+     * The shared sopra engine (idempotent create — reused if another sound system already made it).
      * @type {SopraEngine}
      */
     sopra: SopraEngine;

package/src/engine/sound/ecs/audio/AudioEmitterSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AudioEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSystem.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAgCI;;;;;OAKG;IACH,0FAHW;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAA;KAAC,qBA+C1E;IAjFD,yDAAyC;IAEzC;;;;;OAKG;IACH,iBAFU,kBAAkB,CAEA;IAE5B;;;OAGG;IACH,cAFU,eAAe,CAEP;IAElB;;;;;OAKG;IACH,MAFU,MAAM,EAAE,CAER;IAEV;;;;OAIG;IACH,aAFU,sBAAoB,IAAI,CAEf;IAWf;;;;;OAKG;IACH,aAFU,oBAAkB,IAAI,CAEF;IAE9B;;OAEG;IACH,yBAA8B;IAE9B;;OAEG;IACH,iBAFU,YAAY,CAEoB;IAE1C;;OAEG;IACH,2BAAgC;IAQhC;;;OAGG;IACH,mBAAkF;IAElF;;;;OAIG;IACH,SAFU,cAAc,CAE4C;IAGxE;;;;OAIG;IACH,cAJW,YAAY,aACZ,SAAS,UACT,MAAM,QA4BhB;IAED;;;;OAIG;IACH,gBAJW,YAAY,aACZ,SAAS,UACT,MAAM,QAoBhB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,gBAAc,IAAI,CAe9B;IA4CD,6BAqEC;;CACJ;uBAvTsB,wBAAwB;0BACrB,qCAAqC;6BAKlC,mBAAmB;+BACjB,qBAAqB"}
+{"version":3,"file":"AudioEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSystem.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAgCI;;;;;OAKG;IACH,0FAHW;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAA;KAAC,qBA+C1E;IAjFD,yDAAyC;IAEzC;;;;;OAKG;IACH,iBAFU,kBAAkB,CAEA;IAE5B;;;OAGG;IACH,cAFU,eAAe,CAEP;IAElB;;;;;OAKG;IACH,MAFU,MAAM,EAAE,CAER;IAEV;;;;OAIG;IACH,aAFU,sBAAoB,IAAI,CAEf;IAWf;;;;;OAKG;IACH,aAFU,oBAAkB,IAAI,CAEF;IAE9B;;OAEG;IACH,yBAA8B;IAE9B;;OAEG;IACH,iBAFU,YAAY,CAEoB;IAE1C;;OAEG;IACH,2BAAgC;IAQhC;;;OAGG;IACH,mBAAkF;IAElF;;;;OAIG;IACH,SAFU,cAAc,CAE4C;IAGxE;;;;OAIG;IACH,cAJW,YAAY,aACZ,SAAS,UACT,MAAM,QAoChB;IAED;;;;OAIG;IACH,gBAJW,YAAY,aACZ,SAAS,UACT,MAAM,QA4BhB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,gBAAc,IAAI,CAe9B;IAoDD,6BAqEC;;CACJ;uBA/UsB,wBAAwB;0BACrB,qCAAqC;6BAKlC,mBAAmB;+BACjB,qBAAqB"}