@woosh/meep-engine 2.163.10 → 2.164.0

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

@@ -36,16 +36,54 @@ import { LiveEmitterSet } from "./LiveEmitterSet.js";
  * so it coexists with the legacy `SoundEmitterSystem` during the strangler migration.
  */
 export class AudioEmitterSystem extends System {
+    dependencies = [AudioEmitter, Transform];
+
+    /**
+     * Live direct-path instances (2D + finite 3D one-shots). Tracked separately so the per-frame
+     * acoustic pass enumerates only the few direct instances + the managed live set — never all
+     * registered emitters.
+     * @type {Set<EventInstance>}
+     */
+    directInstances = new Set();
+
+    /**
+     * Reused scratch array of live acoustic instances fed to {@link acousticSim} each frame.
+     * @type {EventInstance[]}
+     */
+    acousticLive = [];
+
+    /**
+     * Per-entity records: { emitter, transform, managed, instance, onVolume }. For a managed (3D)
+     * emitter the playing instance lives in {@link liveSet} (record.instance stays null); for a
+     * direct (2D) emitter it is held here.
+     * @type {object[]}
+     */
+    data = [];
+
     /**
      * @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 = {}) {
+    constructor(assetManager, soundEngine, liveEmitterSetOptions = {}, acousticSim = null) {
         super();
 
-        this.dependencies = [AudioEmitter, Transform];
+        /**
+         * 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;
+
+        /**
+         * 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}
+         */
+        this.probeReverb = null;
+
 
         /**
          * @type {SoundEngine}
@@ -72,7 +110,7 @@ export class AudioEmitterSystem extends System {
          * The shared sopra engine (idempotent create — reused if the legacy system already made it).
          * @type {SopraEngine}
          */
-        this.sopra = soundEngine.createSopra(new AssetManagerBufferProvider(assetManager));
+        this.sopra = soundEngine.obtainSopra(new AssetManagerBufferProvider(assetManager));
 
         /**
          * Spatial lifecycle for 3D ("managed") emitters: BVH cull → promote nearest-in-range up to the
@@ -81,13 +119,6 @@ export class AudioEmitterSystem extends System {
          */
         this.liveSet = new LiveEmitterSet(this.sopra, liveEmitterSetOptions);
 
-        /**
-         * 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[]}
-         */
-        this.data = [];
     }
 
     /**
@@ -104,11 +135,16 @@ export class AudioEmitterSystem extends System {
         const record = { emitter, transform, managed, instance: null, onVolume: null };
 
         if (managed) {
-            this.liveSet.add(entity, emitter.event, transform.position, volume2dB(emitter.volume.getValue()));
+            const pathing = emitter.acoustic && this.acousticSim !== null && this.acousticSim.pathing;
+            this.liveSet.add(entity, emitter.event, transform.position, volume2dB(emitter.volume.getValue()), emitter.acoustic, pathing, emitter.sourceRadius, transform.rotation, emitter.directivity);
             record.onVolume = () => this.liveSet.setGainDb(entity, volume2dB(emitter.volume.getValue()));
         } else {
             if (emitter.autoplay) {
                 record.instance = this.#play(emitter, transform);
+
+                if (record.instance !== null) {
+                    this.directInstances.add(record.instance);
+                }
             }
             record.onVolume = () => this.#applyVolume(record);
         }
@@ -137,6 +173,7 @@ export class AudioEmitterSystem extends System {
         if (record.managed) {
             this.liveSet.remove(entity); // demotes (hard cut) if live, then unregisters
         } else if (record.instance !== null) {
+            this.directInstances.delete(record.instance);
             record.instance.stop();
             record.instance = null;
         }
@@ -180,7 +217,12 @@ export class AudioEmitterSystem extends System {
         const instance = this.sopra.playEvent(event, {
             busId: event.busId,
             position: transform.position, // shared Vector3 — tracks the entity as it moves
-            oneShot
+            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) {
@@ -207,6 +249,7 @@ export class AudioEmitterSystem extends System {
         const ecd = this.entityManager.dataset;
 
         let listenerPosition = null;
+        let listenerRotation = null;
 
         if (ecd !== null) {
             const soundListener = ecd.getAnyComponent(SoundListener);
@@ -219,6 +262,7 @@ export class AudioEmitterSystem extends System {
 
                 if (listenerTransform !== undefined) {
                     listenerPosition = listenerTransform.position;
+                    listenerRotation = listenerTransform.rotation;
                     sopra.setListener(listenerPosition);
                 }
             }
@@ -233,6 +277,40 @@ export class AudioEmitterSystem extends System {
             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);
     }
 }

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

@@ -60,8 +60,19 @@ export class LiveEmitterSet {
      * @param {EventDescription} event
      * @param {Vector3} position shared position vector (tracked reactively by the spatial index)
      * @param {number} [gainDb] per-emitter instance gain in dB, applied on every promotion (default 0 = unity)
+     * @param {boolean} [acoustic] opt the promoted instances into the acoustic simulation (default false)
+     * @param {boolean} [pathing] opt the promoted instances into corner-leakage render (default false)
+     * @param {number} [sourceRadius] apparent acoustic radius for volumetric occlusion (default 0.5)
+     * @param {Quaternion|null} [orientation] shared source orientation ref (tracks the entity), for directivity
+     * @param {AcousticDirectivity|null} [directivity] source radiation directivity (null = omni)
      */
-    add(entity: number, event: EventDescription, position: Vector3, gainDb?: number): void;
+    add(entity: number, event: EventDescription, position: Vector3, gainDb?: number, acoustic?: boolean, pathing?: boolean, sourceRadius?: number, orientation?: Quaternion | null, directivity?: AcousticDirectivity | null): void;
+    /**
+     * Invoke `callback` for each currently-live instance (bounded by the budget). Used by the
+     * `AudioEmitterSystem` to feed live spatial instances to the acoustic simulation.
+     * @param {function(EventInstance):void} callback
+     */
+    forEachLive(callback: (arg0: EventInstance) => void): void;
     /**
      * Set the per-emitter instance gain (dB). Updates the stored value so a future promotion replays it,
      * and applies it immediately if the emitter is currently live. A no-op for an unknown entity, and for

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

@@ -1 +1 @@
-{"version":3,"file":"LiveEmitterSet.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/LiveEmitterSet.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IA+DI;;;OAGG;IACH,6EAFW;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAA;KAAC,EAO1E;IAED;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;IAED;;;;;;OAMG;IACH,YALW,MAAM,uDAGN,MAAM,QAOhB;IAED;;;;;;;OAOG;IACH,kBAHW,MAAM,UACN,MAAM,QAehB;IAED;;;OAGG;IACH,eAFW,MAAM,QAShB;IAED;;;;;;;OAOG;IACH,yCAwDC;;CAgEJ"}
+{"version":3,"file":"LiveEmitterSet.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/LiveEmitterSet.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IA+DI;;;OAGG;IACH,6EAFW;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAA;KAAC,EAO1E;IAED;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;IAED;;;;;;;;;;;OAWG;IACH,YAVW,MAAM,uDAGN,MAAM,aACN,OAAO,YACP,OAAO,iBACP,MAAM,gBACN,aAAW,IAAI,gBACf,sBAAoB,IAAI,QAOlC;IAED;;;;OAIG;IACH,+CAFmC,IAAI,QAMtC;IAED;;;;;;;OAOG;IACH,kBAHW,MAAM,UACN,MAAM,QAehB;IAED;;;OAGG;IACH,eAFW,MAAM,QAShB;IAED;;;;;;;OAOG;IACH,yCAwDC;;CAqEJ"}

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

@@ -74,7 +74,7 @@ export class LiveEmitterSet {
      * entity -> { event, position, gainDb, playingSince }. `gainDb` is the per-emitter instance gain
      * (e.g. the owning `AudioEmitter.volume` in dB) re-applied on every promotion so it survives a
      * demote→re-promote cycle; `playingSince` carries the continuous-clock phase (see {@link add}).
-     * @type {Map<number, {event: EventDescription, position: Vector3, gainDb: number, playingSince: number}>}
+     * @type {Map<number, {event: EventDescription, position: Vector3, gainDb: number, playingSince: number, acoustic: boolean, pathing: boolean, sourceRadius: number, orientation: Quaternion|null, directivity: AcousticDirectivity|null}>}
      */
     #emitters = new Map();
 
@@ -149,12 +149,28 @@ export class LiveEmitterSet {
      * @param {EventDescription} event
      * @param {Vector3} position shared position vector (tracked reactively by the spatial index)
      * @param {number} [gainDb] per-emitter instance gain in dB, applied on every promotion (default 0 = unity)
+     * @param {boolean} [acoustic] opt the promoted instances into the acoustic simulation (default false)
+     * @param {boolean} [pathing] opt the promoted instances into corner-leakage render (default false)
+     * @param {number} [sourceRadius] apparent acoustic radius for volumetric occlusion (default 0.5)
+     * @param {Quaternion|null} [orientation] shared source orientation ref (tracks the entity), for directivity
+     * @param {AcousticDirectivity|null} [directivity] source radiation directivity (null = omni)
      */
-    add(entity, event, position, gainDb = 0) {
+    add(entity, event, position, gainDb = 0, acoustic = false, pathing = false, sourceRadius = 0.5, orientation = null, directivity = null) {
         this.#index.add(entity, event, position);
         // playingSince: continuous-clock semantics — the emitter has been "playing" since it linked, so a
         // later promotion resumes the loop at the phase it should be at (see #promote + EventInstance startTime).
-        this.#emitters.set(entity, { event, position, gainDb, playingSince: this.#sopra.currentTime });
+        this.#emitters.set(entity, { event, position, gainDb, playingSince: this.#sopra.currentTime, acoustic, pathing, sourceRadius, orientation, directivity });
+    }
+
+    /**
+     * Invoke `callback` for each currently-live instance (bounded by the budget). Used by the
+     * `AudioEmitterSystem` to feed live spatial instances to the acoustic simulation.
+     * @param {function(EventInstance):void} callback
+     */
+    forEachLive(callback) {
+        for (const instance of this.#live.values()) {
+            callback(instance);
+        }
     }
 
     /**
@@ -274,7 +290,12 @@ export class LiveEmitterSet {
             busId: event.busId,
             position: record.position,
             oneShot,
-            startTime: record.playingSince
+            startTime: record.playingSince,
+            acoustic: record.acoustic,
+            pathing: record.pathing,
+            sourceRadius: record.sourceRadius,
+            orientation: record.orientation,
+            directivity: record.directivity
         });
 
         if (instance === null) {

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

@@ -63,7 +63,7 @@ export class SoundEmitterSystem extends System {
          * the AssetManager. Reuses the single SoundAssetLoader registered above (no double registration).
          * @type {SopraEngine}
          */
-        this.sopra = soundEngine.createSopra(new AssetManagerBufferProvider(assetManager));
+        this.sopra = soundEngine.obtainSopra(new AssetManagerBufferProvider(assetManager));
 
         /**
          * @deprecated channel ids are sopra bus ids now; retained as a name set for the editor's

package/src/engine/sound/simulation/AcousticSimulator.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The acoustic simulation engine: owns the occluder index, the medium volume regions, the solvers, and
+ * the per-instance temporal state, and turns a source position into an {@link AcousticSolution} the
+ * render seam consumes. ECS-agnostic and WebAudio-agnostic — the ECS systems feed its geometry and the
+ * `AudioEmitterSystem` drives {@link apply}; both inject real objects, so it is unit-testable on bare
+ * geometry.
+ *
+ * Tunables are plain settable fields (not an opaque config bag): construct with no arguments, then set
+ * `rayCount`, `smoothing`, `random_seed`, `medium`, `pathing`, … after construction to taste.
+ */
+export class AcousticSimulator {
+    /**
+     * Rays cast per source per tick. Lower + temporal smoothing = cheaper, integrated over frames.
+     * @type {number}
+     */
+    rayCount: number;
+    /**
+     * EMA factor for temporal smoothing, (0, 1]. Smaller = smoother / slower to react.
+     * @type {number}
+     */
+    smoothing: number;
+    /**
+     * Engine-wide corner-leakage toggle. Off (default) = zero cost (no path branch, no graph search).
+     * On = occluded sources route a leaked send spatialized from their propagation exit point. Requires
+     * a probe field with a baked visibility graph ({@link setProbeField}).
+     * @type {boolean}
+     */
+    pathing: boolean;
+    /**
+     * Re-verify the visibility edges leaks traverse against LIVE geometry (dynamic-geometry policy — a door
+     * that closes after the bake re-blocks the leak). Off (default) = the baked graph is trusted as-is.
+     * Requires {@link pathing}. The recheck is budgeted ({@link recheckBudget}); a blocked edge is disabled
+     * by weight (no topology change), restored when it re-opens.
+     * @type {boolean}
+     */
+    pathingRecheck: boolean;
+    /**
+     * Max visibility edges re-verified per tick when {@link pathingRecheck} is on (one `anyHit` ray each).
+     * Bounds the recheck cost; leftover dirty edges round-robin to later ticks.
+     * @type {number}
+     */
+    recheckBudget: number;
+    set random_seed(arg: number);
+    /**
+     * RNG seed for deterministic ray jitter. Setting it re-seeds the generator (resets the jitter stream).
+     * Default {@link DEFAULT_RANDOM_SEED}.
+     * @returns {number}
+     */
+    get random_seed(): number;
+    set medium(arg: AcousticMedium);
+    /**
+     * The default medium for space outside every authored `AcousticVolume` region (ambient air). Default: a
+     * modest atmospheric absorption ({@link DEFAULT_AIR_ABSORPTION}); set it to dial the air thicker/thinner
+     * (or zero it for vacuum-clean falloff).
+     * @returns {AcousticMedium}
+     */
+    get medium(): AcousticMedium;
+    /**
+     * The occluder index, for offline baking (reverb / visibility) against the same scene geometry the
+     * runtime occludes with.
+     * @returns {AcousticOccluderIndex}
+     */
+    get occluderIndex(): AcousticOccluderIndex;
+    /**
+     * Register an occluder shape, placed by `matrix` (its canonical frame is local; the matrix is the
+     * world transform).
+     * @param {AbstractShape3D} shape
+     * @param {AcousticMaterial} material
+     * @param {Float32Array|number[]} [matrix]
+     * @returns {number} occluder handle
+     */
+    addOccluder(shape: AbstractShape3D, material: AcousticMaterial, matrix?: Float32Array | number[]): number;
+    /**
+     * @param {number} handle
+     * @param {Float32Array|number[]} matrix
+     */
+    setOccluderTransform(handle: number, matrix: Float32Array | number[]): void;
+    /**
+     * @param {number} handle
+     */
+    removeOccluder(handle: number): void;
+    /**
+     * @param {AcousticVolumeRegion} region
+     * @returns {AcousticVolumeRegion} the same region (for handle-keeping)
+     */
+    addRegion(region: AcousticVolumeRegion): AcousticVolumeRegion;
+    /**
+     * @param {AcousticVolumeRegion} region
+     */
+    removeRegion(region: AcousticVolumeRegion): void;
+    /**
+     * The baked probe field currently wired in (for pathing + probe reverb), or null if none. Paired with the
+     * {@link occluderIndex} it is what an offline re-bake (e.g. after deserialization) runs against.
+     * @returns {AcousticProbeField|null}
+     */
+    get probeField(): any;
+    /**
+     * Provide the baked probe field (with a visibility graph) that pathing routes through, or `null` to
+     * clear it. Required before {@link pathing} has any effect. The exit-field solver is dropped and lazily
+     * rebuilt for the new field.
+     * @param {AcousticProbeField|null} field a field with a baked visibility graph ({@link bakeVisibility})
+     */
+    setProbeField(field: AcousticProbeField | null): void;
+    /**
+     * Compute the full acoustic solution for a source at `source`, given `listener`, into `out`.
+     * @param {Vector3} listener
+     * @param {Vector3} source
+     * @param {number} sourceRadius apparent radius of the source (per-source; 0 = point source). For
+     *        volumetric (fractional) occlusion.
+     * @param {AcousticSourceState} state per-source temporal accumulation (mutated)
+     * @param {AcousticSolution} out
+     */
+    solveFor(listener: Vector3, source: Vector3, sourceRadius: number, state: AcousticSourceState, out: AcousticSolution): void;
+    /**
+     * Solve + push the result to every live instance. Each instance must expose a `position` (Vector3)
+     * and `setAcoustic(solution)`. Called once per frame by the `AudioEmitterSystem`, between the live-set
+     * refresh and the sopra tick.
+     * @param {EventInstance[]} liveInstances bounded set (≤ voice budget)
+     * @param {Vector3} listener
+     */
+    apply(liveInstances: EventInstance[], listener: Vector3): void;
+    /**
+     * Drop a live instance's accumulated state (call when the instance ends).
+     * @param {EventInstance} instance
+     */
+    forget(instance: EventInstance): void;
+    #private;
+}
+import { AcousticMedium } from "./core/AcousticMedium.js";
+import { AcousticOccluderIndex } from "./core/AcousticOccluderIndex.js";
+import { Vector3 } from "../../../core/geom/Vector3.js";
+import { AcousticSourceState } from "./core/AcousticSourceState.js";
+import { AcousticSolution } from "./core/AcousticSolution.js";
+//# sourceMappingURL=AcousticSimulator.d.ts.map

package/src/engine/sound/simulation/AcousticSimulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticSimulator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/simulation/AcousticSimulator.js"],"names":[],"mappings":"AAyCA;;;;;;;;;GASG;AACH;IACI;;;OAGG;IACH,UAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,SAFU,OAAO,CAED;IAEhB;;;;;;OAMG;IACH,gBAFU,OAAO,CAEM;IAEvB;;;;OAIG;IACH,eAFU,MAAM,CAEE;IAgGlB,6BAGC;IAZD;;;;OAIG;IACH,0BAEC;IAiBD,gCAEC;IAZD;;;;;OAKG;IACH,6BAEC;IAMD;;;;OAIG;IACH,2CAEC;IAED;;;;;;;OAOG;IACH,yEAHW,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CAIlB;IAED;;;OAGG;IACH,6BAHW,MAAM,UACN,YAAY,GAAC,MAAM,EAAE,QAI/B;IAED;;OAEG;IACH,uBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,8DAEC;IAED;;OAEG;IACH,iDAEC;IAED;;;;OAIG;IACH,sBAEC;IAED;;;;;OAKG;IACH,qBAFW,qBAAmB,IAAI,QAMjC;IAED;;;;;;;;OAQG;IACH,mBAPW,OAAO,UACP,OAAO,gBACP,MAAM,SAEN,mBAAmB,OACnB,gBAAgB,QAkB1B;IAED;;;;;;OAMG;IACH,qBAHW,eAAe,YACf,OAAO,QAuFjB;IAwOD;;;OAGG;IACH,sCAOC;;CACJ;+BAvnB8B,0BAA0B;sCACnB,iCAAiC;wBAL/C,+BAA+B;oCAQW,+BAA+B;iCADhE,4BAA4B"}