@woosh/meep-engine 3.46.0 → 3.49.0

package/src/engine/sound/sopra/SopraEngine.d.ts

@@ -45,11 +45,12 @@ export class SopraEngine {
      */
     voiceManager: VoiceManager;
     /**
-     * Listener world position for spatialization/attenuation. Null = no listener set yet (events play
-     * unattenuated). In P3 this is driven from the ECS SoundListener.
-     * @type {Vector3|null}
+     * Listener world position for spatialization/attenuation, read by index. Null = no listener set yet
+     * (events play unattenuated). Set it with {@link setListener}, which is also how a move is reported;
+     * the ECS `AudioEmitterSystem` drives it from the `SoundListener` entity's transform.
+     * @type {ArrayLike<number>|null}
      */
-    listenerPosition: Vector3 | null;
+    listenerPosition: ArrayLike<number> | null;
     /**
      * @type {BaseAudioContext}
      */
@@ -88,9 +89,22 @@ export class SopraEngine {
      * feeding the old graph, so anything already playing is silenced by the swap rather than
      * re-routed. Swap between scenes, or stop what is playing first.
      *
+     * Every bus is built at its DEFINED gain, so by default a fader moved since — a player's volume
+     * setting, a bound parameter, a snapshot — is reset by the swap. That is right when the new tree IS
+     * the new mix (loading a scene's authored mix). When the tree changes but the mix should not —
+     * adding a bus to the tree the player has been adjusting — pass `keepVolumes`: each bus present in
+     * both trees keeps its fader where it was, moved the way {@link setBusVolume} moves it (an engaged
+     * duck on it carries over too), and buses new to the tree start at their defined gain. Only the
+     * faders carry: insert-effect parameters start from the new definitions, which may describe
+     * different effects — except one a {@link bindParameterToBusEffectParam} binding holds, which the new
+     * tree is built at the bound value of, with `keepVolumes` or without.
+     *
      * @param {BusDefinition[]} busDefinitions
+     * @param {{keepVolumes?: boolean}} [options]
      */
-    setBuses(busDefinitions: BusDefinition[]): void;
+    setBuses(busDefinitions: BusDefinition[], { keepVolumes }?: {
+        keepVolumes?: boolean;
+    }): void;
     /**
      * Create (but do not start) an instance of an event.
      * @param {EventDescription} description
@@ -159,10 +173,18 @@ export class SopraEngine {
      */
     getParameter(name: string): number | undefined;
     /**
-     * Set the listener world position used for 3D attenuation/culling.
-     * @param {Vector3} position
+     * Set the listener world position used for 3D attenuation/culling, and report that it moved: every 3D
+     * instance re-attenuates against it on the next {@link update}, and none does again until the next
+     * call. Held by reference, so after writing into the same array, call this again with it.
+     * @param {ArrayLike<number>|null} position read by index
+     */
+    setListener(position: ArrayLike<number> | null): void;
+    /**
+     * Advanced by each {@link setListener}: what a 3D instance compares to tell whether the listener has
+     * moved since it last attenuated.
+     * @returns {number}
      */
-    setListener(position: Vector3): void;
+    get listenerVersion(): number;
     /**
      * Register a parameter with a default value.
      * @param {string} name
@@ -182,6 +204,42 @@ export class SopraEngine {
      * @param {AnimationCurve} curve maps parameter value -> linear bus gain
      */
     bindParameterToBusVolume(name: string, busId: string, curve: AnimationCurve): void;
+    /**
+     * Drive a parameter of one of a bus's insert effects from a sopra parameter through an
+     * {@link AnimationCurve} — the effect's counterpart of {@link bindParameterToBusVolume}. A game sets
+     * one value (`health`); how far the world's lowpass closes for it is authored in the curve, not
+     * worked out in game code.
+     *
+     * Addressed as {@link setBusEffectParam}, and checked against the tree as it stands: a bus, effect or
+     * parameter it does not have throws here, where the binding was written. The parameter's value takes
+     * hold at once, without a glide: now if it has one, else when it first gets one.
+     *
+     * From then on the binding is a standing rule:
+     * - each change of the parameter moves the effect — now, or with a `timeConstant` above 0 as a glide
+     *   ({@link approachBusEffectParam}), so a value set every frame is tracked smoothly;
+     * - every tree {@link setBuses} builds that has the target starts at the bound value, not at the
+     *   definition it was rebuilt from;
+     * - over a tree without the target it does nothing, and holds again over the next tree that has it.
+     *   (A binding cannot be removed, so it has to outlive a tree swap; a mistyped address is caught at
+     *   the bind.)
+     *
+     * One binding per parameter and target: binding the same pair again replaces its curve and time
+     * constant, and moves the effect to the new curve as a change would — it adds nothing, so binding again
+     * after a {@link setBuses} that keeps the target is harmless. Two parameters bound to one target
+     * take turns — the last to change wins, and after a rebuild the later binding (a re-bind keeps its
+     * place). A direct {@link setBusEffectParam} on a bound effect holds until the parameter next changes.
+     *
+     * The address is positional, like every effect address: reorder a bus's `effects` and the binding
+     * follows whatever now sits at its index.
+     *
+     * @param {string} name sopra parameter, as {@link setParameter} sets it
+     * @param {string} busId
+     * @param {number} effectIndex position in the bus definition's `effects`
+     * @param {string} paramName one of that effect class's `parameters` (`'frequency'` on an `EqEffect`)
+     * @param {AnimationCurve} curve maps the parameter's value to the effect parameter's, in its own units
+     * @param {number} [timeConstant=0] seconds: 0 moves the effect now on each change; above 0 glides
+     */
+    bindParameterToBusEffectParam(name: string, busId: string, effectIndex: number, paramName: string, curve: AnimationCurve, timeConstant?: number): void;
     /**
      * @param {string} busId
      * @returns {number} linear gain
@@ -192,6 +250,44 @@ export class SopraEngine {
      * @param {number} linear linear gain
      */
     setBusVolume(busId: string, linear: number): void;
+    /**
+     * Move a parameter of one of a bus's insert effects ({@link BusDefinition.effects}), now.
+     *
+     * The effect is addressed by its position in the bus definition's `effects`, the parameter by one of
+     * its class's `parameters` — the name of the definition field it starts from (`'frequency'` on an
+     * `EqEffect`). It moves the bus's built copy only; the definition is never touched, and
+     * {@link setBuses} rebuilds from it. Whatever automation was in flight on the parameter is cancelled.
+     *
+     * @param {string} busId
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value in the parameter's own units (Hz, dB, seconds, ...)
+     */
+    setBusEffectParam(busId: string, effectIndex: number, name: string, value: number): void;
+    /**
+     * Glide a parameter of one of a bus's insert effects toward `value` — a lowpass closing over the
+     * world as health runs out, a compressor's threshold riding a game state. Exponential, covering ~63%
+     * of the way per `timeConstant`, like the fader's ducking glide. Whatever was in flight is cancelled
+     * and held first, so a value sent every frame retargets from wherever the last glide had got to.
+     *
+     * Addressed as {@link setBusEffectParam}.
+     *
+     * @param {string} busId
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value
+     * @param {number} timeConstant seconds, above 0
+     */
+    approachBusEffectParam(busId: string, effectIndex: number, name: string, value: number, timeConstant: number): void;
+    /**
+     * Where a bus effect's parameter was last sent (the target of a glide still in flight), or its
+     * defined value if it has not been moved.
+     * @param {string} busId
+     * @param {number} effectIndex
+     * @param {string} name
+     * @returns {number}
+     */
+    getBusEffectParam(busId: string, effectIndex: number, name: string): number;
     /**
      * Apply a {@link MixerSnapshot}: move each listed bus to its target gain. `duration` 0 snaps
      * instantly; > 0 click-safely ramps (a mix-state blend).

package/src/engine/sound/sopra/SopraEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SopraEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/sopra/SopraEngine.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"SopraEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/sopra/SopraEngine.js"],"names":[],"mappings":"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"}

package/src/engine/sound/sopra/SopraEngine.js

@@ -62,23 +62,54 @@ export class SopraEngine {
     voiceManager = new VoiceManager();
 
     /**
-     * Listener world position for spatialization/attenuation. Null = no listener set yet (events play
-     * unattenuated). In P3 this is driven from the ECS SoundListener.
-     * @type {Vector3|null}
+     * Listener world position for spatialization/attenuation, read by index. Null = no listener set yet
+     * (events play unattenuated). Set it with {@link setListener}, which is also how a move is reported;
+     * the ECS `AudioEmitterSystem` drives it from the `SoundListener` entity's transform.
+     * @type {ArrayLike<number>|null}
      */
     listenerPosition = null;
 
+    /**
+     * Advanced by every {@link setListener}. An instance re-attenuates when this differs from the value it
+     * last attenuated against, so between listener moves nothing is recomputed.
+     * @type {number}
+     */
+    #listenerVersion = 0;
+
     /**
      * @type {Set<EventInstance>}
      */
     #activeInstances = new Set();
 
+    /**
+     * Where {@link update} takes its snapshot of {@link #activeInstances}, kept rather than built each
+     * frame. Emptied after each update so it holds no instance past it.
+     * @type {EventInstance[]}
+     */
+    #updateSnapshot = [];
+
+    /**
+     * Whether an {@link update} is under way. An update reached from inside one — an instance's end
+     * handler ticking the engine — takes a snapshot of its own rather than overwrite the outer one.
+     * @type {boolean}
+     */
+    #updating = false;
+
     /**
      * Active ducking rules + their runtime state.
      * @type {{rule: DuckingRule, engaged: boolean, nominalDb: number}[]}
      */
     #duckers = [];
 
+    /**
+     * The standing rules of {@link bindParameterToBusEffectParam}, kept so {@link setBuses} can put each
+     * one back over the tree it builds.
+     * `held`: the binding has put its target at a bound value at least once — until then a value takes
+     * hold at once, after that a change glides (with a `timeConstant`).
+     * @type {{name: string, busId: string, effectIndex: number, paramName: string, curve: AnimationCurve, timeConstant: number, held: boolean}[]}
+     */
+    #effectBindings = [];
+
     /**
      * @param {BaseAudioContext} audioContext
      * @param {AudioNode} destinationNode master destination the bus root routes into
@@ -152,13 +183,48 @@ export class SopraEngine {
      * feeding the old graph, so anything already playing is silenced by the swap rather than
      * re-routed. Swap between scenes, or stop what is playing first.
      *
+     * Every bus is built at its DEFINED gain, so by default a fader moved since — a player's volume
+     * setting, a bound parameter, a snapshot — is reset by the swap. That is right when the new tree IS
+     * the new mix (loading a scene's authored mix). When the tree changes but the mix should not —
+     * adding a bus to the tree the player has been adjusting — pass `keepVolumes`: each bus present in
+     * both trees keeps its fader where it was, moved the way {@link setBusVolume} moves it (an engaged
+     * duck on it carries over too), and buses new to the tree start at their defined gain. Only the
+     * faders carry: insert-effect parameters start from the new definitions, which may describe
+     * different effects — except one a {@link bindParameterToBusEffectParam} binding holds, which the new
+     * tree is built at the bound value of, with `keepVolumes` or without.
+     *
      * @param {BusDefinition[]} busDefinitions
+     * @param {{keepVolumes?: boolean}} [options]
      */
-    setBuses(busDefinitions) {
-        this.busGraph.dispose();
+    setBuses(busDefinitions, { keepVolumes = false } = {}) {
+        const previous = this.busGraph;
+
+        /**
+         * fader positions to carry over: id -> linear gain
+         * @type {Map<string, number>}
+         */
+        const kept = new Map();
+
+        if (keepVolumes) {
+            for (const [id, bus] of previous.buses) {
+                kept.set(id, bus.nominal);
+            }
+        }
+
+        previous.dispose();
 
         this.busGraph = new BusGraph(this.audioContext, this.destination);
         this.busGraph.build(busDefinitions);
+
+        for (const [id, linear] of kept) {
+            if (this.busGraph.has(id)) {
+                this.setBusVolume(id, linear);
+            }
+        }
+
+        // a binding is a standing rule, not a move made once: the rebuilt effect is put at the bound value
+        // at once, where it would otherwise sit at its definition until the parameter next changed
+        this.#reassertEffectBindings(null);
     }
 
     /**
@@ -265,11 +331,23 @@ export class SopraEngine {
     }
 
     /**
-     * Set the listener world position used for 3D attenuation/culling.
-     * @param {Vector3} position
+     * Set the listener world position used for 3D attenuation/culling, and report that it moved: every 3D
+     * instance re-attenuates against it on the next {@link update}, and none does again until the next
+     * call. Held by reference, so after writing into the same array, call this again with it.
+     * @param {ArrayLike<number>|null} position read by index
      */
     setListener(position) {
         this.listenerPosition = position;
+        this.#listenerVersion++;
+    }
+
+    /**
+     * Advanced by each {@link setListener}: what a 3D instance compares to tell whether the listener has
+     * moved since it last attenuated.
+     * @returns {number}
+     */
+    get listenerVersion() {
+        return this.#listenerVersion;
     }
 
     /**
@@ -278,7 +356,15 @@ export class SopraEngine {
      * @param {number} [defaultValue]
      */
     defineParameter(name, defaultValue = 0) {
+        const fresh = !this.parameters.has(name);
+
         this.parameters.define(name, defaultValue);
+
+        // `define` runs no binding, and a later `set` to the same value is no change, so an effect bound
+        // before its parameter existed would otherwise wait for a different value - or the next setBuses
+        if (fresh) {
+            this.#reassertEffectBindings(name);
+        }
     }
 
     /**
@@ -300,6 +386,169 @@ export class SopraEngine {
         this.parameters.bind(name, (value) => this.setBusVolume(busId, curve.evaluate(value)));
     }
 
+    /**
+     * Drive a parameter of one of a bus's insert effects from a sopra parameter through an
+     * {@link AnimationCurve} — the effect's counterpart of {@link bindParameterToBusVolume}. A game sets
+     * one value (`health`); how far the world's lowpass closes for it is authored in the curve, not
+     * worked out in game code.
+     *
+     * Addressed as {@link setBusEffectParam}, and checked against the tree as it stands: a bus, effect or
+     * parameter it does not have throws here, where the binding was written. The parameter's value takes
+     * hold at once, without a glide: now if it has one, else when it first gets one.
+     *
+     * From then on the binding is a standing rule:
+     * - each change of the parameter moves the effect — now, or with a `timeConstant` above 0 as a glide
+     *   ({@link approachBusEffectParam}), so a value set every frame is tracked smoothly;
+     * - every tree {@link setBuses} builds that has the target starts at the bound value, not at the
+     *   definition it was rebuilt from;
+     * - over a tree without the target it does nothing, and holds again over the next tree that has it.
+     *   (A binding cannot be removed, so it has to outlive a tree swap; a mistyped address is caught at
+     *   the bind.)
+     *
+     * One binding per parameter and target: binding the same pair again replaces its curve and time
+     * constant, and moves the effect to the new curve as a change would — it adds nothing, so binding again
+     * after a {@link setBuses} that keeps the target is harmless. Two parameters bound to one target
+     * take turns — the last to change wins, and after a rebuild the later binding (a re-bind keeps its
+     * place). A direct {@link setBusEffectParam} on a bound effect holds until the parameter next changes.
+     *
+     * The address is positional, like every effect address: reorder a bus's `effects` and the binding
+     * follows whatever now sits at its index.
+     *
+     * @param {string} name sopra parameter, as {@link setParameter} sets it
+     * @param {string} busId
+     * @param {number} effectIndex position in the bus definition's `effects`
+     * @param {string} paramName one of that effect class's `parameters` (`'frequency'` on an `EqEffect`)
+     * @param {AnimationCurve} curve maps the parameter's value to the effect parameter's, in its own units
+     * @param {number} [timeConstant=0] seconds: 0 moves the effect now on each change; above 0 glides
+     */
+    bindParameterToBusEffectParam(name, busId, effectIndex, paramName, curve, timeConstant = 0) {
+        assert.isString(name, 'name');
+        assert.defined(curve, 'curve');
+        assert.isFinite(timeConstant, 'timeConstant');
+        assert.greaterThanOrEqual(timeConstant, 0, 'timeConstant');
+
+        // throws naming what the tree lacks
+        this.busGraph.getEffectParam(busId, effectIndex, paramName);
+
+        const parameters = this.parameters;
+        const existing = this.#findEffectBinding(name, busId, effectIndex, paramName);
+        const binding = { name, busId, effectIndex, paramName, curve, timeConstant, held: existing !== null && existing.held };
+
+        // Put the effect at the bound value BEFORE registering or replacing anything, so a curve that cannot
+        // be applied leaves no half-made binding behind. A new binding takes hold as a move, not a glide - it
+        // does not sweep in from wherever the definition left the effect; one replacing a binding that
+        // already holds the effect moves it the way a change would.
+        if (parameters.has(name)) {
+            this.#applyEffectBinding(binding, parameters.get(name), binding.held ? timeConstant : 0);
+        }
+
+        if (existing !== null) {
+            // the store already calls the one callback this pair has, and it reads the record
+            existing.curve = curve;
+            existing.timeConstant = timeConstant;
+            existing.held = binding.held;
+
+            return;
+        }
+
+        this.#effectBindings.push(binding);
+
+        // the store calls a callback once as it is bound, when the parameter has a value; that one is
+        // already applied above
+        let bound = false;
+
+        parameters.bind(name, (value) => {
+            if (bound) {
+                // a parameter's first value takes hold; only a change after that is a glide
+                this.#applyEffectBinding(binding, value, binding.held ? binding.timeConstant : 0);
+            }
+        });
+
+        bound = true;
+    }
+
+    /**
+     * @param {string} name
+     * @param {string} busId
+     * @param {number} effectIndex
+     * @param {string} paramName
+     * @returns {{name: string, busId: string, effectIndex: number, paramName: string, curve: AnimationCurve, timeConstant: number, held: boolean}|null}
+     */
+    #findEffectBinding(name, busId, effectIndex, paramName) {
+        const bindings = this.#effectBindings;
+
+        for (let i = 0; i < bindings.length; i++) {
+            const b = bindings[i];
+
+            if (b.name === name && b.busId === busId && b.effectIndex === effectIndex && b.paramName === paramName) {
+                return b;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Put every effect binding — or only those of parameter `name` — at its bound value now, over the
+     * current tree. Each is tried: one whose curve cannot be applied (a stored value it cannot evaluate)
+     * does not keep the rest from holding, and the first such failure is thrown once they all have.
+     * @param {string|null} name null: every binding
+     */
+    #reassertEffectBindings(name) {
+        const bindings = this.#effectBindings;
+        const parameters = this.parameters;
+
+        let failure = null;
+
+        for (let i = 0; i < bindings.length; i++) {
+            const binding = bindings[i];
+
+            if ((name !== null && binding.name !== name) || !parameters.has(binding.name)) {
+                continue;
+            }
+
+            try {
+                this.#applyEffectBinding(binding, parameters.get(binding.name), 0);
+            } catch (e) {
+                if (failure === null) {
+                    failure = e;
+                }
+            }
+        }
+
+        if (failure !== null) {
+            throw failure;
+        }
+    }
+
+    /**
+     * Put one effect binding's target at the curve's value for `value`, over the current tree — if it has
+     * that target at all (see {@link bindParameterToBusEffectParam}).
+     * @param {{busId: string, effectIndex: number, paramName: string, curve: AnimationCurve, held: boolean}} binding
+     * @param {number} value the sopra parameter's
+     * @param {number} timeConstant 0 moves it now; above 0 glides
+     */
+    #applyEffectBinding(binding, value, timeConstant) {
+        const graph = this.busGraph;
+        const busId = binding.busId;
+        const effectIndex = binding.effectIndex;
+        const paramName = binding.paramName;
+
+        if (!graph.hasEffectParam(busId, effectIndex, paramName)) {
+            return;
+        }
+
+        const target = binding.curve.evaluate(value);
+
+        if (timeConstant > 0) {
+            graph.approachEffectParam(busId, effectIndex, paramName, target, timeConstant);
+        } else {
+            graph.setEffectParam(busId, effectIndex, paramName, target);
+        }
+
+        binding.held = true;
+    }
+
     /**
      * @param {string} busId
      * @returns {number} linear gain
@@ -318,6 +567,53 @@ export class SopraEngine {
         this.#reduck(busId);
     }
 
+    /**
+     * Move a parameter of one of a bus's insert effects ({@link BusDefinition.effects}), now.
+     *
+     * The effect is addressed by its position in the bus definition's `effects`, the parameter by one of
+     * its class's `parameters` — the name of the definition field it starts from (`'frequency'` on an
+     * `EqEffect`). It moves the bus's built copy only; the definition is never touched, and
+     * {@link setBuses} rebuilds from it. Whatever automation was in flight on the parameter is cancelled.
+     *
+     * @param {string} busId
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value in the parameter's own units (Hz, dB, seconds, ...)
+     */
+    setBusEffectParam(busId, effectIndex, name, value) {
+        this.busGraph.setEffectParam(busId, effectIndex, name, value);
+    }
+
+    /**
+     * Glide a parameter of one of a bus's insert effects toward `value` — a lowpass closing over the
+     * world as health runs out, a compressor's threshold riding a game state. Exponential, covering ~63%
+     * of the way per `timeConstant`, like the fader's ducking glide. Whatever was in flight is cancelled
+     * and held first, so a value sent every frame retargets from wherever the last glide had got to.
+     *
+     * Addressed as {@link setBusEffectParam}.
+     *
+     * @param {string} busId
+     * @param {number} effectIndex
+     * @param {string} name
+     * @param {number} value
+     * @param {number} timeConstant seconds, above 0
+     */
+    approachBusEffectParam(busId, effectIndex, name, value, timeConstant) {
+        this.busGraph.approachEffectParam(busId, effectIndex, name, value, timeConstant);
+    }
+
+    /**
+     * Where a bus effect's parameter was last sent (the target of a glide still in flight), or its
+     * defined value if it has not been moved.
+     * @param {string} busId
+     * @param {number} effectIndex
+     * @param {string} name
+     * @returns {number}
+     */
+    getBusEffectParam(busId, effectIndex, name) {
+        return this.busGraph.getEffectParam(busId, effectIndex, name);
+    }
+
     /**
      * Apply a {@link MixerSnapshot}: move each listed bus to its target gain. `duration` 0 snaps
      * instantly; > 0 click-safely ramps (a mix-state blend).
@@ -362,13 +658,32 @@ export class SopraEngine {
      * @param {number} [now] context time; defaults to the live clock
      */
     update(now = this.currentTime) {
-        const listenerPosition = this.listenerPosition;
+        /*
+         Snapshot: an instance may finish (and remove itself) during its own update, and one played from
+         inside an update waits for the next. Written by index into a kept array up to a count, and
+         nulled after, rather than emptied with `length = 0`, which lets V8 trim the store it would only
+         grow back on the next frame.
+        */
+        const nested = this.#updating;
+        const instances = nested ? [] : this.#updateSnapshot;
+
+        let count = 0;
+
+        for (const instance of this.#activeInstances) {
+            instances[count++] = instance;
+        }
 
-        // snapshot — an instance may finish (and remove itself) during its own update
-        const instances = [...this.#activeInstances];
+        this.#updating = true;
+
+        try {
+            for (let i = 0; i < count; i++) {
+                // each reads the listener itself, with the version that goes with it
+                instances[i].update(now);
+            }
+        } finally {
+            this.#updating = nested;
 
-        for (let i = 0; i < instances.length; i++) {
-            instances[i].update(now, listenerPosition);
+            instances.fill(null, 0, count);
         }
 
         this.#updateDuckers();

package/src/engine/sound/sopra/definition/EventDescription.d.ts

@@ -11,7 +11,7 @@ export class EventDescription {
      * @param {Partial<EventDescription>} [options]
      * @returns {EventDescription}
      */
-    static from(label: string, rootClip: AbstractAudioClip, { busId, gainDb, is3D, panningModel, distanceMin, distanceMax, attenuation, maxInstances, priority, stealMode, virtualThresholdDb }?: Partial<EventDescription>): EventDescription;
+    static from(label: string, rootClip: AbstractAudioClip, { busId, gainDb, is3D, panningModel, distanceMin, distanceMax, attenuation, maxInstances, priority, stealMode, virtualThresholdDb, effects }?: Partial<EventDescription>): EventDescription;
     /**
      * Human-readable label (need not be unique).
      * @type {string}
@@ -76,6 +76,21 @@ export class EventDescription {
      * @type {number}
      */
     virtualThresholdDb: number;
+    /**
+     * Insert effects every instance of this event plays through, in order — the event's own DSP, as a
+     * bus has its own ({@link BusDefinition.effects}). Each instance builds its own copy, ahead of its
+     * fader: `voices → effects[0] → … → effects[n] → instance gain → (3D chain) → bus`.
+     *
+     * Because the copy is per instance, so is its control: one play of an event can be filtered or
+     * compressed independently of every other play of it, through {@link EventInstance#setEffectParam}.
+     * Empty (the default) builds nothing.
+     *
+     * Part of {@link equals} and {@link hash}, like every authored field — so never edit an effect's fields
+     * in place on a description that is playing: the `VoiceManager` files live instances under the hash, and
+     * a moved field loses them. Move a playing effect through its instance.
+     * @type {AbstractAudioEffect[]}
+     */
+    effects: AbstractAudioEffect[];
     /**
      *
      * @param {EventDescription} other
@@ -94,6 +109,11 @@ export class EventDescription {
         label: string;
         rootClip: {
             type: string;
+            /**
+             * The triggerable unit (FMOD EventDescription / Wwise Actor-Mixer object). Immutable authored data;
+             * playing it spawns a transient {@link EventInstance}. Held as data (e.g. by an `AudioEmitter`) and
+             * passed directly to {@link SopraEngine.playEvent} / `playOneShot`.
+             */
             data: any;
         };
         busId: string;
@@ -109,8 +129,12 @@ export class EventDescription {
         priority: number;
         stealMode: number;
         virtualThresholdDb: number;
+        effects: {
+            type: string;
+            data: any;
+        }[];
     };
-    fromJSON({ label, rootClip, busId, gainDb, is3D, panningModel, distanceMin, distanceMax, attenuation, maxInstances, priority, stealMode, virtualThresholdDb }: {
+    fromJSON({ label, rootClip, busId, gainDb, is3D, panningModel, distanceMin, distanceMax, attenuation, maxInstances, priority, stealMode, virtualThresholdDb, effects }: {
         label?: string;
         rootClip: any;
         busId?: string;
@@ -124,12 +148,14 @@ export class EventDescription {
         priority?: number;
         stealMode?: number;
         virtualThresholdDb?: number;
+        effects?: any[];
     }): void;
 }
 export namespace EventDescription {
     let typeName: string;
 }
 export type AbstractAudioClip = import("./clip/AbstractAudioClip.js").AbstractAudioClip;
+export type AbstractAudioEffect = import("./effect/AbstractAudioEffect.js").AbstractAudioEffect;
 import { SopraPanningModel } from "./SopraPanningModel.js";
 import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
 import { VoiceStealMode } from "./VoiceStealMode.js";

package/src/engine/sound/sopra/definition/EventDescription.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EventDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/EventDescription.js"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH;IA+EI;;;;;;OAMG;IACH,mBALW,MAAM,YACN,iBAAiB,wIACjB,QAAQ,gBAAgB,CAAC,GACvB,gBAAgB,CAgC5B;IAlHD;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,UAFU,iBAAiB,CAEO;IAElC;;;OAGG;IACH,OAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,OAAO,CAEJ;IAEb;;;OAGG;IACH,cAFU,iBAAiB,GAAC,MAAM,CAEI;IAEtC;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,aAFU,cAAc,CAEW;IAEnC;;;OAGG;IACH,cAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEG;IAElC;;;OAGG;IACH,oBAFU,MAAM,CAES;IAyCzB;;;;OAIG;IACH,cAHW,gBAAgB,GACd,OAAO,CAgBnB;IAED;;;;;OAKG;IACH,QAFa,MAAM,CA4BlB;IAED,0BAkBC;IAED;;;;;;;;;;;;;;;;;;;MAgBC;IAED;;;;;;;;;;;;;;aAmCC;CACJ;;;;gCAvQY,OAAO,6BAA6B,EAAE,iBAAiB;kCAJlC,wBAAwB;+BAH3B,4CAA4C;+BAI5C,qBAAqB"}
+{"version":3,"file":"EventDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/EventDescription.js"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH;IA+FI;;;;;;OAMG;IACH,mBALW,MAAM,YACN,iBAAiB,iJACjB,QAAQ,gBAAgB,CAAC,GACvB,gBAAgB,CAkC5B;IApID;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,UAFU,iBAAiB,CAEO;IAElC;;;OAGG;IACH,OAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,OAAO,CAEJ;IAEb;;;OAGG;IACH,cAFU,iBAAiB,GAAC,MAAM,CAEI;IAEtC;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,aAFU,cAAc,CAEW;IAEnC;;;OAGG;IACH,cAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,WAFU,cAAc,GAAC,MAAM,CAEG;IAElC;;;OAGG;IACH,oBAFU,MAAM,CAES;IAEzB;;;;;;;;;;;;;OAaG;IACH,SAFU,mBAAmB,EAAE,CAElB;IA2Cb;;;;OAIG;IACH,cAHW,gBAAgB,GACd,OAAO,CA4BnB;IAED;;;;;OAKG;IACH,QAFa,MAAM,CAoClB;IAED,0BAmBC;IAED;;;;YA7OJ;;;;eAIG;;;;;;;;;;;;;;;;;;;;MA0PE;IAED;;;;;;;;;;;;;;;aAsCC;CACJ;;;;gCAnTY,OAAO,6BAA6B,EAAE,iBAAiB;kCACvD,OAAO,iCAAiC,EAAE,mBAAmB;kCALxC,wBAAwB;+BAR3B,4CAA4C;+BAS5C,qBAAqB"}