@woosh/meep-engine 3.46.0 → 3.47.0

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

@@ -5,6 +5,7 @@ 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";
+import { EffectParamOverrides } from "../../sopra/runtime/EffectParamOverrides.js";
 
 const DEFAULT_SOURCE_RADIUS = 0.05;
 
@@ -22,13 +23,14 @@ export class AudioEmitter {
     /**
      * The authored event this emitter plays.
      *
-     * Authored data: fixed for as long as the emitter is playing. Routing (`busId`, `is3D`,
-     * `panningModel`) decides the shape of the instance's audio graph, which is built once when the
-     * voice starts; and `distanceMin`, `distanceMax`, `maxInstances` and the attenuation curve all take
-     * part in {@link EventDescription.hash}, which the `VoiceManager` buckets live instances by — so
-     * editing any of them in place on a sounding emitter files that instance under a hash it can no
-     * longer be found by. Change them by re-linking the component (remove and re-add it), which tears
-     * the voice down and re-reads the description cleanly.
+     * Authored data: fixed for as long as the emitter is linked, playing or dormant. Routing (`busId`,
+     * `is3D`, `panningModel`) decides the shape of the instance's audio graph, which is built once when
+     * the voice starts; and `distanceMin`, `distanceMax`, `maxInstances`, the attenuation curve and the
+     * insert `effects` (every field of every effect) all take part in {@link EventDescription.hash}, which
+     * the `VoiceManager` buckets live instances by — so editing any of them in place on a sounding emitter
+     * files that instance under a hash it can no longer be found by. Change them by re-linking the
+     * component (remove and re-add it), which tears the voice down and re-reads the description cleanly.
+     * A playing effect's parameters move through {@link effectOverrides}, never through the definition.
      *
      * @type {EventDescription}
      */
@@ -71,6 +73,32 @@ export class AudioEmitter {
      */
     directivity = new AcousticDirectivity();
 
+    /**
+     * This emitter's own values for its event's insert-effect parameters ({@link EventDescription.effects}):
+     * a lowpass closing over one torch as a door shuts on it, while every other torch playing the same
+     * event stays bright.
+     *
+     * Live state, the way {@link volume} is live — plumbed by `AudioEmitterSystem` onto whichever instance
+     * is current, and put onto every new one. A spatially managed emitter's instance is torn down when it
+     * is demoted and built afresh when it is promoted again, and is built at these values, not the event's;
+     * a value moved straight on an instance (`AudioEmitterSystem.instanceFor(entity).setEffectParam`) lasts
+     * only as long as that instance.
+     *
+     * Not authored data, so absent from {@link toJSON}, {@link equals} and {@link hash}: two emitters that
+     * differ only in where a filter has been turned are the same emitter, and the overrides must change
+     * neither what a save contains nor which polyphony bucket a voice is filed under.
+     *
+     * Checked against the event: while the emitter is linked, an override its event has no such parameter
+     * for throws where it is written, and is not kept; one written before the link is checked by the link,
+     * which throws instead of playing. So {@link EffectParamOverrides#clear} them before re-adding the
+     * component with a different event. One entity per `AudioEmitter`: a second link of the same component
+     * throws, since the overrides can follow only one playing instance.
+     *
+     * @readonly
+     * @type {EffectParamOverrides}
+     */
+    effectOverrides = new EffectParamOverrides();
+
     /**
      * 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

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

@@ -1 +1 @@
-{"version":3,"file":"AudioEmitterSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSerializationAdapter.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH;;IACI,2BAAqB;IAarB;;;OAGG;IACH,mFAEC;IAED;;;OAGG;IACH,uCAFW,YAAY,QAWtB;IAED;;;OAGG;IACH,yCAFW,YAAY,QAWtB;;CACJ;gDAnE+C,gEAAgE;6BAGnF,mBAAmB"}
+{"version":3,"file":"AudioEmitterSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSerializationAdapter.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH;;IACI,2BAAqB;IAiBrB;;;OAGG;IACH,mFAEC;IAED;;;OAGG;IACH,uCAFW,YAAY,QAWtB;IAED;;;OAGG;IACH,yCAFW,YAAY,QAWtB;;CACJ;gDAvE+C,gEAAgE;6BAGnF,mBAAmB"}

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

@@ -16,7 +16,11 @@ import { AudioEmitter } from "./AudioEmitter.js";
  */
 export class AudioEmitterSerializationAdapter extends BinaryClassSerializationAdapter {
     klass = AudioEmitter;
-    version = 0;
+    /**
+     * 1: the embedded event record moved to its format 1 (insert effects) — `AudioEmitterSerializationUpgrader_0_1`.
+     * @type {number}
+     */
+    version = 1;
 
     /**
      * @type {EventDescriptionSerializationAdapter}

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

@@ -0,0 +1,18 @@
+/**
+ * @typedef {import("../../../ecs/storage/binary/BinarySerializationRegistry.js").BinarySerializationRegistry} BinarySerializationRegistry
+ */
+/**
+ * Version 0 → 1: the embedded {@link EventDescription} record moved to its own format 1 (insert effects).
+ * The record leads the component and carries no version tag of its own, so the component's version is what
+ * says which layout it is in; every field after it is unchanged.
+ */
+export class AudioEmitterSerializationUpgrader_0_1 extends BinaryClassUpgrader {
+    /**
+     * @param {BinarySerializationRegistry} registry where the event's clip types are registered
+     */
+    constructor(registry: BinarySerializationRegistry);
+    #private;
+}
+export type BinarySerializationRegistry = import("../../../ecs/storage/binary/BinarySerializationRegistry.js").BinarySerializationRegistry;
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=AudioEmitterSerializationUpgrader_0_1.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEmitterSerializationUpgrader_0_1.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSerializationUpgrader_0_1.js"],"names":[],"mappings":"AAMA;;GAEG;AAEH;;;;GAIG;AACH;IASI;;OAEG;IACH,sBAFW,2BAA2B,EAMrC;;CAgBJ;0CAxCY,OAAO,4DAA4D,EAAE,2BAA2B;oCANzE,oDAAoD"}

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

@@ -0,0 +1,48 @@
+import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+import {
+    EventDescriptionSerializationUpgrader_0_1
+} from "../../sopra/definition/EventDescriptionSerializationUpgrader_0_1.js";
+
+/**
+ * @typedef {import("../../../ecs/storage/binary/BinarySerializationRegistry.js").BinarySerializationRegistry} BinarySerializationRegistry
+ */
+
+/**
+ * Version 0 → 1: the embedded {@link EventDescription} record moved to its own format 1 (insert effects).
+ * The record leads the component and carries no version tag of its own, so the component's version is what
+ * says which layout it is in; every field after it is unchanged.
+ */
+export class AudioEmitterSerializationUpgrader_0_1 extends BinaryClassUpgrader {
+    __startVersion = 0;
+    __targetVersion = 1;
+
+    /**
+     * @type {EventDescriptionSerializationUpgrader_0_1}
+     */
+    #event;
+
+    /**
+     * @param {BinarySerializationRegistry} registry where the event's clip types are registered
+     */
+    constructor(registry) {
+        super();
+
+        this.#event = new EventDescriptionSerializationUpgrader_0_1(registry);
+    }
+
+    /**
+     * @param {BinaryBuffer} source
+     * @param {BinaryBuffer} target
+     */
+    upgrade(source, target) {
+        this.#event.upgrade(source, target);
+
+        BinaryBuffer.copyFloat32(source, target); // volume
+        BinaryBuffer.copyUint8(source, target); // autoplay
+        BinaryBuffer.copyUint8(source, target); // acoustic
+        BinaryBuffer.copyFloat32(source, target); // sourceRadius
+        BinaryBuffer.copyFloat32(source, target); // directivity.dipoleWeight
+        BinaryBuffer.copyFloat32(source, target); // directivity.dipolePower
+    }
+}

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

@@ -1,7 +1,8 @@
 /**
  * Drives {@link AudioEmitter} components through the shared sopra engine. Each emitter owns its
  * {@link EventDescription} directly (no track translation); the entity's {@link Transform64} feeds
- * position; `volume` changes plumb to the instance gain. Each frame it forwards the listener pose,
+ * position; `volume` changes plumb to the instance gain, and `effectOverrides` to the instance's effect
+ * parameters — both put onto every instance the emitter gets. 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 —
@@ -50,7 +51,7 @@ export class AudioEmitterSystem extends System<any> {
      */
     acousticLive: EventInstance[];
     /**
-     * Per-entity records: { emitter, transform, managed, instance, onVolume }. For a managed (3D)
+     * Per-entity records: { emitter, transform, managed, instance, onVolume, effectOverrides, onEffectOverride, ... }. 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[]}
@@ -112,6 +113,15 @@ export class AudioEmitterSystem extends System<any> {
      * @returns {EventInstance|null}
      */
     instanceFor(entity: number): EventInstance | null;
+    /**
+     * @param {EntityComponentDataset} dataset
+     */
+    handleDatasetDetached(dataset: EntityComponentDataset): void;
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    shutdown(entityManager: EntityManager): Promise<void>;
     update(timeDelta: any): void;
     #private;
 }

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":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;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,2DAA2C;IAE3C;;;;;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,WAAW,UACX,MAAM,QA4ChB;IAED;;;;OAIG;IACH,gBAJW,YAAY,aACZ,WAAW,UACX,MAAM,QA+BhB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,gBAAc,IAAI,CAe9B;IAqDD,6BAoFC;;CACJ;uBAvXsB,wBAAwB;4BAGnB,uCAAuC;6BAKtC,mBAAmB;+BACjB,qBAAqB"}
+{"version":3,"file":"AudioEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSystem.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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,2DAA2C;IAE3C;;;;;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,WAAW,UACX,MAAM,QAyEhB;IAED;;;;OAIG;IACH,gBAJW,YAAY,aACZ,WAAW,UACX,MAAM,QAkChB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,gBAAc,IAAI,CAe9B;IAoJD;;OAEG;IACH,6DAKC;IAED;;;OAGG;IACH,wCAFa,QAAQ,IAAI,CAAC,CAKzB;IAmBD,6BAoFC;;CACJ;uBA3hBsB,wBAAwB;4BAGnB,uCAAuC;6BAKtC,mBAAmB;+BACjB,qBAAqB"}

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

@@ -25,7 +25,8 @@ const LISTENER_ROTATION = new Quaternion();
 /**
  * Drives {@link AudioEmitter} components through the shared sopra engine. Each emitter owns its
  * {@link EventDescription} directly (no track translation); the entity's {@link Transform64} feeds
- * position; `volume` changes plumb to the instance gain. Each frame it forwards the listener pose,
+ * position; `volume` changes plumb to the instance gain, and `effectOverrides` to the instance's effect
+ * parameters — both put onto every instance the emitter gets. 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 —
@@ -66,7 +67,7 @@ export class AudioEmitterSystem extends System {
     acousticLive = [];
 
     /**
-     * Per-entity records: { emitter, transform, managed, instance, onVolume }. For a managed (3D)
+     * Per-entity records: { emitter, transform, managed, instance, onVolume, effectOverrides, onEffectOverride, ... }. 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[]}
@@ -144,11 +145,25 @@ export class AudioEmitterSystem extends System {
         // class doc.
         const managed = emitter.autoplay && emitter.event.is3D && emitter.event.rootClip.loops();
 
-        const record = { emitter, transform, managed, instance: null, onVolume: null, onEnded: null, onMoved: null };
+        const record = {
+            emitter, transform, managed, instance: null, onVolume: null, onEnded: null, onMoved: null,
+            // held here, so unlink detaches what link attached even if the field was replaced since
+            effectOverrides: emitter.effectOverrides,
+            onEffectOverride: null
+        };
+
+        // Effect overrides move whichever instance is current, on either route. Checked first: an override
+        // written before the link that the event has no parameter for throws HERE, before anything is
+        // registered or played. They are attached - and every later write checked as it is written - once
+        // the record is stored, below, when nothing left in the link can fail and leave them attached to a
+        // record that never was.
+        record.effectOverrides.checkAttach(emitter.event);
+        record.onEffectOverride = (effectIndex, name, value, timeConstant) => this.#moveEffectParam(record, entity, effectIndex, name, value, timeConstant);
 
         if (managed) {
             const pathing = emitter.acoustic && this.acousticSim !== null && this.acousticSim.pathing;
-            this.liveSet.add(entity, emitter.event, transform.translation, volume2dB(emitter.volume.getValue()), emitter.acoustic, pathing, emitter.sourceRadius, transform.rotation, emitter.directivity);
+            // the live set puts the overrides onto every instance it promotes
+            this.liveSet.add(entity, emitter.event, transform.translation, volume2dB(emitter.volume.getValue()), emitter.acoustic, pathing, emitter.sourceRadius, transform.rotation, emitter.directivity, record.effectOverrides);
             record.onVolume = () => this.liveSet.setGainDb(entity, volume2dB(emitter.volume.getValue()));
 
             // The live set reads the translation through a live view, but a Transform64 cannot say it
@@ -166,12 +181,27 @@ export class AudioEmitterSystem extends System {
                 }
             }
             record.onVolume = () => this.#applyVolume(record);
+
+            if (record.instance !== null && emitter.event.is3D) {
+                // The instance holds the translation's live view, and reads it only when told it moved -
+                // the announcement is how it is told, as it is for the live set below
+                record.onMoved = () => record.instance?.moved();
+
+                this.entityManager.dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, record.onMoved);
+            }
         }
 
         emitter.volume.onChanged.add(record.onVolume);
 
         this.data[entity] = record;
 
+        record.effectOverrides.attach(emitter.event, record.onEffectOverride);
+
+        // a direct instance was built above, at the event's definition
+        if (record.instance !== null && record.instance.state !== EventInstanceState.Stopped) {
+            record.effectOverrides.applyTo(record.instance);
+        }
+
         // A one-shot whose buffers are already decoded resolves its timeline inside playEvent and can
         // finish there and then — before the subscription in #play exists, and while the record is still
         // unreachable. Report that end here instead, once the link is complete, so an `on.ended` handler
@@ -197,10 +227,13 @@ export class AudioEmitterSystem extends System {
         delete this.data[entity];
 
         emitter.volume.onChanged.remove(record.onVolume);
+        record.effectOverrides.detach(record.onEffectOverride);
 
-        if (record.managed) {
+        if (record.onMoved !== null) {
             this.entityManager.dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, record.onMoved);
+        }
 
+        if (record.managed) {
             this.liveSet.remove(entity); // demotes (hard cut) if live, then unregisters
         } else if (record.instance !== null) {
             this.directInstances.delete(record.instance);
@@ -255,7 +288,7 @@ export class AudioEmitterSystem extends System {
 
         const instance = this.sopra.playEvent(event, {
             busId: event.busId,
-            // a live view over the transform's buffer, so it still tracks the entity as it moves
+            // a live view over the transform's buffer, read again each time the entity announces a move
             position: transform.translation,
             oneShot,
             acoustic: emitter.acoustic,
@@ -290,6 +323,137 @@ export class AudioEmitterSystem extends System {
         }
     }
 
+    /**
+     * Carry one change of an emitter's {@link AudioEmitter.effectOverrides} to its current instance. With
+     * none — dormant, or a one-shot that has ended — there is nothing to move: the next instance is built
+     * at the overrides as they then stand. A contention fade is not current; like the gain, it finishes
+     * as it was.
+     * @param {object} record the emitter's link record
+     * @param {number} entity
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value
+     * @param {number} timeConstant 0 moves it now; above 0 glides
+     */
+    #moveEffectParam(record, entity, effectIndex, name, value, timeConstant) {
+        // entity ids are reused: a record that is no longer the entity's must not move whoever has it now
+        if (this.data[entity] !== record) {
+            return;
+        }
+
+        const instance = this.instanceFor(entity);
+
+        if (instance === null || instance.state === EventInstanceState.Stopped) {
+            return;
+        }
+
+        if (timeConstant > 0) {
+            instance.approachEffectParam(effectIndex, name, value, timeConstant);
+        } else {
+            instance.setEffectParam(effectIndex, name, value);
+        }
+    }
+
+    /**
+     * The listener this system follows: its dataset, entity and transform, and the transform's
+     * translation view handed to sopra, taken once rather than read off the transform each frame (that
+     * getter builds a new view on every read). Null until a listener is seen.
+     * @type {EntityComponentDataset|null}
+     */
+    #listener_ecd = null;
+
+    /** @type {number} */
+    #listener_entity = -1;
+
+    /** @type {Transform64|null} */
+    #listener_transform = null;
+
+    /** @type {Float64Array|null} */
+    #listener_position = null;
+
+    /**
+     * Tells sopra the listener moved, when its transform announces a write: every 3D instance re-attenuates
+     * on the next tick, and none does between moves.
+     */
+    #on_listener_moved = () => {
+        this.sopra.setListener(this.#listener_position);
+    };
+
+    /**
+     * The followed listener's entity was removed, and its listeners with it. Forget it, so the next
+     * update follows whatever listener there is then — the same entity rebuilt from the same components
+     * included, which comes back with the same id and transform and would otherwise look followed already.
+     * sopra keeps the last listener position until then, as it does with no listener at all.
+     */
+    #on_listener_removed = () => {
+        this.#listener_ecd = null;
+        this.#listener_entity = -1;
+        this.#listener_transform = null;
+    };
+
+    /**
+     * Follow `entity` as the listener, if it is not the one followed already: subscribe to its transform's
+     * announcements and hand sopra its position, which is itself a move.
+     *
+     * @param {EntityComponentDataset} ecd
+     * @param {number} entity
+     * @param {Transform64} transform
+     */
+    #follow_listener(ecd, entity, transform) {
+        // the transform too: an entity id is reused, and a dataset can be swapped
+        if (ecd === this.#listener_ecd && entity === this.#listener_entity && transform === this.#listener_transform) {
+            return;
+        }
+
+        this.#unfollow_listener();
+
+        this.#listener_ecd = ecd;
+        this.#listener_entity = entity;
+        this.#listener_transform = transform;
+        this.#listener_position = transform.translation;
+
+        ecd.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, this.#on_listener_moved);
+        ecd.addEntityEventListener(entity, EventType.EntityRemoved, this.#on_listener_removed);
+
+        this.sopra.setListener(this.#listener_position);
+    }
+
+    /**
+     * @param {EntityComponentDataset} dataset
+     */
+    handleDatasetDetached(dataset) {
+        // the listener followed lives in that dataset: leave nothing subscribed there
+        if (dataset === this.#listener_ecd) {
+            this.#unfollow_listener();
+        }
+    }
+
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async shutdown(entityManager) {
+        // a removed system keeps no listener subscription, nor through it itself alive
+        this.#unfollow_listener();
+    }
+
+    /**
+     * Stop following the listener followed now, if any.
+     */
+    #unfollow_listener() {
+        const ecd = this.#listener_ecd;
+
+        if (ecd === null) {
+            return;
+        }
+
+        // false, harmlessly, when that entity is gone: its listeners went with it
+        ecd.removeEntityEventListener(this.#listener_entity, TRANSFORM64_EVENT_CHANGE, this.#on_listener_moved);
+        ecd.removeEntityEventListener(this.#listener_entity, EventType.EntityRemoved, this.#on_listener_removed);
+
+        this.#on_listener_removed();
+    }
+
     update(timeDelta) {
         const sopra = this.sopra;
 
@@ -309,18 +473,18 @@ export class AudioEmitterSystem extends System {
                 const listenerTransform = ecd.getComponent(soundListener.entity, Transform64);
 
                 if (listenerTransform !== undefined) {
+                    this.#follow_listener(ecd, soundListener.entity, listenerTransform);
+
                     /*
                      The position stays the transform's own view: it is a live one, so a listener that
                      walks needs no second write, and every consumer of it below indexes the three
                      numbers rather than reading `.x`. The reverb is the exception, and reads them
                      off the transform by component where it is called.
                     */
-                    listenerPosition = listenerTransform.translation;
+                    listenerPosition = this.#listener_position;
 
                     // the rotation, by contrast, is handed to a renderer that steers by `q.x`
                     listenerRotation = t64_read_rotation(LISTENER_ROTATION, listenerTransform);
-
-                    sopra.setListener(listenerPosition);
                 }
             }
         }

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

@@ -65,14 +65,19 @@ export class LiveEmitterSet {
      * @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)
+     * @param {EffectParamOverrides|null} [effectOverrides] the emitter's own effect parameters, held by
+     *        reference and put onto every promoted instance (null = none). Moving the live instance as they
+     *        change is the owner's business: they reach it through {@link instanceOf}.
      */
-    add(entity: number, event: EventDescription, position: Float64Array, gainDb?: number, acoustic?: boolean, pathing?: boolean, sourceRadius?: number, orientation?: Quaternion | null, directivity?: AcousticDirectivity | null): void;
+    add(entity: number, event: EventDescription, position: Float64Array, gainDb?: number, acoustic?: boolean, pathing?: boolean, sourceRadius?: number, orientation?: Quaternion | null, directivity?: AcousticDirectivity | null, effectOverrides?: EffectParamOverrides | null): void;
     /**
-     * Report that a registered emitter moved, so the broadphase refits it. No-op for an unknown entity.
+     * Report that a registered emitter moved, so the broadphase refits it and its instance, if it is
+     * sounding, puts itself where it now is. No-op for an unknown entity.
      *
      * The position is a live view, so whatever reads it reads the current value - what the set cannot
      * do is notice that it was written. {@link refresh} considers only what this reported, which is
-     * what keeps a dormant emitter free: nothing visits it until it moves.
+     * what keeps a dormant emitter free: nothing visits it until it moves. The instance is the same: it
+     * reads the view only when told ({@link EventInstance#moved}), a fading one included.
      * @param {number} entity
      */
     moved(entity: number): void;
@@ -107,4 +112,5 @@ export class LiveEmitterSet {
     refresh(listenerPosition: number[] | Float64Array): void;
     #private;
 }
+export type EffectParamOverrides = import("../../sopra/runtime/EffectParamOverrides.js").EffectParamOverrides;
 //# sourceMappingURL=LiveEmitterSet.d.ts.map

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":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IA2EI;;;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,qCAEN,YAAY,WACZ,MAAM,aACN,OAAO,YACP,OAAO,iBACP,MAAM,gBACN,aAAW,IAAI,gBACf,sBAAoB,IAAI,QAOlC;IAED;;;;;;;OAOG;IACH,cAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,+CAFmC,IAAI,QAMtC;IAED;;;;;;;OAOG;IACH,kBAHW,MAAM,UACN,MAAM,QAehB;IAED;;;OAGG;IACH,eAFW,MAAM,QAwBhB;IAED;;;;;;;OAOG;IACH,0BAFW,MAAM,EAAE,GAAC,YAAY,QA+D/B;;CAgFJ"}
+{"version":3,"file":"LiveEmitterSet.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/LiveEmitterSet.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IA4EI;;;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;;;;;;;;;;;;;;OAcG;IACH,YAbW,MAAM,qCAEN,YAAY,WACZ,MAAM,aACN,OAAO,YACP,OAAO,iBACP,MAAM,gBACN,aAAW,IAAI,gBACf,sBAAoB,IAAI,oBACxB,oBAAoB,GAAC,IAAI,QASnC;IAED;;;;;;;;;OASG;IACH,cAFW,MAAM,QAOhB;IAED;;;;OAIG;IACH,+CAFmC,IAAI,QAMtC;IAED;;;;;;;OAOG;IACH,kBAHW,MAAM,UACN,MAAM,QAehB;IAED;;;OAGG;IACH,eAFW,MAAM,QAwBhB;IAED;;;;;;;OAOG;IACH,0BAFW,MAAM,EAAE,GAAC,YAAY,QA+D/B;;CAuFJ;mCA/ZY,OAAO,6CAA6C,EAAE,oBAAoB"}

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

@@ -2,6 +2,10 @@ import { EventInstanceState } from "../../sopra/runtime/EventInstance.js";
 import { SpatialAudioIndex } from "./SpatialAudioIndex.js";
 import { v3_distance } from "../../../../core/geom/vec3/v3_distance.js";
 
+/**
+ * @typedef {import("../../sopra/runtime/EffectParamOverrides.js").EffectParamOverrides} EffectParamOverrides
+ */
+
 /**
  * Sort rank entries nearest-first by effective (stickiness-discounted) distance.
  * @param {{effective:number}} a
@@ -72,10 +76,11 @@ export class LiveEmitterSet {
     #fadeOutSeconds;
 
     /**
-     * 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: Float64Array, gainDb: number, playingSince: number, acoustic: boolean, pathing: boolean, sourceRadius: number, orientation: Quaternion|null, directivity: AcousticDirectivity|null}>}
+     * entity -> { event, position, gainDb, playingSince, effectOverrides, ... }. `gainDb` is the per-emitter
+     * instance gain (e.g. the owning `AudioEmitter.volume` in dB) and `effectOverrides` the emitter's own
+     * effect parameters, both re-applied on every promotion so they survive a demote→re-promote cycle;
+     * `playingSince` carries the continuous-clock phase (see {@link add}).
+     * @type {Map<number, {event: EventDescription, position: Float64Array, gainDb: number, playingSince: number, acoustic: boolean, pathing: boolean, sourceRadius: number, orientation: Quaternion|null, directivity: AcousticDirectivity|null, effectOverrides: EffectParamOverrides|null}>}
      */
     #emitters = new Map();
 
@@ -167,24 +172,32 @@ export class LiveEmitterSet {
      * @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)
+     * @param {EffectParamOverrides|null} [effectOverrides] the emitter's own effect parameters, held by
+     *        reference and put onto every promoted instance (null = none). Moving the live instance as they
+     *        change is the owner's business: they reach it through {@link instanceOf}.
      */
-    add(entity, event, position, gainDb = 0, acoustic = false, pathing = false, sourceRadius = 0.5, orientation = null, directivity = null) {
+    add(entity, event, position, gainDb = 0, acoustic = false, pathing = false, sourceRadius = 0.5, orientation = null, directivity = null, effectOverrides = 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, acoustic, pathing, sourceRadius, orientation, directivity });
+        this.#emitters.set(entity, { event, position, gainDb, playingSince: this.#sopra.currentTime, acoustic, pathing, sourceRadius, orientation, directivity, effectOverrides });
     }
 
     /**
-     * Report that a registered emitter moved, so the broadphase refits it. No-op for an unknown entity.
+     * Report that a registered emitter moved, so the broadphase refits it and its instance, if it is
+     * sounding, puts itself where it now is. No-op for an unknown entity.
      *
      * The position is a live view, so whatever reads it reads the current value - what the set cannot
      * do is notice that it was written. {@link refresh} considers only what this reported, which is
-     * what keeps a dormant emitter free: nothing visits it until it moves.
+     * what keeps a dormant emitter free: nothing visits it until it moves. The instance is the same: it
+     * reads the view only when told ({@link EventInstance#moved}), a fading one included.
      * @param {number} entity
      */
     moved(entity) {
         this.#index.refresh(entity);
+
+        this.#live.get(entity)?.moved();
+        this.#fading.get(entity)?.moved();
     }
 
     /**
@@ -370,6 +383,13 @@ export class LiveEmitterSet {
                 this.#fading.delete(entity);
             }
         });
+
+        // and the emitter's effect parameters, the way the gain is replayed: the fresh instance was built at
+        // the event's definition. Last, once the instance is tracked: an override the event cannot take
+        // throws, and must not leave a sounding instance nobody will ever stop.
+        if (record.effectOverrides !== null) {
+            record.effectOverrides.applyTo(instance);
+        }
     }
 
     /**

package/src/engine/sound/ecs/trigger/AudioEventTrigger.d.ts

@@ -67,6 +67,10 @@ export class AudioEventTriggerRule {
             priority: number;
             stealMode: number;
             virtualThresholdDb: number;
+            effects: {
+                type: string;
+                data: any;
+            }[];
         };
     };
     fromJSON(json: any): void;
@@ -131,6 +135,10 @@ export class AudioEventTrigger {
                 priority: number;
                 stealMode: number;
                 virtualThresholdDb: number;
+                effects: {
+                    type: string;
+                    data: any;
+                }[];
             };
         }[];
     };

package/src/engine/sound/ecs/trigger/AudioEventTrigger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AudioEventTrigger.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/trigger/AudioEventTrigger.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH;IAuBI;;;;;OAKG;IACH,wBALW,MAAM,SACN,gBAAgB,cAChB,MAAM,GAAC,IAAI,GACT,qBAAqB,CAUjC;IAuCD;;;OAGG;IACH,4BAFa,qBAAqB,CAMjC;IAlFD;;;;OAIG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,WAFU,MAAM,GAAC,IAAI,CAEJ;IAEjB;;;;OAIG;IACH,OAFU,gBAAgB,CAEK;IAkB/B;;;OAGG;IACH,cAHW,qBAAqB,GACnB,OAAO,CAMnB;IAED,eAMC;IAED;;;;;;;;;;;;;;;;;;;;;;;MAMC;IAED,0BASC;CAWJ;AAED;;;;;;;;GAQG;AACH;IAcI;;;OAGG;IACH,mBAHW,qBAAqB,EAAE,GACrB,iBAAiB,CAQ7B;IA6CD;;;OAGG;IACH,4BAFa,iBAAiB,CAM7B;IA3ED;;;;;;;;;OASG;IACH,OAFU,qBAAqB,EAAE,CAEtB;IAcX;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAiBnB;IAED,eAUC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;MAIC;IAED,0BAEC;CAWJ;;;;iCA1LgC,4CAA4C"}
+{"version":3,"file":"AudioEventTrigger.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/trigger/AudioEventTrigger.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH;IAuBI;;;;;OAKG;IACH,wBALW,MAAM,SACN,gBAAgB,cAChB,MAAM,GAAC,IAAI,GACT,qBAAqB,CAUjC;IAuCD;;;OAGG;IACH,4BAFa,qBAAqB,CAMjC;IAlFD;;;;OAIG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,WAFU,MAAM,GAAC,IAAI,CAEJ;IAEjB;;;;OAIG;IACH,OAFU,gBAAgB,CAEK;IAkB/B;;;OAGG;IACH,cAHW,qBAAqB,GACnB,OAAO,CAMnB;IAED,eAMC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;MAMC;IAED,0BASC;CAWJ;AAED;;;;;;;;GAQG;AACH;IAcI;;;OAGG;IACH,mBAHW,qBAAqB,EAAE,GACrB,iBAAiB,CAQ7B;IA6CD;;;OAGG;IACH,4BAFa,iBAAiB,CAM7B;IA3ED;;;;;;;;;OASG;IACH,OAFU,qBAAqB,EAAE,CAEtB;IAcX;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAiBnB;IAED,eAUC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAIC;IAED,0BAEC;CAWJ;;;;iCA1LgC,4CAA4C"}

package/src/engine/sound/ecs/trigger/AudioEventTriggerSerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AudioEventTriggerSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/trigger/AudioEventTriggerSerializationAdapter.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH;;IACI,gCAA0B;IAQ1B;;;OAGG;IACH,mFAEC;IAED;;;OAGG;IACH,uCAFW,iBAAiB,QAuB3B;IAED;;;OAGG;IACH,yCAFW,iBAAiB,QAmB3B;;CACJ;gDAhF+C,gEAAgE;kCAEvD,wBAAwB"}
+{"version":3,"file":"AudioEventTriggerSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/trigger/AudioEventTriggerSerializationAdapter.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH;;IACI,gCAA0B;IAY1B;;;OAGG;IACH,mFAEC;IAED;;;OAGG;IACH,uCAFW,iBAAiB,QAuB3B;IAED;;;OAGG;IACH,yCAFW,iBAAiB,QAmB3B;;CACJ;gDApF+C,gEAAgE;kCAEvD,wBAAwB"}

package/src/engine/sound/ecs/trigger/AudioEventTriggerSerializationAdapter.js

@@ -14,7 +14,11 @@ import { AudioEventTrigger, AudioEventTriggerRule } from "./AudioEventTrigger.js
  */
 export class AudioEventTriggerSerializationAdapter extends BinaryClassSerializationAdapter {
     klass = AudioEventTrigger;
-    version = 0;
+    /**
+     * 1: the embedded event record moved to its format 1 (insert effects) — `AudioEventTriggerSerializationUpgrader_0_1`.
+     * @type {number}
+     */
+    version = 1;
 
     /**
      * @type {EventDescriptionSerializationAdapter}

package/src/engine/sound/ecs/trigger/AudioEventTriggerSerializationUpgrader_0_1.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @typedef {import("../../../ecs/storage/binary/BinarySerializationRegistry.js").BinarySerializationRegistry} BinarySerializationRegistry
+ */
+/**
+ * Version 0 → 1: each rule's embedded {@link EventDescription} record moved to its own format 1 (insert
+ * effects). The record carries no version tag of its own, so the component's version is what says which
+ * layout it is in; the rule's other fields are unchanged.
+ */
+export class AudioEventTriggerSerializationUpgrader_0_1 extends BinaryClassUpgrader {
+    /**
+     * @param {BinarySerializationRegistry} registry where the events' clip types are registered
+     */
+    constructor(registry: BinarySerializationRegistry);
+    #private;
+}
+export type BinarySerializationRegistry = import("../../../ecs/storage/binary/BinarySerializationRegistry.js").BinarySerializationRegistry;
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+//# sourceMappingURL=AudioEventTriggerSerializationUpgrader_0_1.d.ts.map

package/src/engine/sound/ecs/trigger/AudioEventTriggerSerializationUpgrader_0_1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEventTriggerSerializationUpgrader_0_1.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/trigger/AudioEventTriggerSerializationUpgrader_0_1.js"],"names":[],"mappings":"AAMA;;GAEG;AAEH;;;;GAIG;AACH;IASI;;OAEG;IACH,sBAFW,2BAA2B,EAMrC;;CAmBJ;0CA3CY,OAAO,4DAA4D,EAAE,2BAA2B;oCANzE,oDAAoD"}