@woosh/meep-engine 3.14.5 → 3.15.0

package/src/engine/sound/SoundEngine.js

@@ -53,18 +53,36 @@ class SoundEngine {
         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);
-                }
-            }
-        });
+    /**
+     * The one master fader in the graph, and the only one worth reaching for.
+     *
+     * Everything is downstream of {@link destination}: {@link obtainSopra}
+     * passes it as the sopra bus tree's output, and a `ProbeReverbRenderer` is
+     * constructed against the same node, so the dry mix and the wet return both
+     * pass through this gain.
+     *
+     * The bus named `master` inside sopra is NOT this. The probe reverb's
+     * return joins the graph BELOW the bus tree, so `busGraph.setVolume('master', 0)`
+     * silences the dry signal and leaves the wet tail of every sound at full
+     * level — audible, and audible only in reverberant rooms.
+     *
+     * This was an `Object.defineProperties` block, which the declaration
+     * generator does not read, so `sound.volume = 0.5` was a compile error
+     * against a property that exists and works.
+     *
+     * @returns {number}
+     */
+    get volume() {
+        return this.destination.gain.value;
+    }
+
+    /**
+     * @param {number} value
+     */
+    set volume(value) {
+        this.destination.gain.setValueAtTime(value, this.context.currentTime, 0);
     }
 
     /**

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

@@ -14,18 +14,26 @@
  *
  * Returns the simulator so the caller can tune it (`rayCount`, `smoothing`, `random_seed`, `medium`), bake
  * against its `occluderIndex` (reverb / visibility), and enable corner-leakage (`pathing` + `setProbeField`).
- * For probe-baked reverb, pass a configured {@link ProbeReverbRenderer} as `options.probeReverb` (or assign
- * `audioEmitterSystem.probeReverb` yourself afterwards).
+ * For probe-baked reverb, pass a configured {@link ProbeReverbRenderer} as `probeReverb`. It reaches both
+ * halves: the emitter system, which drives it per frame, and {@link AcousticProbeFieldSystem}, which hands
+ * it the field on link. Assigning `audioEmitterSystem.probeReverb` yourself instead wires only the first,
+ * and a renderer with no field renders silence.
  *
  * Call once during engine configuration, after the `AudioEmitterSystem` is constructed (construct it
  * without an `acousticSim` argument — this injects it).
  *
- * @param {EngineConfiguration} configuration the config the acoustic systems are added to
+ * @param {{addManySystems: function(...System):*}} configuration whatever the systems are added to.
+ * Structural rather than {@link EngineConfiguration}, because `addManySystems` is the only method
+ * this helper calls and an application driving the {@link EntityManager} directly has no
+ * `EngineConfiguration` to hand it — `EngineConfiguration.systems` is `@private`, so the only way
+ * through was a collector object and an `as unknown as` cast (GAP-033).
  * @param {AudioEmitterSystem} audioEmitterSystem the system whose `update()` drives the simulation
  * @param {AcousticSimulator} [simulator] reuse this simulator instead of creating one (default: a fresh one)
  * @param {ProbeReverbRenderer} [probeReverb] optional probe-reverb renderer to wire (left untouched if omitted)
  * @returns {AcousticSimulator} the shared simulator (tune `random_seed` / `medium` on it directly)
  */
-export function configureAcousticSimulation(configuration: EngineConfiguration, audioEmitterSystem: AudioEmitterSystem, simulator?: AcousticSimulator, probeReverb?: ProbeReverbRenderer): AcousticSimulator;
+export function configureAcousticSimulation(configuration: {
+    addManySystems: (...args: System[]) => any;
+}, audioEmitterSystem: AudioEmitterSystem, simulator?: AcousticSimulator, probeReverb?: ProbeReverbRenderer): AcousticSimulator;
 import { AcousticSimulator } from "./AcousticSimulator.js";
 //# sourceMappingURL=configureAcousticSimulation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"configureAcousticSimulation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/simulation/configureAcousticSimulation.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,oIAJW,iBAAiB,sCAEf,iBAAiB,CAgB7B;kCA/CiC,wBAAwB"}
+{"version":3,"file":"configureAcousticSimulation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/simulation/configureAcousticSimulation.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,2DAVW;IAAC,cAAc,6BAAuB;CAAC,sDAMvC,iBAAiB,sCAEf,iBAAiB,CAgB7B;kCArDiC,wBAAwB"}

package/src/engine/sound/simulation/configureAcousticSimulation.js

@@ -19,13 +19,19 @@ import { AcousticVolumeSystem } from "./ecs/AcousticVolumeSystem.js";
  *
  * Returns the simulator so the caller can tune it (`rayCount`, `smoothing`, `random_seed`, `medium`), bake
  * against its `occluderIndex` (reverb / visibility), and enable corner-leakage (`pathing` + `setProbeField`).
- * For probe-baked reverb, pass a configured {@link ProbeReverbRenderer} as `options.probeReverb` (or assign
- * `audioEmitterSystem.probeReverb` yourself afterwards).
+ * For probe-baked reverb, pass a configured {@link ProbeReverbRenderer} as `probeReverb`. It reaches both
+ * halves: the emitter system, which drives it per frame, and {@link AcousticProbeFieldSystem}, which hands
+ * it the field on link. Assigning `audioEmitterSystem.probeReverb` yourself instead wires only the first,
+ * and a renderer with no field renders silence.
  *
  * Call once during engine configuration, after the `AudioEmitterSystem` is constructed (construct it
  * without an `acousticSim` argument — this injects it).
  *
- * @param {EngineConfiguration} configuration the config the acoustic systems are added to
+ * @param {{addManySystems: function(...System):*}} configuration whatever the systems are added to.
+ * Structural rather than {@link EngineConfiguration}, because `addManySystems` is the only method
+ * this helper calls and an application driving the {@link EntityManager} directly has no
+ * `EngineConfiguration` to hand it — `EngineConfiguration.systems` is `@private`, so the only way
+ * through was a collector object and an `as unknown as` cast (GAP-033).
  * @param {AudioEmitterSystem} audioEmitterSystem the system whose `update()` drives the simulation
  * @param {AcousticSimulator} [simulator] reuse this simulator instead of creating one (default: a fresh one)
  * @param {ProbeReverbRenderer} [probeReverb] optional probe-reverb renderer to wire (left untouched if omitted)
@@ -35,7 +41,7 @@ export function configureAcousticSimulation(configuration, audioEmitterSystem, s
     configuration.addManySystems(
         new AcousticSimulationSystem(simulator),
         new AcousticVolumeSystem(simulator),
-        new AcousticProbeFieldSystem(simulator)
+        new AcousticProbeFieldSystem(simulator, probeReverb ?? null)
     );
 
     audioEmitterSystem.acousticSim = simulator;

package/src/engine/sound/simulation/ecs/AcousticProbeFieldSystem.d.ts

@@ -15,8 +15,10 @@
 export class AcousticProbeFieldSystem extends System<any> {
     /**
      * @param {AcousticSimulator} simulator the shared simulation engine
+     * @param {ProbeReverbRenderer} [probeReverb] renderer to hand the field to alongside the
+     * simulator. {@link configureAcousticSimulation} passes the one it is given.
      */
-    constructor(simulator: AcousticSimulator);
+    constructor(simulator: AcousticSimulator, probeReverb?: ProbeReverbRenderer);
     dependencies: (typeof AcousticProbeField)[];
     /**
      * @type {AcousticSimulator}

package/src/engine/sound/simulation/ecs/AcousticProbeFieldSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AcousticProbeFieldSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/ecs/AcousticProbeFieldSystem.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH;IASI;;OAEG;IACH,0CAOC;IAlBD,4CAAoC;IAchC;;OAEG;IACH,6BAA0B;IAG9B;;;OAGG;IACH,YAHW,kBAAkB,UAClB,MAAM,QAShB;IAED;;;OAGG;IACH,cAHW,kBAAkB,UAClB,MAAM,QAShB;;CACJ;uBA/DsB,wBAAwB;mCACZ,gCAAgC"}
+{"version":3,"file":"AcousticProbeFieldSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/ecs/AcousticProbeFieldSystem.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH;IAuBI;;;;OAIG;IACH,6EASC;IApCD,4CAAoC;IA8BhC;;OAEG;IACH,6BAA0B;IAK9B;;;OAGG;IACH,YAHW,kBAAkB,UAClB,MAAM,QAahB;IAED;;;OAGG;IACH,cAHW,kBAAkB,UAClB,MAAM,QAahB;;CACJ;uBAzFsB,wBAAwB;mCACZ,gCAAgC"}

package/src/engine/sound/simulation/ecs/AcousticProbeFieldSystem.js

@@ -24,16 +24,34 @@ export class AcousticProbeFieldSystem extends System {
      */
     #field = null;
 
+    /**
+     * The renderer that plays the field's baked reverberation, if there is one.
+     *
+     * Its absence was the whole of GAP-031, reported from a port. The docblock above says the
+     * field's "baked reverb feeds the probe-reverb renderer", `ProbeReverbRenderer` has its own
+     * `setProbeField`, and nothing called it: `link` handed the field to the simulator — which
+     * uses it only for corner-leak pathing — and the half that plays the reverberation kept a
+     * null field, whose `update` returns immediately. Attaching a field and hearing nothing was
+     * the default outcome, in a subsystem whose correct output is also quiet.
+     *
+     * @type {ProbeReverbRenderer|null}
+     */
+    #reverb = null;
+
     /**
      * @param {AcousticSimulator} simulator the shared simulation engine
+     * @param {ProbeReverbRenderer} [probeReverb] renderer to hand the field to alongside the
+     * simulator. {@link configureAcousticSimulation} passes the one it is given.
      */
-    constructor(simulator) {
+    constructor(simulator, probeReverb = null) {
         super();
 
         /**
          * @type {AcousticSimulator}
          */
         this.simulator = simulator;
+
+        this.#reverb = probeReverb;
     }
 
     /**
@@ -47,6 +65,10 @@ export class AcousticProbeFieldSystem extends System {
 
         this.#field = field;
         this.simulator.setProbeField(field);
+
+        if (this.#reverb !== null) {
+            this.#reverb.setProbeField(field);
+        }
     }
 
     /**
@@ -60,5 +82,9 @@ export class AcousticProbeFieldSystem extends System {
 
         this.#field = null;
         this.simulator.setProbeField(null);
+
+        if (this.#reverb !== null) {
+            this.#reverb.setProbeField(null);
+        }
     }
 }

package/src/engine/sound/simulation/render/ProbeReverbRenderer.d.ts

@@ -38,6 +38,40 @@ export class ProbeReverbRenderer {
      * @type {number}
      */
     minDecay: number;
+    set sendLevel(arg: number);
+    /**
+     * How much of the send actually comes back, 0..1.
+     *
+     * There was no level anywhere in this path. The internal wet gains crossfade between silence
+     * and **unity**, so connecting a bus output to {@link input} the way this class documents put
+     * the whole mix through the convolver at full wet — and every tunable that existed
+     * (`decayPower`, `crossfadeSeconds`, `changeThreshold`, `minDecay`) shapes the IR or the
+     * transition, not the amount. The honest wiring was the wrong-sounding one, which is a bad
+     * default to hand somebody. Reported from a port as GAP-032, worked around with a `GainNode`
+     * in front of the input.
+     *
+     * Multiplies the active wet gain, so it takes effect on the next crossfade and is applied
+     * immediately to a live one.
+     *
+     * @type {number}
+     */
+    get sendLevel(): number;
+    /**
+     * Longest impulse response this will synthesise, in seconds.
+     *
+     * `reverbImpulseResponse` sized its buffer straight from the RT60 with no ceiling. A probe
+     * measuring 8.06 s — not a bug: that is Sabine for a large hall behind hard surfaces — yields a
+     * 387,000-sample stereo `AudioBuffer` plus three scratch bands the same length, about 11 MB,
+     * synthesised **on the main thread**, every time the listener crosses into a probe cell whose
+     * decay differs by more than {@link changeThreshold}. That is a mid-match hitch triggered by
+     * walking, and it is a long way from its cause. GAP-032.
+     *
+     * Three seconds is what a `ConvolverNode` is comfortable running and is what the port clamped
+     * to when it hit this. Raise it if you have measured that you can afford to.
+     *
+     * @type {number}
+     */
+    maxDecaySeconds: number;
     /**
      * The node sources / a sopra bus send their post-fader copy into.
      * @returns {AudioNode}

package/src/engine/sound/simulation/render/ProbeReverbRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProbeReverbRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/ProbeReverbRenderer.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH;IAsFI;;;OAGG;IACH,0BAHW,gBAAgB,eAChB,SAAS,EA8BnB;IArHD;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,UAFU,MAAM,CAEA;IAgGhB;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,oDAEC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,KACN,MAAM,QAShB;IAED;;;OAGG;IACH,uBAFW,MAAM,QAOhB;IAED;;;;OAIG;IACH,gBAFW,YAAY,GAAC,MAAM,EAAE,QAwC/B;;CACJ"}
+{"version":3,"file":"ProbeReverbRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/ProbeReverbRenderer.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH;IAwII;;;OAGG;IACH,0BAHW,gBAAgB,eAChB,SAAS,EA8BnB;IAvKD;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,UAFU,MAAM,CAEA;IAsBhB,2BAQC;IA5BD;;;;;;;;;;;;;;;OAeG;IACH,wBAEC;IAeD;;;;;;;;;;;;;;OAcG;IACH,iBAFU,MAAM,CAEI;IAgGpB;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,oDAEC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,KACN,MAAM,QAShB;IAED;;;OAGG;IACH,uBAFW,MAAM,QAOhB;IAED;;;;OAIG;IACH,gBAFW,YAAY,GAAC,MAAM,EAAE,QAiD/B;;CACJ"}

package/src/engine/sound/simulation/render/ProbeReverbRenderer.js

@@ -41,6 +41,56 @@ export class ProbeReverbRenderer {
      */
     minDecay = 0.05;
 
+    /**
+     * How much of the send actually comes back, 0..1.
+     *
+     * There was no level anywhere in this path. The internal wet gains crossfade between silence
+     * and **unity**, so connecting a bus output to {@link input} the way this class documents put
+     * the whole mix through the convolver at full wet — and every tunable that existed
+     * (`decayPower`, `crossfadeSeconds`, `changeThreshold`, `minDecay`) shapes the IR or the
+     * transition, not the amount. The honest wiring was the wrong-sounding one, which is a bad
+     * default to hand somebody. Reported from a port as GAP-032, worked around with a `GainNode`
+     * in front of the input.
+     *
+     * Multiplies the active wet gain, so it takes effect on the next crossfade and is applied
+     * immediately to a live one.
+     *
+     * @type {number}
+     */
+    get sendLevel() {
+        return this.#sendLevel;
+    }
+
+    set sendLevel(value) {
+        this.#sendLevel = value;
+
+        // apply to whichever convolver is currently up, so a change is audible without waiting for
+        // the listener to cross a probe cell
+        if (this.#currentWet > 0) {
+            rampGain(this.#wets[this.#active].gain, Math.max(FADE_EPSILON, value), 0.02, this.#ctx);
+        }
+    }
+
+    /** @private @type {number} */
+    #sendLevel = 1;
+
+    /**
+     * Longest impulse response this will synthesise, in seconds.
+     *
+     * `reverbImpulseResponse` sized its buffer straight from the RT60 with no ceiling. A probe
+     * measuring 8.06 s — not a bug: that is Sabine for a large hall behind hard surfaces — yields a
+     * 387,000-sample stereo `AudioBuffer` plus three scratch bands the same length, about 11 MB,
+     * synthesised **on the main thread**, every time the listener crosses into a probe cell whose
+     * decay differs by more than {@link changeThreshold}. That is a mid-match hitch triggered by
+     * walking, and it is a long way from its cause. GAP-032.
+     *
+     * Three seconds is what a `ConvolverNode` is comfortable running and is what the port clamped
+     * to when it hit this. Raise it if you have measured that you can afford to.
+     *
+     * @type {number}
+     */
+    maxDecaySeconds = 3;
+
     /**
      * @type {BaseAudioContext}
      */
@@ -215,8 +265,17 @@ export class ProbeReverbRenderer {
         const inactive = 1 - this.#active;
 
         if (targetWet > 0) {
+            // clamped here rather than at the bake, so a field that ships a long RT60 still plays
+            // at a length the convolver can run and the allocation stays bounded
+            const ceiling = this.maxDecaySeconds;
+            const clamped = [
+                Math.min(bands[0], ceiling),
+                Math.min(bands[1], ceiling),
+                Math.min(bands[2], ceiling)
+            ];
+
             this.#convolvers[inactive].buffer = reverbImpulseResponse(
-                this.#ctx, bands, this.decayPower, this.#random
+                this.#ctx, clamped, this.decayPower, this.#random
             );
         }
 
@@ -224,7 +283,7 @@ export class ProbeReverbRenderer {
         // where available, so crossing a probe cell mid-fade doesn't snap). Fade to FADE_EPSILON, never 0.
         const cf = this.crossfadeSeconds;
         rampGain(this.#wets[this.#active].gain, FADE_EPSILON, cf, this.#ctx);
-        rampGain(this.#wets[inactive].gain, targetWet > 0 ? 1 : FADE_EPSILON, cf, this.#ctx);
+        rampGain(this.#wets[inactive].gain, targetWet > 0 ? Math.max(FADE_EPSILON, this.#sendLevel) : FADE_EPSILON, cf, this.#ctx);
 
         this.#active = inactive;
     }

package/src/engine/sound/simulation/render/reverbImpulseResponse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reverbImpulseResponse.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/reverbImpulseResponse.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;GAeG;AACH,2CANW,gBAAgB,cAChB,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,gBACK,MAAM,GACf,WAAW,CA2CvB"}
+{"version":3,"file":"reverbImpulseResponse.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/reverbImpulseResponse.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;GAeG;AACH,2CANW,gBAAgB,cAChB,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,gBACK,MAAM,GACf,WAAW,CAoDvB"}

package/src/engine/sound/simulation/render/reverbImpulseResponse.js

@@ -39,6 +39,15 @@ export function reverbImpulseResponse(
     const ir = ctx.createBuffer(2, length, sampleRate);
 
     // band scratch, allocated once and reused for BOTH channels (they differ only in their noise stream)
+    /*
+     Float64, and it stays that way. GAP-032 suggested halving this allocation with a Float32
+     scratch on the reasoning that the bands are summed into a float32 channel anyway. They are —
+     and `reverb_band_tails` documents why that does not follow: the callers SUM AND RE-WEIGHT
+     these values, rounding each band to float32 first perturbs the sum, and there are two callers
+     (this stereo IR and the B-format directional one). The whole point of sharing the band
+     production is that both renderers agree about what the same room sounds like. The allocation
+     is bounded by `ProbeReverbRenderer.maxDecaySeconds` instead, which was the real problem.
+    */
     const bandLow = new Float64Array(length);
     const bandMid = new Float64Array(length);
     const bandHigh = new Float64Array(length);