@woosh/meep-engine 3.46.0 → 3.49.0

package/src/engine/physics/cloth/solver/constraint/cloth_contact_row.js

@@ -22,6 +22,7 @@ import {
     CVA_H_ZZ,
     CVA_TRUST
 } from "../cloth_vertex_accumulator.js";
+import { CLOTH_CONTACT_GAMMA, CLOTH_CONTACT_RAMP_RATIO } from "../cloth_solver_constants.js";
 
 /**
  * # Contact — the collision row and its friction row, which are one contact
@@ -80,6 +81,21 @@ import {
  * never act at all. The current force is already computed, already
  * non-negative, and makes a cloth land on a slope and stay there at 1×1.
  *
+ * ## The normal penalty ramps in the contact's own units
+ *
+ * `k ← min(k + ratio·k_max·|C|/offset, k_max)`, `offset = thickness + inflation`:
+ * the penalty gains {@link CLOTH_CONTACT_RAMP_RATIO} of its band per contact
+ * offset of violation per iteration, rather than `β·|C|` newtons per metre.
+ * A contact against a **sweeping** collider — a thigh into a skirt — has to
+ * produce an arresting force within the iteration budget, and a ramp in N/m²
+ * that was gentle on a landing sheet was, on a 20 g particle at two substeps,
+ * 0.003 of the band per offset: the row sat at the floor while its multiplier
+ * was rebuilt from a quarter every substep, and the limb showed through. The
+ * ratio keeps the measured shape — a grazing contact ramps gently, a real
+ * interpenetration is at the ceiling within an iteration — and it keeps it
+ * for every mass, substep count and thickness. `β` still ramps friction.
+ * `MEASUREMENTS.md` §67.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -329,12 +345,14 @@ export function cloth_contact_accumulate(accumulator, state, particle, table) {
  *
  * @param {ClothState} state
  * @param {number} alpha
- * @param {number} gamma
+ * @param {number} gamma the multiplier's decay, with `alpha`
  * @param {number} k_min_ratio
  * @param {number} k_max_ratio
  * @param {number} inverse_h_squared
+ * @param {number} [penalty_gamma] the contact's own decay of both penalties per
+ *   substep — {@link CLOTH_CONTACT_GAMMA}, and why a contact has one
  */
-export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared) {
+export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared, penalty_gamma = CLOTH_CONTACT_GAMMA) {
     const particle_count = state.particle_count;
 
     const collider = state.contact_collider;
@@ -374,8 +392,11 @@ export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max
             lambda[slot] *= decay;
             friction_lambda[slot] *= decay;
 
-            penalty[slot] = clamp(penalty[slot] * gamma, lo, hi);
-            friction_penalty[slot] = clamp(friction_penalty[slot] * gamma, lo, hi);
+            // Both penalties decay by the contact's own `penalty_gamma`, the multipliers above by
+            // `α·γ`: a quiet row sinks back to the floor while its multiplier carries the load, and a
+            // violated one re-climbs within an iteration (the module docblock).
+            penalty[slot] = clamp(penalty[slot] * penalty_gamma, lo, hi);
+            friction_penalty[slot] = clamp(friction_penalty[slot] * penalty_gamma, lo, hi);
         }
     }
 }
@@ -392,11 +413,13 @@ export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max
  *
  * @param {ClothState} state
  * @param {Float32Array|Float64Array} table
- * @param {number} beta
+ * @param {number} beta the friction row's ramp, N/m²
  * @param {number} k_max_ratio
  * @param {number} inverse_h_squared
+ * @param {number} [ramp_ratio] the normal row's ramp, as the fraction of the
+ *   band gained per contact offset of violation per iteration
  */
-export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inverse_h_squared) {
+export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inverse_h_squared, ramp_ratio = CLOTH_CONTACT_RAMP_RATIO) {
     const particle_count = state.particle_count;
 
     const collider = state.contact_collider;
@@ -446,7 +469,9 @@ export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inver
 
             const distance = NORMAL[3];
 
-            const c = radius + table[r + CCR_INFLATION] - distance;
+            const offset = radius + table[r + CCR_INFLATION];
+
+            const c = offset - distance;
 
             const k = penalty[slot];
 
@@ -456,7 +481,10 @@ export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inver
 
             lambda[slot] = normal_force;
 
-            const ramped = k + beta * Math.abs(c);
+            // The band per offset of violation, whether or not the row is
+            // active (the module docblock); a zero offset divides to
+            // `Infinity` or `NaN`, and either comparison below lands on `k_max`.
+            const ramped = k + ramp_ratio * k_max * Math.abs(c) / offset;
 
             penalty[slot] = ramped < k_max ? ramped : k_max;
 

package/src/engine/physics/cloth/solver/constraint/cloth_self_row.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_self_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_self_row.js"],"names":[],"mappings":"AAsEA;;;;;;;;;;GAUG;AACH,4EAJW,MAAM,GAEJ,MAAM,CA4FlB;AAED;;;;;;GAMG;AACH,mDAJW,YAAY,+BAEZ,MAAM,QAyBhB;AA/LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;;;GAKG;AACH,iCAFU,MAAM,CAEuB"}
+{"version":3,"file":"cloth_self_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_self_row.js"],"names":[],"mappings":"AAsEA;;;;;;;;;;GAUG;AACH,4EAJW,MAAM,GAEJ,MAAM,CA8FlB;AAED;;;;;;GAMG;AACH,mDAJW,YAAY,+BAEZ,MAAM,QAyBhB;AAjMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;;;GAKG;AACH,iCAFU,MAAM,CAEuB"}

package/src/engine/physics/cloth/solver/constraint/cloth_self_row.js

@@ -94,8 +94,7 @@ export function cloth_self_accumulate_scratch(state, stiffness) {
 
     const pair = state.self_pair;
     const position = state.position;
-
-    const radius = state.self_radius * 2;
+    const self_radius = state.self_radius;
 
     let active = 0;
 
@@ -103,6 +102,9 @@ export function cloth_self_accumulate_scratch(state, stiffness) {
         const i = pair[p * 2];
         const j = pair[p * 2 + 1];
 
+        // `r_i + r_j`, each particle's own (`ClothState#self_radius`)
+        const radius = self_radius[i] + self_radius[j];
+
         const a = i * 3;
         const b = j * 3;
 

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#432@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#445@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#432@#clear_field"(fluid: FluidComponent): void;
+    static "__#445@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#432@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#445@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#432@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#445@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"AudioEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitter.js"],"names":[],"mappings":"AAUA;;;;;;;;GAQG;AACH;IAgII;;;OAGG;IACH,4BAFa,YAAY,CAMxB;IAtID;;;;;;;;;;;;OAYG;IACH,OAFU,gBAAgB,CAEK;IAE/B;;;OAGG;IACH,QAFU,OAAO,CAEO;IAExB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;OAKG;IACH,cAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,aAFU,mBAAmB,CAEW;IAExC;;;;;;;;;;;;;;;OAeG;IACH,aAFU;QAAC,KAAK,EAAE,OAAO,YAAY,CAAC,CAAA;KAAC,CAIrC;IAEF;;;OAGG;IACH,cAHW,YAAY,GACV,OAAO,CASnB;IAED,eAaC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MASC;IAED,0BAaC;CAWJ;;;;iCAtJgC,4CAA4C;oBAHzD,kCAAkC;oCAElB,oDAAoD;mBAHrE,0CAA0C"}
+{"version":3,"file":"AudioEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitter.js"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AACH;IA2JI;;;OAGG;IACH,4BAFa,YAAY,CAMxB;IAjKD;;;;;;;;;;;;;OAaG;IACH,OAFU,gBAAgB,CAEK;IAE/B;;;OAGG;IACH,QAFU,OAAO,CAEO;IAExB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;OAKG;IACH,cAFU,MAAM,CAEqB;IAErC;;;;;OAKG;IACH,aAFU,mBAAmB,CAEW;IAExC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,0BAFU,oBAAoB,CAEe;IAE7C;;;;;;;;;;;;;;;OAeG;IACH,aAFU;QAAC,KAAK,EAAE,OAAO,YAAY,CAAC,CAAA;KAAC,CAIrC;IAEF;;;OAGG;IACH,cAHW,YAAY,GACV,OAAO,CASnB;IAED,eAaC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MASC;IAED,0BAaC;CAWJ;;;;iCAlLgC,4CAA4C;oBAHzD,kCAAkC;oCAElB,oDAAoD;qCAEnD,6CAA6C;mBAL/D,0CAA0C"}

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,7 +1,8 @@
 /**
  * Drives {@link AudioEmitter} components through the shared sopra engine. Each emitter owns its
  * {@link EventDescription} directly (no track translation); the entity's {@link Transform64} feeds
- * position; `volume` changes plumb to the instance gain. Each frame it forwards the listener pose,
+ * position; `volume` changes plumb to the instance gain, and `effectOverrides` to the instance's effect
+ * parameters — both put onto every instance the emitter gets. Each frame it forwards the listener pose,
  * refreshes the spatial live set, and ticks sopra.
  *
  * **Two play paths**, chosen once at {@link link} (routing is fixed for the lifetime of the link —
@@ -50,7 +51,7 @@ export class AudioEmitterSystem extends System<any> {
      */
     acousticLive: EventInstance[];
     /**
-     * Per-entity records: { emitter, transform, managed, instance, onVolume }. For a managed (3D)
+     * Per-entity records: { emitter, transform, managed, instance, onVolume, effectOverrides, onEffectOverride, ... }. For a managed (3D)
      * emitter the playing instance lives in {@link liveSet} (record.instance stays null); for a
      * direct (2D) emitter it is held here.
      * @type {object[]}
@@ -112,6 +113,15 @@ export class AudioEmitterSystem extends System<any> {
      * @returns {EventInstance|null}
      */
     instanceFor(entity: number): EventInstance | null;
+    /**
+     * @param {EntityComponentDataset} dataset
+     */
+    handleDatasetDetached(dataset: EntityComponentDataset): void;
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    shutdown(entityManager: EntityManager): Promise<void>;
     update(timeDelta: any): void;
     #private;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"AudioEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSystem.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAgCI;;;;;OAKG;IACH,0FAHW;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAA;KAAC,qBA+C1E;IAjFD,2DAA2C;IAE3C;;;;;OAKG;IACH,iBAFU,kBAAkB,CAEA;IAE5B;;;OAGG;IACH,cAFU,eAAe,CAEP;IAElB;;;;;OAKG;IACH,MAFU,MAAM,EAAE,CAER;IAEV;;;;OAIG;IACH,aAFU,sBAAoB,IAAI,CAEf;IAWf;;;;;OAKG;IACH,aAFU,oBAAkB,IAAI,CAEF;IAE9B;;OAEG;IACH,yBAA8B;IAE9B;;OAEG;IACH,iBAFU,YAAY,CAEoB;IAE1C;;OAEG;IACH,2BAAgC;IAQhC;;;OAGG;IACH,mBAAkF;IAElF;;;;OAIG;IACH,SAFU,cAAc,CAE4C;IAGxE;;;;OAIG;IACH,cAJW,YAAY,aACZ,WAAW,UACX,MAAM,QA4ChB;IAED;;;;OAIG;IACH,gBAJW,YAAY,aACZ,WAAW,UACX,MAAM,QA+BhB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,gBAAc,IAAI,CAe9B;IAqDD,6BAoFC;;CACJ;uBAvXsB,wBAAwB;4BAGnB,uCAAuC;6BAKtC,mBAAmB;+BACjB,qBAAqB"}
+{"version":3,"file":"AudioEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSystem.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAgCI;;;;;OAKG;IACH,0FAHW;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAA;KAAC,qBA+C1E;IAjFD,2DAA2C;IAE3C;;;;;OAKG;IACH,iBAFU,kBAAkB,CAEA;IAE5B;;;OAGG;IACH,cAFU,eAAe,CAEP;IAElB;;;;;OAKG;IACH,MAFU,MAAM,EAAE,CAER;IAEV;;;;OAIG;IACH,aAFU,sBAAoB,IAAI,CAEf;IAWf;;;;;OAKG;IACH,aAFU,oBAAkB,IAAI,CAEF;IAE9B;;OAEG;IACH,yBAA8B;IAE9B;;OAEG;IACH,iBAFU,YAAY,CAEoB;IAE1C;;OAEG;IACH,2BAAgC;IAQhC;;;OAGG;IACH,mBAAkF;IAElF;;;;OAIG;IACH,SAFU,cAAc,CAE4C;IAGxE;;;;OAIG;IACH,cAJW,YAAY,aACZ,WAAW,UACX,MAAM,QAyEhB;IAED;;;;OAIG;IACH,gBAJW,YAAY,aACZ,WAAW,UACX,MAAM,QAkChB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,gBAAc,IAAI,CAe9B;IAoJD;;OAEG;IACH,6DAKC;IAED;;;OAGG;IACH,wCAFa,QAAQ,IAAI,CAAC,CAKzB;IAmBD,6BAoFC;;CACJ;uBA3hBsB,wBAAwB;4BAGnB,uCAAuC;6BAKtC,mBAAmB;+BACjB,qBAAqB"}