@woosh/meep-engine 3.45.0 → 3.47.0

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,CAkBlB;IAED,0BAkBC;IAED;;;;;;;;;;;;;;;;;;;MAgBC;IAED;;;;;;;;;;;;;;aAmCC;CACJ;;;;gCA7PY,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"}

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

@@ -1,14 +1,21 @@
-import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+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,21 +207,39 @@ export class EventDescription {
      * @returns {number}
      */
     hash() {
-        return combine_hash(
-            computeStringHash(this.label),
-            computeStringHash(this.busId),
-            computeHashFloat(this.gainDb),
-            this.is3D ? 1 : 0,
-            this.panningModel,
-            computeHashFloat(this.distanceMin),
-            computeHashFloat(this.distanceMax),
-            this.maxInstances,
-            computeHashFloat(this.priority),
-            this.stealMode,
-            computeHashFloat(this.virtualThresholdDb),
+        let h = hash_mix3(
+            hash_mix3(
+                hash_mix3(
+                    hash_mix3(
+                        hash_mix3(
+                            hash_mix3(
+                                computeStringHash(this.label),
+                                computeStringHash(this.busId),
+                                computeHashFloat(this.gainDb)
+                            ),
+                            this.is3D ? 1 : 0,
+                            this.panningModel
+                        ),
+                        computeHashFloat(this.distanceMin),
+                        computeHashFloat(this.distanceMax)
+                    ),
+                    this.maxInstances,
+                    computeHashFloat(this.priority)
+                ),
+                this.stealMode,
+                computeHashFloat(this.virtualThresholdDb)
+            ),
             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() {
@@ -203,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;
     }
@@ -221,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)
         };
     }
 
@@ -238,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);
@@ -260,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/MixerSnapshot.js

@@ -1,4 +1,4 @@
-import { combine_hash } from "../../../../core/collection/array/combine_hash.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";
 
@@ -57,7 +57,7 @@ export class MixerSnapshot {
         let h = computeStringHash(this.id);
 
         for (let i = 0; i < this.buses.length; i++) {
-            h = combine_hash(h, computeStringHash(this.buses[i].busId), computeHashFloat(this.buses[i].gainDb));
+            h = hash_mix3(h, computeStringHash(this.buses[i].busId), computeHashFloat(this.buses[i].gainDb));
         }
 
         return h;

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

@@ -1 +1 @@
-{"version":3,"file":"ParameterDefinition.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/ParameterDefinition.js"],"names":[],"mappings":";;;6BAMU,MAAM;;;;;AAOhB;;;GAGG;AACH;IA2BI;;;;;OAKG;IACH,kBAJW,MAAM,sCACN;QAAC,GAAG,CAAC,EAAC,MAAM,CAAC;QAAC,GAAG,CAAC,EAAC,MAAM,CAAC;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,KAAK,CAAC,EAAC,cAAc,GAAC,MAAM,CAAA;KAAC,GAC5E,mBAAmB,CAY/B;IAzCD;;OAEG;IACH,MAFU,MAAM,CAEN;IAEV;;OAEG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,OAFU,cAAc,GAAC,MAAM,CAED;IAoB9B;;;;OAIG;IACH,cAHW,mBAAmB,GACjB,OAAO,CAQnB;IAED,eAQC;IAED,6BAUC;IAED;;;;;;MAQC;IAED;;;;;;aAMC;CACJ"}
+{"version":3,"file":"ParameterDefinition.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/definition/ParameterDefinition.js"],"names":[],"mappings":";;;6BAMU,MAAM;;;;;AAOhB;;;GAGG;AACH;IA2BI;;;;;OAKG;IACH,kBAJW,MAAM,sCACN;QAAC,GAAG,CAAC,EAAC,MAAM,CAAC;QAAC,GAAG,CAAC,EAAC,MAAM,CAAC;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,KAAK,CAAC,EAAC,cAAc,GAAC,MAAM,CAAA;KAAC,GAC5E,mBAAmB,CAY/B;IAzCD;;OAEG;IACH,MAFU,MAAM,CAEN;IAEV;;OAEG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,OAFU,cAAc,GAAC,MAAM,CAED;IAoB9B;;;;OAIG;IACH,cAHW,mBAAmB,GACjB,OAAO,CAQnB;IAED,eAUC;IAED,6BAUC;IAED;;;;;;MAQC;IAED;;;;;;aAMC;CACJ"}

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

@@ -1,4 +1,4 @@
-import { combine_hash } from "../../../../core/collection/array/combine_hash.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";
 
@@ -74,10 +74,12 @@ export class ParameterDefinition {
     }
 
     hash() {
-        return combine_hash(
-            computeStringHash(this.name),
-            computeHashFloat(this.min),
-            computeHashFloat(this.max),
+        return hash_mix3(
+            hash_mix3(
+                computeStringHash(this.name),
+                computeHashFloat(this.min),
+                computeHashFloat(this.max)
+            ),
             computeHashFloat(this.defaultValue),
             this.scope
         );

package/src/engine/sound/sopra/definition/clip/AbstractAudioClip.js

@@ -1,4 +1,4 @@
-import { combine_hash } from "../../../../../core/collection/array/combine_hash.js";
+import { hash_mix2 } from "../../../../../core/math/hash/hash_mix2.js";
 import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
 
 /**
@@ -57,7 +57,7 @@ export class AbstractAudioClip {
      * @returns {number}
      */
     hash() {
-        return combine_hash(
+        return hash_mix2(
             computeHashFloat(this.gain),
             computeHashFloat(this.pitch)
         );

package/src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BlendContainerAudioClip.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.js"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH;IAqBI;;;;OAIG;IACH,uBAJW,mBAAmB,wCACnB;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,MAAM,CAAC,EAAC,cAAc,EAAE,CAAA;KAAC,GACjE,uBAAuB,CAWnC;IAjCD;;;OAGG;IACH,WAFU,MAAM,CAED;IAEf;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,QAFU,cAAc,EAAE,CAEd;IAkCZ;;;;;;;;;MA+BC;IAED;;;OAGG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAkBnB;IAqBD,iCAaC;IAED;;;;;;;;;;;;MASC;IAED;;;;;;;aAWC;;CACJ;;;;mCAjLkC,yBAAyB;+BAF7B,+CAA+C"}
+{"version":3,"file":"BlendContainerAudioClip.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IAqBI;;;;OAIG;IACH,uBAJW,mBAAmB,wCACnB;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,MAAM,CAAC,EAAC,cAAc,EAAE,CAAA;KAAC,GACjE,uBAAuB,CAWnC;IAjCD;;;OAGG;IACH,WAFU,MAAM,CAED;IAEf;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,QAFU,cAAc,EAAE,CAEd;IAkCZ;;;;;;;;;MA+BC;IAED;;;OAGG;IACH,cAHW,uBAAuB,GACrB,OAAO,CAkBnB;IAqBD,iCAaC;IAED;;;;;;;;;;;;MASC;IAED;;;;;;;aAWC;;CACJ;;;;mCAjLkC,yBAAyB;+BAF7B,+CAA+C"}

package/src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.js

@@ -1,4 +1,5 @@
-import { combine_hash } from "../../../../../core/collection/array/combine_hash.js";
+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";
@@ -127,7 +128,7 @@ export class BlendContainerAudioClip extends ContainerAudioClip {
         // super.hash() already folds gain/pitch + children; only this class's own fields go on top.
         // `blends` MUST be folded here — `equals` compares the curves element-wise, so leaving them out
         // made two containers differing only in their blend curves compare unequal yet hash identically.
-        let h = combine_hash(
+        let h = hash_mix3(
             super.hash(),
             computeStringHash(this.parameter),
             computeHashFloat(this.defaultValue)
@@ -136,7 +137,7 @@ export class BlendContainerAudioClip extends ContainerAudioClip {
         const blends = this.blends;
 
         for (let i = 0; i < blends.length; i++) {
-            h = combine_hash(h, blends[i].hash());
+            h = hash_mix2(h, blends[i].hash());
         }
 
         return h;

package/src/engine/sound/sopra/definition/clip/ContainerAudioClip.js

@@ -1,5 +1,5 @@
 import { assert } from "../../../../../core/assert.js";
-import { combine_hash } from "../../../../../core/collection/array/combine_hash.js";
+import { hash_mix2 } from "../../../../../core/math/hash/hash_mix2.js";
 import { AbstractAudioClip } from "./AbstractAudioClip.js";
 
 /**
@@ -120,7 +120,7 @@ export class ContainerAudioClip extends AbstractAudioClip {
         const children = this.children;
 
         for (let i = 0; i < children.length; i++) {
-            h = combine_hash(h, children[i].hash());
+            h = hash_mix2(h, children[i].hash());
         }
 
         return h;

package/src/engine/sound/sopra/definition/clip/RandomContainerAudioClip.js

@@ -1,4 +1,4 @@
-import { combine_hash } from "../../../../../core/collection/array/combine_hash.js";
+import { hash_mix2 } from "../../../../../core/math/hash/hash_mix2.js";
 import { weightedRandomFromArray } from "../../../../../core/collection/array/weightedRandomFromArray.js";
 import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
 import { ContainerAudioClip } from "./ContainerAudioClip.js";
@@ -126,11 +126,11 @@ export class RandomContainerAudioClip extends ContainerAudioClip {
 
     hash() {
         // super.hash() already folds gain/pitch + children; only this class's own fields go on top
-        let h = combine_hash(super.hash(), this.avoid_repeating_last);
+        let h = hash_mix2(super.hash(), this.avoid_repeating_last);
 
         const weights = this.weights;
         for (let i = 0; i < weights.length; i++) {
-            h = combine_hash(h, computeHashFloat(weights[i]));
+            h = hash_mix2(h, computeHashFloat(weights[i]));
         }
 
         return h;