@woosh/meep-engine 3.46.0 → 3.49.0

package/src/engine/sound/sopra/definition/EventDescription.js

@@ -1,14 +1,21 @@
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
 import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
 import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
-import { deserializeAudioClipFromJSON, serializeAudioClipToJSON } from "../serialization/sopraJSON.js";
+import {
+    deserializeAudioClipFromJSON,
+    deserializeAudioEffectFromJSON,
+    serializeAudioClipToJSON,
+    serializeAudioEffectToJSON
+} from "../serialization/sopraJSON.js";
 import { SilenceAudioClip } from "./clip/SilenceAudioClip.js";
 import { SopraPanningModel } from "./SopraPanningModel.js";
 import { VoiceStealMode } from "./VoiceStealMode.js";
 
 /**
  * @typedef {import("./clip/AbstractAudioClip.js").AbstractAudioClip} AbstractAudioClip
+ * @typedef {import("./effect/AbstractAudioEffect.js").AbstractAudioEffect} AbstractAudioEffect
  */
 
 /**
@@ -103,6 +110,22 @@ export class EventDescription {
      */
     virtualThresholdDb = -60;
 
+    /**
+     * 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 = [];
+
     /**
      *
      * @param {string} label
@@ -121,7 +144,8 @@ export class EventDescription {
         maxInstances = 32,
         priority = 0,
         stealMode = VoiceStealMode.Oldest,
-        virtualThresholdDb = -60
+        virtualThresholdDb = -60,
+        effects = []
     } = {}) {
         const r = new EventDescription();
 
@@ -138,6 +162,7 @@ export class EventDescription {
         r.priority = priority;
         r.stealMode = stealMode;
         r.virtualThresholdDb = virtualThresholdDb;
+        r.effects = effects;
 
         return r;
     }
@@ -148,6 +173,18 @@ export class EventDescription {
      * @returns {boolean}
      */
     equals(other) {
+        const effects = this.effects;
+
+        if (effects.length !== other.effects.length) {
+            return false;
+        }
+
+        for (let i = 0; i < effects.length; i++) {
+            if (!effects[i].equals(other.effects[i])) {
+                return false;
+            }
+        }
+
         return this.label === other.label
             && this.busId === other.busId
             && this.gainDb === other.gainDb
@@ -170,7 +207,7 @@ export class EventDescription {
      * @returns {number}
      */
     hash() {
-        return hash_mix3(
+        let h = hash_mix3(
             hash_mix3(
                 hash_mix3(
                     hash_mix3(
@@ -195,6 +232,14 @@ export class EventDescription {
             this.attenuation.hash(),
             this.rootClip.hash()
         );
+
+        const effects = this.effects;
+
+        for (let i = 0; i < effects.length; i++) {
+            h = hash_mix2(h, effects[i].hash());
+        }
+
+        return h;
     }
 
     clone() {
@@ -213,6 +258,7 @@ export class EventDescription {
         r.priority = this.priority;
         r.stealMode = this.stealMode;
         r.virtualThresholdDb = this.virtualThresholdDb;
+        r.effects = this.effects.map(e => e.clone());
 
         return r;
     }
@@ -231,7 +277,8 @@ export class EventDescription {
             maxInstances: this.maxInstances,
             priority: this.priority,
             stealMode: this.stealMode,
-            virtualThresholdDb: this.virtualThresholdDb
+            virtualThresholdDb: this.virtualThresholdDb,
+            effects: this.effects.map(serializeAudioEffectToJSON)
         };
     }
 
@@ -248,7 +295,9 @@ export class EventDescription {
         maxInstances = 32,
         priority = 0,
         stealMode = VoiceStealMode.Oldest,
-        virtualThresholdDb = -60
+        virtualThresholdDb = -60,
+        // absent from JSON written before events carried inserts
+        effects = []
     }) {
         this.label = label;
         this.rootClip = rootClip === undefined ? new SilenceAudioClip() : deserializeAudioClipFromJSON(rootClip);
@@ -270,6 +319,7 @@ export class EventDescription {
         this.priority = priority;
         this.stealMode = stealMode;
         this.virtualThresholdDb = virtualThresholdDb;
+        this.effects = effects.map(deserializeAudioEffectFromJSON);
     }
 }
 

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

@@ -1,3 +1,13 @@
+/**
+ * Format history:
+ * - 0: every field but the inserts.
+ * - 1: {@link EventDescription.effects} appended, as a count and then each effect by type
+ *   (upgrade: `EventDescriptionSerializationUpgrader_0_1`).
+ *
+ * ⚠ The record is also EMBEDDED, without its own version tag, by the `AudioEmitter` and
+ * `AudioEventTrigger` component adapters, so a change here is a change to their formats too: bump them
+ * with it, and have their upgraders run the embedded record through this class's upgrader for the same step.
+ */
 export class EventDescriptionSerializationAdapter extends ObjectBasedClassSerializationAdapter {
     klass: typeof EventDescription;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"EventDescriptionSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/EventDescriptionSerializationAdapter.js"],"names":[],"mappings":"AAOA;IACI,+BAAyB;IAGzB;;;OAGG;IACH,uCAFW,gBAAgB,QAkB1B;IAED;;;OAGG;IACH,yCAFW,gBAAgB,QAkB1B;CACJ;qDAlDoD,4EAA4E;iCAChG,uBAAuB"}
+{"version":3,"file":"EventDescriptionSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/EventDescriptionSerializationAdapter.js"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH;IACI,+BAAyB;IAGzB;;;OAGG;IACH,uCAFW,gBAAgB,QAwB1B;IAED;;;OAGG;IACH,yCAFW,gBAAgB,QAwB1B;CACJ;qDAxEoD,4EAA4E;iCAChG,uBAAuB"}

package/src/engine/sound/sopra/definition/EventDescriptionSerializationAdapter.js

@@ -1,55 +1,77 @@
-import {
-    deserialize_animation_curve,
-    serialize_animation_curve
-} from "../../../animation/curve/animation_curve_binary_codec.js";
-import { ObjectBasedClassSerializationAdapter } from "../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
-import { EventDescription } from "./EventDescription.js";
-
-export class EventDescriptionSerializationAdapter extends ObjectBasedClassSerializationAdapter {
-    klass = EventDescription;
-    version = 0;
-
-    /**
-     * @param {BinaryBuffer} buffer
-     * @param {EventDescription} value
-     */
-    serialize(buffer, value) {
-        buffer.writeUTF8String(value.label);
-        this.objectAdapter.serialize(buffer, value.rootClip);
-        buffer.writeUTF8String(value.busId);
-        buffer.writeFloat32(value.gainDb);
-        buffer.writeUint8(value.is3D ? 1 : 0);
-        buffer.writeUint8(value.panningModel);
-        buffer.writeFloat32(value.distanceMin);
-        buffer.writeFloat32(value.distanceMax);
-
-        serialize_animation_curve(buffer, value.attenuation);
-
-        buffer.writeUintVar(value.maxInstances);
-        buffer.writeFloat32(value.priority);
-        buffer.writeUint8(value.stealMode);
-        buffer.writeFloat32(value.virtualThresholdDb);
-    }
-
-    /**
-     * @param {BinaryBuffer} buffer
-     * @param {EventDescription} value
-     */
-    deserialize(buffer, value) {
-        value.label = buffer.readUTF8String();
-        value.rootClip = this.objectAdapter.deserialize(buffer);
-        value.busId = buffer.readUTF8String();
-        value.gainDb = buffer.readFloat32();
-        value.is3D = buffer.readUint8() !== 0;
-        value.panningModel = buffer.readUint8();
-        value.distanceMin = buffer.readFloat32();
-        value.distanceMax = buffer.readFloat32();
-
-        value.attenuation = deserialize_animation_curve(buffer);
-
-        value.maxInstances = buffer.readUintVar();
-        value.priority = buffer.readFloat32();
-        value.stealMode = buffer.readUint8();
-        value.virtualThresholdDb = buffer.readFloat32();
-    }
-}
+import {
+    deserialize_animation_curve,
+    serialize_animation_curve
+} from "../../../animation/curve/animation_curve_binary_codec.js";
+import { ObjectBasedClassSerializationAdapter } from "../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
+import { EventDescription } from "./EventDescription.js";
+
+/**
+ * Format history:
+ * - 0: every field but the inserts.
+ * - 1: {@link EventDescription.effects} appended, as a count and then each effect by type
+ *   (upgrade: `EventDescriptionSerializationUpgrader_0_1`).
+ *
+ * ⚠ The record is also EMBEDDED, without its own version tag, by the `AudioEmitter` and
+ * `AudioEventTrigger` component adapters, so a change here is a change to their formats too: bump them
+ * with it, and have their upgraders run the embedded record through this class's upgrader for the same step.
+ */
+export class EventDescriptionSerializationAdapter extends ObjectBasedClassSerializationAdapter {
+    klass = EventDescription;
+    version = 1;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {EventDescription} value
+     */
+    serialize(buffer, value) {
+        buffer.writeUTF8String(value.label);
+        this.objectAdapter.serialize(buffer, value.rootClip);
+        buffer.writeUTF8String(value.busId);
+        buffer.writeFloat32(value.gainDb);
+        buffer.writeUint8(value.is3D ? 1 : 0);
+        buffer.writeUint8(value.panningModel);
+        buffer.writeFloat32(value.distanceMin);
+        buffer.writeFloat32(value.distanceMax);
+
+        serialize_animation_curve(buffer, value.attenuation);
+
+        buffer.writeUintVar(value.maxInstances);
+        buffer.writeFloat32(value.priority);
+        buffer.writeUint8(value.stealMode);
+        buffer.writeFloat32(value.virtualThresholdDb);
+
+        const effects = value.effects;
+        buffer.writeUintVar(effects.length);
+        for (let i = 0; i < effects.length; i++) {
+            this.objectAdapter.serialize(buffer, effects[i]);
+        }
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {EventDescription} value
+     */
+    deserialize(buffer, value) {
+        value.label = buffer.readUTF8String();
+        value.rootClip = this.objectAdapter.deserialize(buffer);
+        value.busId = buffer.readUTF8String();
+        value.gainDb = buffer.readFloat32();
+        value.is3D = buffer.readUint8() !== 0;
+        value.panningModel = buffer.readUint8();
+        value.distanceMin = buffer.readFloat32();
+        value.distanceMax = buffer.readFloat32();
+
+        value.attenuation = deserialize_animation_curve(buffer);
+
+        value.maxInstances = buffer.readUintVar();
+        value.priority = buffer.readFloat32();
+        value.stealMode = buffer.readUint8();
+        value.virtualThresholdDb = buffer.readFloat32();
+
+        const effectCount = buffer.readUintVar();
+        value.effects = [];
+        for (let i = 0; i < effectCount; i++) {
+            value.effects.push(this.objectAdapter.deserialize(buffer));
+        }
+    }
+}

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

@@ -0,0 +1,31 @@
+/**
+ * @typedef {import("../../../ecs/storage/binary/BinarySerializationRegistry.js").BinarySerializationRegistry} BinarySerializationRegistry
+ */
+/**
+ * Version 0 → 1: an event gains its insert effects (`EventDescription.effects`), written after every other
+ * field. A version-0 record had none, so it upgrades to itself followed by an empty list.
+ *
+ * Field by field, as every upgrader must: `source` and `target` need not share an encoding (the dataset
+ * stream dictionary-encodes its strings, the upgrade buffers do not), so bytes are never copied raw. The
+ * version-0 layout is frozen here rather than borrowed from the current adapter, so a later format change
+ * cannot alter what this step produces.
+ *
+ * The one field that is not a flat value is the root clip, a polymorphic tree whose length is not known
+ * until it is read. It is read through the object adapter (which upgrades it, if it was saved at an older
+ * clip format) and written back at its current format under its own type-and-version header — clip formats
+ * are versioned by that header, independently of this record's.
+ *
+ * Also the upgrade of the record wherever a component EMBEDS it untagged (`AudioEmitter`,
+ * `AudioEventTrigger`): their upgraders hand the embedded span to {@link upgrade}, which consumes exactly
+ * one record from `source`.
+ */
+export class EventDescriptionSerializationUpgrader_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=EventDescriptionSerializationUpgrader_0_1.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EventDescriptionSerializationUpgrader_0_1.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/EventDescriptionSerializationUpgrader_0_1.js"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH;IASI;;OAEG;IACH,sBAFW,2BAA2B,EAMrC;;CAgCJ;0CArEY,OAAO,4DAA4D,EAAE,2BAA2B;oCAJzE,oDAAoD"}

package/src/engine/sound/sopra/definition/EventDescriptionSerializationUpgrader_0_1.js

@@ -0,0 +1,75 @@
+import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { BinaryClassUpgrader } from "../../../ecs/storage/binary/BinaryClassUpgrader.js";
+import { BinaryObjectSerializationAdapter } from "../../../ecs/storage/binary/object/BinaryObjectSerializationAdapter.js";
+
+/**
+ * @typedef {import("../../../ecs/storage/binary/BinarySerializationRegistry.js").BinarySerializationRegistry} BinarySerializationRegistry
+ */
+
+/**
+ * Version 0 → 1: an event gains its insert effects (`EventDescription.effects`), written after every other
+ * field. A version-0 record had none, so it upgrades to itself followed by an empty list.
+ *
+ * Field by field, as every upgrader must: `source` and `target` need not share an encoding (the dataset
+ * stream dictionary-encodes its strings, the upgrade buffers do not), so bytes are never copied raw. The
+ * version-0 layout is frozen here rather than borrowed from the current adapter, so a later format change
+ * cannot alter what this step produces.
+ *
+ * The one field that is not a flat value is the root clip, a polymorphic tree whose length is not known
+ * until it is read. It is read through the object adapter (which upgrades it, if it was saved at an older
+ * clip format) and written back at its current format under its own type-and-version header — clip formats
+ * are versioned by that header, independently of this record's.
+ *
+ * Also the upgrade of the record wherever a component EMBEDS it untagged (`AudioEmitter`,
+ * `AudioEventTrigger`): their upgraders hand the embedded span to {@link upgrade}, which consumes exactly
+ * one record from `source`.
+ */
+export class EventDescriptionSerializationUpgrader_0_1 extends BinaryClassUpgrader {
+    __startVersion = 0;
+    __targetVersion = 1;
+
+    /**
+     * @type {BinaryObjectSerializationAdapter}
+     */
+    #objects = new BinaryObjectSerializationAdapter();
+
+    /**
+     * @param {BinarySerializationRegistry} registry where the event's clip types are registered
+     */
+    constructor(registry) {
+        super();
+
+        this.#objects.initialize(registry);
+    }
+
+    /**
+     * @param {BinaryBuffer} source
+     * @param {BinaryBuffer} target
+     */
+    upgrade(source, target) {
+        BinaryBuffer.copyUTF8String(source, target); // label
+
+        this.#objects.serialize(target, this.#objects.deserialize(source)); // rootClip
+
+        BinaryBuffer.copyUTF8String(source, target); // busId
+        BinaryBuffer.copyFloat32(source, target); // gainDb
+        BinaryBuffer.copyUint8(source, target); // is3D
+        BinaryBuffer.copyUint8(source, target); // panningModel
+        BinaryBuffer.copyFloat32(source, target); // distanceMin
+        BinaryBuffer.copyFloat32(source, target); // distanceMax
+
+        // attenuation: key count, then time / value / inTangent / outTangent per key
+        const keyCount = BinaryBuffer.copyUintVar(source, target);
+        for (let i = 0; i < keyCount * 4; i++) {
+            BinaryBuffer.copyFloat32(source, target);
+        }
+
+        BinaryBuffer.copyUintVar(source, target); // maxInstances
+        BinaryBuffer.copyFloat32(source, target); // priority
+        BinaryBuffer.copyUint8(source, target); // stealMode
+        BinaryBuffer.copyFloat32(source, target); // virtualThresholdDb
+
+        // new in 1: no inserts
+        target.writeUintVar(0);
+    }
+}

package/src/engine/sound/sopra/definition/effect/AbstractAudioEffect.d.ts

@@ -1,24 +1,53 @@
 /**
- * Base class for serializable bus insert effects.
+ * What {@link AbstractAudioEffect#build} returns: the live sub-graph, as the two nodes it is spliced in by,
+ * and the parameters that can be moved while it plays.
  *
- * An effect is a DEFINITION; {@link build} turns it into a live WebAudio sub-graph. The returned
- * `{ input, output }` lets the {@link BusGraph} splice the effect into a bus chain
- * (`input → effect → output`); for single-node effects `input === output`.
+ * `params` holds the live {@link AudioParam} of each of the class's {@link AbstractAudioEffect.parameters},
+ * in that order. Omitted by an effect that declares none.
+ *
+ * @typedef {{input: AudioNode, output: AudioNode, params?: AudioParam[]}} BuiltAudioEffect
+ */
+/**
+ * Base class for serializable insert effects — on a bus ({@link BusDefinition.effects}) or on an event
+ * ({@link EventDescription.effects}).
+ *
+ * An effect is a DEFINITION; {@link build} turns it into a live WebAudio sub-graph, once per bus or once per
+ * playing instance. The returned `{ input, output }` lets an {@link EffectChain} splice the effect in
+ * (`input → effect → output`); for single-node effects `input === output`. The definition is never touched
+ * at runtime: a parameter moved on a built effect moves that one copy (see `SopraEngine.setBusEffectParam`,
+ * `EventInstance.setEffectParam`).
+ *
+ * A subclass that has parameters worth moving while it plays names them in a static `parameters` list and
+ * returns their `AudioParam`s from {@link build} in the same order. An "effect param" is one of those — a
+ * live `AudioParam` of an insert — which is not the same thing as a sopra parameter (the named game value
+ * of `SopraEngine.setParameter`).
  */
 export class AbstractAudioEffect {
     /**
      * Construct the live WebAudio nodes for this effect.
      * @param {BaseAudioContext} ctx
-     * @returns {{input: AudioNode, output: AudioNode}}
+     * @returns {BuiltAudioEffect}
      */
-    build(ctx: BaseAudioContext): {
-        input: AudioNode;
-        output: AudioNode;
-    };
+    build(ctx: BaseAudioContext): BuiltAudioEffect;
     /**
      * @readonly
      * @type {boolean}
      */
     readonly isAudioEffect: boolean;
 }
+export namespace AbstractAudioEffect {
+    let parameters: string[];
+}
+/**
+ * What {@link AbstractAudioEffectbuild } returns: the live sub-graph, as the two nodes it is spliced in by,
+ * and the parameters that can be moved while it plays.
+ *
+ * `params` holds the live {@link AudioParam } of each of the class's {@link AbstractAudioEffect.parameters },
+ * in that order. Omitted by an effect that declares none.
+ */
+export type BuiltAudioEffect = {
+    input: AudioNode;
+    output: AudioNode;
+    params?: AudioParam[];
+};
 //# sourceMappingURL=AbstractAudioEffect.d.ts.map

package/src/engine/sound/sopra/definition/effect/AbstractAudioEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractAudioEffect.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/effect/AbstractAudioEffect.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;IAEI;;;;OAIG;IACH,WAHW,gBAAgB,GACd;QAAC,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAC,CAIjD;IAGL;;;OAGG;IACH,wBAFU,OAAO,CAE0B;CAN1C"}
+{"version":3,"file":"AbstractAudioEffect.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/effect/AbstractAudioEffect.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;GAcG;AACH;IAEI;;;;OAIG;IACH,WAHW,gBAAgB,GACd,gBAAgB,CAI5B;IAcL;;;OAGG;IACH,wBAFU,OAAO,CAE0B;CAjB1C;;oBASS,MAAM,EAAE;;;;;;;;;+BArCL;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;CAAC"}

package/src/engine/sound/sopra/definition/effect/AbstractAudioEffect.js

@@ -1,22 +1,51 @@
 /**
- * Base class for serializable bus insert effects.
+ * What {@link AbstractAudioEffect#build} returns: the live sub-graph, as the two nodes it is spliced in by,
+ * and the parameters that can be moved while it plays.
  *
- * An effect is a DEFINITION; {@link build} turns it into a live WebAudio sub-graph. The returned
- * `{ input, output }` lets the {@link BusGraph} splice the effect into a bus chain
- * (`input → effect → output`); for single-node effects `input === output`.
+ * `params` holds the live {@link AudioParam} of each of the class's {@link AbstractAudioEffect.parameters},
+ * in that order. Omitted by an effect that declares none.
+ *
+ * @typedef {{input: AudioNode, output: AudioNode, params?: AudioParam[]}} BuiltAudioEffect
+ */
+
+/**
+ * Base class for serializable insert effects — on a bus ({@link BusDefinition.effects}) or on an event
+ * ({@link EventDescription.effects}).
+ *
+ * An effect is a DEFINITION; {@link build} turns it into a live WebAudio sub-graph, once per bus or once per
+ * playing instance. The returned `{ input, output }` lets an {@link EffectChain} splice the effect in
+ * (`input → effect → output`); for single-node effects `input === output`. The definition is never touched
+ * at runtime: a parameter moved on a built effect moves that one copy (see `SopraEngine.setBusEffectParam`,
+ * `EventInstance.setEffectParam`).
+ *
+ * A subclass that has parameters worth moving while it plays names them in a static `parameters` list and
+ * returns their `AudioParam`s from {@link build} in the same order. An "effect param" is one of those — a
+ * live `AudioParam` of an insert — which is not the same thing as a sopra parameter (the named game value
+ * of `SopraEngine.setParameter`).
  */
 export class AbstractAudioEffect {
 
     /**
      * Construct the live WebAudio nodes for this effect.
      * @param {BaseAudioContext} ctx
-     * @returns {{input: AudioNode, output: AudioNode}}
+     * @returns {BuiltAudioEffect}
      */
     build(ctx) {
         throw new Error('Implementation must override build()');
     }
 }
 
+/**
+ * The names of the parameters this class's built effect can move while it plays, in the order
+ * {@link AbstractAudioEffect#build} returns their `AudioParam`s. Each is the name of the definition field
+ * it starts from, so the field that authors a value and the name that moves it are one word. Declared
+ * once per CLASS, so a built effect carries no names of its own. Empty: nothing to move — which is also
+ * what a subclass written before parameters existed inherits.
+ * @readonly
+ * @type {string[]}
+ */
+AbstractAudioEffect.parameters = [];
+
 /**
  * @readonly
  * @type {boolean}

package/src/engine/sound/sopra/definition/effect/CompressorEffect.d.ts

@@ -1,6 +1,9 @@
 /**
- * Dynamics compressor bus insert, backed by a {@link DynamicsCompressorNode}.
- * NOTE: this is a per-bus insert; the engine's master compressor (in SoundEngine) is separate
+ * @typedef {import("./AbstractAudioEffect.js").BuiltAudioEffect} BuiltAudioEffect
+ */
+/**
+ * Dynamics compressor insert (on a bus or an event), backed by a {@link DynamicsCompressorNode}.
+ * NOTE: this is a per-bus or per-instance insert; the engine's master compressor (in SoundEngine) is separate
  * master-glue and is not duplicated here.
  */
 export class CompressorEffect extends AbstractAudioEffect {
@@ -65,6 +68,8 @@ export class CompressorEffect extends AbstractAudioEffect {
 }
 export namespace CompressorEffect {
     let typeName: string;
+    let parameters: string[];
 }
+export type BuiltAudioEffect = import("./AbstractAudioEffect.js").BuiltAudioEffect;
 import { AbstractAudioEffect } from "./AbstractAudioEffect.js";
 //# sourceMappingURL=CompressorEffect.d.ts.map

package/src/engine/sound/sopra/definition/effect/CompressorEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompressorEffect.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/effect/CompressorEffect.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IA+BI;;;;OAIG;IACH,0DAHW;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,IAAI,CAAC,EAAC,MAAM,CAAC;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,OAAO,CAAC,EAAC,MAAM,CAAA;KAAC,GAC/E,gBAAgB,CAY5B;IA5CD;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;OAEG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,QAFU,MAAM,CAED;IAEf;;;OAGG;IACH,SAFU,MAAM,CAED;IAmCf;;;;OAIG;IACH,cAHW,gBAAgB,GACd,OAAO,CAQnB;IAED,eAUC;IAED,0BAEC;IAED;;;;;;MAQC;IAED;;;;;;aAMC;CACJ;;;;oCArHmC,0BAA0B"}
+{"version":3,"file":"CompressorEffect.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/effect/CompressorEffect.js"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;;;GAIG;AACH;IA+BI;;;;OAIG;IACH,0DAHW;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,IAAI,CAAC,EAAC,MAAM,CAAC;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,OAAO,CAAC,EAAC,MAAM,CAAA;KAAC,GAC/E,gBAAgB,CAY5B;IA5CD;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;OAEG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,QAFU,MAAM,CAED;IAEf;;;OAGG;IACH,SAFU,MAAM,CAED;IAuCf;;;;OAIG;IACH,cAHW,gBAAgB,GACd,OAAO,CAQnB;IAED,eAUC;IAED,0BAEC;IAED;;;;;;MAQC;IAED;;;;;;aAMC;CACJ;;;oBAOS,MAAM,EAAE;;+BAjIL,OAAO,0BAA0B,EAAE,gBAAgB;oCAH5B,0BAA0B"}