@woosh/meep-engine 2.155.0 → 2.156.0

package/src/engine/physics/narrowphase/refine_ray_hit.js

@@ -1,78 +1,81 @@
-import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
-import { ray_sphere_local, ray_box_local, ray_capsule_local } from "./ray_shapes.js";
-import { refine_ray_concave } from "./refine_ray_concave.js";
-
-/**
- * Sentinel returned by {@link refine_ray_hit} for a shape it has no exact ray
- * test for (composite / arbitrary convex). The caller should keep the
- * broadphase AABB result for that leaf rather than treat it as a miss.
- * Distinct from `Infinity` (a refined miss) and any finite hit distance.
- * @type {number}
- */
-export const RAY_REFINE_UNSUPPORTED = -1;
-
-const lo = new Float64Array(3); // ray origin in shape-local frame
-const ld = new Float64Array(3); // ray direction in shape-local frame
-const ln = new Float64Array(3); // surface normal in shape-local frame
-
-/**
- * Refine a broadphase ray hit against a body's true shape geometry.
- *
- * Transforms the world ray into the shape's local frame once (rotate by the
- * inverse body rotation — a unit direction stays unit, so the hit distance is
- * preserved), runs the matching canonical primitive ({@link ray_shapes}), and
- * rotates the returned local normal back to world. Spheres are
- * rotation-invariant, so they only need the translation.
- *
- * Handles the convex primitives (sphere / box / capsule). Concave shapes
- * (mesh / heightmap) and arbitrary composite convex shapes return
- * {@link RAY_REFINE_UNSUPPORTED} — the concave path is wired in separately, and
- * composites fall back to the broadphase AABB hit (no regression).
- *
- * @param {AbstractShape3D} shape
- * @param {{x:number,y:number,z:number}} position  body world position
- * @param {ArrayLike<number>} rotation  body world rotation quaternion (x,y,z,w)
- * @param {number} ox @param {number} oy @param {number} oz  ray origin (world)
- * @param {number} dx @param {number} dy @param {number} dz  ray dir (world, unit)
- * @param {number} tMax
- * @param {Float64Array|Vector3} outNormal  world surface normal, written on a
- *   finite hit
- * @returns {number} hit distance, `Infinity` on a refined miss, or
- *   {@link RAY_REFINE_UNSUPPORTED} when the shape has no exact ray test here
- */
-export function refine_ray_hit(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
-    if (shape.isSphereShape3D === true) {
-        // Rotation-invariant: translate into the sphere's frame; the local
-        // normal is already the world normal.
-        return ray_sphere_local(outNormal, ox - position.x, oy - position.y, oz - position.z, dx, dy, dz, tMax, shape.radius);
-    }
-
-    if (shape.isBoxShape3D === true || shape.isCapsuleShape3D === true) {
-        const qx = rotation[0], qy = rotation[1], qz = rotation[2], qw = rotation[3];
-        // World → local: rotate by the inverse (conjugate) body rotation.
-        v3_quat3_apply(lo, 0, ox - position.x, oy - position.y, oz - position.z, -qx, -qy, -qz, qw);
-        v3_quat3_apply(ld, 0, dx, dy, dz, -qx, -qy, -qz, qw);
-
-        let t;
-        if (shape.isBoxShape3D === true) {
-            const h = shape.half_extents;
-            t = ray_box_local(ln, lo[0], lo[1], lo[2], ld[0], ld[1], ld[2], tMax, h.x, h.y, h.z);
-        } else {
-            t = ray_capsule_local(ln, lo[0], lo[1], lo[2], ld[0], ld[1], ld[2], tMax, shape.radius, shape.height * 0.5);
-        }
-        if (t === Infinity) return Infinity;
-
-        // Local normal → world: rotate by the body rotation.
-        v3_quat3_apply(outNormal, 0, ln[0], ln[1], ln[2], qx, qy, qz, qw);
-        return t;
-    }
-
-    // Concave (mesh / heightmap): triangle decomposition.
-    if (shape.is_convex === false) {
-        return refine_ray_concave(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal);
-    }
-
-    // Arbitrary composite convex (TransformedShape3D / UnionShape3D / …):
-    // no exact ray test yet — caller falls back to the broadphase AABB hit.
-    return RAY_REFINE_UNSUPPORTED;
-}
+import { box3_raycast } from "../../../core/geom/3d/box/box3_raycast.js";
+import { capsule_raycast } from "../../../core/geom/3d/capsule/capsule_raycast.js";
+import { sphere_raycast } from "../../../core/geom/3d/sphere/sphere_raycast.js";
+import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
+import { v3_quat3_apply_inverse } from "../../../core/geom/vec3/v3_quat3_apply_inverse.js";
+import { refine_ray_concave } from "./refine_ray_concave.js";
+
+/**
+ * Sentinel returned by {@link refine_ray_hit} for a shape it has no exact ray
+ * test for (composite / arbitrary convex). The caller should keep the
+ * broadphase AABB result for that leaf rather than treat it as a miss.
+ * Distinct from `Infinity` (a refined miss) and any finite hit distance.
+ * @type {number}
+ */
+export const RAY_REFINE_UNSUPPORTED = -1;
+
+const lo = new Float64Array(3); // ray origin in shape-local frame
+const ld = new Float64Array(3); // ray direction in shape-local frame
+const ln = new Float64Array(3); // surface normal in shape-local frame
+
+/**
+ * Refine a broadphase ray hit against a body's true shape geometry.
+ *
+ * Transforms the world ray into the shape's local frame once (rotate by the
+ * inverse body rotation — a unit direction stays unit, so the hit distance is
+ * preserved), runs the matching canonical primitive ({@link ray_shapes}), and
+ * rotates the returned local normal back to world. Spheres are
+ * rotation-invariant, so they only need the translation.
+ *
+ * Handles the convex primitives (sphere / box / capsule). Concave shapes
+ * (mesh / heightmap) and arbitrary composite convex shapes return
+ * {@link RAY_REFINE_UNSUPPORTED} — the concave path is wired in separately, and
+ * composites fall back to the broadphase AABB hit (no regression).
+ *
+ * @param {AbstractShape3D} shape
+ * @param {{x:number,y:number,z:number}} position  body world position
+ * @param {ArrayLike<number>} rotation  body world rotation quaternion (x,y,z,w)
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (world)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (world, unit)
+ * @param {number} tMax
+ * @param {Float64Array|Vector3} outNormal  world surface normal, written on a
+ *   finite hit
+ * @returns {number} hit distance, `Infinity` on a refined miss, or
+ *   {@link RAY_REFINE_UNSUPPORTED} when the shape has no exact ray test here
+ */
+export function refine_ray_hit(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
+    if (shape.isSphereShape3D === true) {
+        // Rotation-invariant: translate into the sphere's frame; the local
+        // normal is already the world normal.
+        return sphere_raycast(outNormal, 0, ox - position.x, oy - position.y, oz - position.z, dx, dy, dz, tMax, shape.radius);
+    }
+
+    if (shape.isBoxShape3D === true || shape.isCapsuleShape3D === true) {
+        const qx = rotation[0], qy = rotation[1], qz = rotation[2], qw = rotation[3];
+        // World → local: rotate by the inverse (conjugate) body rotation.
+        v3_quat3_apply_inverse(lo, 0, ox - position.x, oy - position.y, oz - position.z, qx, qy, qz, qw);
+        v3_quat3_apply_inverse(ld, 0, dx, dy, dz, qx, qy, qz, qw);
+
+        let t;
+        if (shape.isBoxShape3D === true) {
+            const h = shape.half_extents;
+            t = box3_raycast(ln, 0, lo[0], lo[1], lo[2], ld[0], ld[1], ld[2], tMax, h.x, h.y, h.z);
+        } else {
+            t = capsule_raycast(ln, 0, lo[0], lo[1], lo[2], ld[0], ld[1], ld[2], tMax, shape.radius, shape.height * 0.5);
+        }
+        if (t === Infinity) return Infinity;
+
+        // Local normal → world: rotate by the body rotation.
+        v3_quat3_apply(outNormal, 0, ln[0], ln[1], ln[2], qx, qy, qz, qw);
+        return t;
+    }
+
+    // Concave (mesh / heightmap): triangle decomposition.
+    if (shape.is_convex === false) {
+        return refine_ray_concave(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal);
+    }
+
+    // Arbitrary composite convex (TransformedShape3D / UnionShape3D / …):
+    // no exact ray test yet — caller falls back to the broadphase AABB hit.
+    return RAY_REFINE_UNSUPPORTED;
+}

package/src/engine/sound/SoundEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoundEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/sound/SoundEngine.js"],"names":[],"mappings":";AAAA;;;;GAIG;AACH;IAkBwB,sBAWd;IAUF,sBAA2B;IAiB/B;;;OAGG;IACH,kBAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,iBAFa,QAAQ,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,SAFa,QAAQ,GAAG,CAAC,CAWxB;CACJ"}
+{"version":3,"file":"SoundEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/sound/SoundEngine.js"],"names":[],"mappings":";AAEA;;;;GAIG;AACH;IAkBwB,sBAWd;IAUF,sBAA2B;IAI3B;;;;OAIG;IACH,OAFU,WAAW,GAAC,IAAI,CAET;IAerB;;;;;;;;;;OAUG;IACH,6CAFa,WAAW,CAQvB;IAED;;;OAGG;IACH,kBAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,iBAFa,QAAQ,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,SAFa,QAAQ,GAAG,CAAC,CAWxB;CACJ;4BA1H2B,wBAAwB"}

package/src/engine/sound/SoundEngine.js

@@ -1,3 +1,5 @@
+import { SopraEngine } from "./sopra/SopraEngine.js";
+
 /**
  *
  * @author Alex Goldring
@@ -46,6 +48,13 @@ class SoundEngine {
         gainNode.connect(compressor);
         compressor.connect(context.destination);
 
+        /**
+         * The sopra (FMOD/Wwise-style) engine, created and owned here once the AssetManager-backed
+         * buffer provider is available (see {@link createSopra}, called from SoundEmitterSystem).
+         * @type {SopraEngine|null}
+         */
+        this.sopra = null;
+
         // master channel
         Object.defineProperties(this, {
             volume: {
@@ -59,6 +68,25 @@ class SoundEngine {
         });
     }
 
+    /**
+     * Create and own the sopra engine, built on this SoundEngine's existing AudioContext + master
+     * destination (never a second context). Wired in by the sound systems, which supply an
+     * AssetManager-backed buffer provider.
+     *
+     * Idempotent: the SopraEngine is a singleton on the SoundEngine, so the first caller creates it and
+     * later callers reuse it (the `bufferProvider` of later calls is ignored). This lets multiple
+     * systems — e.g. the legacy SoundEmitterSystem and the native AudioEmitterSystem — share one engine.
+     * @param {BufferProvider} bufferProvider
+     * @returns {SopraEngine}
+     */
+    createSopra(bufferProvider) {
+        if (this.sopra === null) {
+            this.sopra = new SopraEngine(this.context, this.destination, bufferProvider);
+        }
+
+        return this.sopra;
+    }
+
     /**
      *
      * @return {number}

package/src/engine/sound/dB2Volume.d.ts

@@ -3,5 +3,5 @@
  * @param {number} dB
  * @returns {number}
  */
-declare function dB2Volume(dB: number): number;
+export function dB2Volume(dB: number): number;
 //# sourceMappingURL=dB2Volume.d.ts.map

package/src/engine/sound/dB2Volume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dB2Volume.d.ts","sourceRoot":"","sources":["../../../../src/engine/sound/dB2Volume.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,+BAHW,MAAM,GACJ,MAAM,CAIlB"}
+{"version":3,"file":"dB2Volume.d.ts","sourceRoot":"","sources":["../../../../src/engine/sound/dB2Volume.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,8BAHW,MAAM,GACJ,MAAM,CAIlB"}

package/src/engine/sound/dB2Volume.js

@@ -3,6 +3,6 @@
  * @param {number} dB
  * @returns {number}
  */
-function dB2Volume(dB) {
+export function dB2Volume(dB) {
     return Math.pow(10, 0.05 * dB);
 }

package/src/engine/sound/ecs/SoundController.d.ts

@@ -16,6 +16,10 @@ export class SoundControllerSerializationAdapter extends BinaryClassSerializatio
      */
     deserialize(buffer: BinaryBuffer, value: SoundController): void;
 }
+/**
+ * @deprecated Legacy sound controller — superseded by the native audio path ({@link AudioEmitter} and
+ * the forthcoming `AudioEventTrigger`). Retained for existing callers during the strangler migration.
+ */
 declare class SoundController {
     /**
      *

package/src/engine/sound/ecs/SoundController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoundController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/ecs/SoundController.js"],"names":[],"mappings":";AAkJA;;IACI,8BAAwB;IACxB,gBAAY;IAEZ;;;;OAIG;IACH,uCAFW,eAAe,QAIzB;IAED;;;;OAIG;IACH,yCAFW,eAAe,QAIzB;CACJ;AAnDD;IACI;;;;OAIG;IACH,0BAKC;IAJG,iBAAuB;IAM3B,0BAEC;IAED,cAEC;CACJ;;;;;gDAvI+C,6DAA6D;iBAD5F,uCAAuC;AAGxD;IAEQ;;;OAGG;IACH,QAFU,MAAM,MAAM,CAAC,CAEP;IAChB;;;OAGG;IACH,YAFU,SAAO,IAAI,CAEC;IACtB;;;OAGG;IACH,WAFU,SAAO,IAAI,CAEA;IACrB;;;OAGG;IACH,MAFU,OAAO,CAEA;IACjB;;;OAGG;IACH,QAFU,MAAM,CAED;IACf;;;OAGG;IACH,SAFU,SAAO,IAAI,CAEF;IAGvB;;;;;;;MASC;IAED,0BAyBC;IAxBG,SAAmB;IA0BvB;;;OAGG;IACH,2CAcC;IAED;;;OAGG;IACH,6CAcC;CACJ"}
+{"version":3,"file":"SoundController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/ecs/SoundController.js"],"names":[],"mappings":";AAsJA;;IACI,8BAAwB;IACxB,gBAAY;IAEZ;;;;OAIG;IACH,uCAFW,eAAe,QAIzB;IAED;;;;OAIG;IACH,yCAFW,eAAe,QAIzB;CACJ;AAvDD;;;GAGG;AACH;IACI;;;;OAIG;IACH,0BAKC;IAJG,iBAAuB;IAM3B,0BAEC;IAED,cAEC;CACJ;;;;;gDA3I+C,6DAA6D;iBAD5F,uCAAuC;AAGxD;IAEQ;;;OAGG;IACH,QAFU,MAAM,MAAM,CAAC,CAEP;IAChB;;;OAGG;IACH,YAFU,SAAO,IAAI,CAEC;IACtB;;;OAGG;IACH,WAFU,SAAO,IAAI,CAEA;IACrB;;;OAGG;IACH,MAFU,OAAO,CAEA;IACjB;;;OAGG;IACH,QAFU,MAAM,CAED;IACf;;;OAGG;IACH,SAFU,SAAO,IAAI,CAEF;IAGvB;;;;;;;MASC;IAED,0BAyBC;IAxBG,SAAmB;IA0BvB;;;OAGG;IACH,2CAcC;IAED;;;OAGG;IACH,6CAcC;CACJ"}

package/src/engine/sound/ecs/SoundController.js

@@ -114,6 +114,10 @@ class Rule {
     }
 }
 
+/**
+ * @deprecated Legacy sound controller — superseded by the native audio path ({@link AudioEmitter} and
+ * the forthcoming `AudioEventTrigger`). Retained for existing callers during the strangler migration.
+ */
 class SoundController {
     /**
      *

package/src/engine/sound/ecs/SoundControllerSystem.d.ts

@@ -1,4 +1,9 @@
 export default SoundControllerSystem;
+/**
+ * @deprecated Legacy sound-controller system — superseded by the native audio path
+ * ({@link AudioEmitterSystem} and the forthcoming `AudioEventTrigger`). Retained for existing callers
+ * during the strangler migration.
+ */
 declare class SoundControllerSystem extends System<any, any, any, any, any> {
     constructor();
     dependencies: (typeof SoundController)[];

package/src/engine/sound/ecs/SoundControllerSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoundControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/ecs/SoundControllerSystem.js"],"names":[],"mappings":";AAyBA;IACI,cAUC;IARG,yCAAqC;IAGrC,oEAEC;IAED,gBAAkB;IAGtB;;;;OAIG;IACH,gBAHW,eAAe,UACf,MAAM,QAsDhB;IAED,0CAUC;CACJ;uBA1GsB,qBAAqB;4BAGhB,sBAAsB;6BAFrB,2BAA2B;4CAFZ,oDAAoD"}
+{"version":3,"file":"SoundControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/ecs/SoundControllerSystem.js"],"names":[],"mappings":";AAyBA;;;;GAIG;AACH;IACI,cAUC;IARG,yCAAqC;IAGrC,oEAEC;IAED,gBAAkB;IAGtB;;;;OAIG;IACH,gBAHW,eAAe,UACf,MAAM,QAsDhB;IAED,0CAUC;CACJ;uBA/GsB,qBAAqB;4BAGhB,sBAAsB;6BAFrB,2BAA2B;4CAFZ,oDAAoD"}

package/src/engine/sound/ecs/SoundControllerSystem.js

@@ -23,6 +23,11 @@ function pickTackFromRule(rule) {
     return tracks[index];
 }
 
+/**
+ * @deprecated Legacy sound-controller system — superseded by the native audio path
+ * ({@link AudioEmitterSystem} and the forthcoming `AudioEventTrigger`). Retained for existing callers
+ * during the strangler migration.
+ */
 class SoundControllerSystem extends System {
     constructor() {
         super();

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

@@ -0,0 +1,69 @@
+/**
+ * Native ECS sound component (the user-facing replacement for the legacy `SoundEmitter`). Unlike
+ * `SoundEmitter` — which holds a list of tracks that get *translated* into sopra events — an
+ * `AudioEmitter` OWNS its authored sopra {@link EventDescription} directly (full clip graph: samples /
+ * sequence / random / switch / blend; effects; bus routing; 3D / attenuation; voice config). It is the
+ * ECS-native data container the engine's data model makes possible (no FMOD-style global bank needed).
+ *
+ * Played + spatialised by {@link AudioEmitterSystem}; the entity's {@link Transform} supplies position.
+ */
+export class AudioEmitter {
+    /**
+     * @param {*} json
+     * @returns {AudioEmitter}
+     */
+    static fromJSON(json: any): AudioEmitter;
+    /**
+     * The authored event this emitter plays.
+     * @type {EventDescription}
+     */
+    event: EventDescription;
+    /**
+     * Live volume multiplier applied on top of the event's own gain (carried by the instance gain).
+     * @type {Vector1}
+     */
+    volume: Vector1;
+    /**
+     * Play automatically when the component links to an entity (e.g. looping ambience). A finite event
+     * self-releases when it finishes; a looping event persists until unlink.
+     * @type {boolean}
+     */
+    autoplay: boolean;
+    /**
+     * @param {AudioEmitter} other
+     * @returns {boolean}
+     */
+    equals(other: AudioEmitter): boolean;
+    hash(): number;
+    toJSON(): {
+        event: {
+            label: string;
+            rootClip: {
+                type: string;
+                data: any;
+            };
+            busId: string;
+            gainDb: number;
+            is3D: boolean;
+            panningModel: number;
+            distanceMin: number;
+            distanceMax: number;
+            attenuation: {
+                keys: any[];
+            };
+            maxInstances: number;
+            priority: number;
+            stealMode: number;
+            virtualThresholdDb: number;
+        };
+        volume: number;
+        autoplay: boolean;
+    };
+    fromJSON(json: any): void;
+}
+export namespace AudioEmitter {
+    let typeName: string;
+}
+import { EventDescription } from "../../sopra/definition/EventDescription.js";
+import Vector1 from "../../../../core/geom/Vector1.js";
+//# sourceMappingURL=AudioEmitter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitter.js"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH;IAyDI;;;OAGG;IACH,4BAFa,YAAY,CAMxB;IA/DD;;;OAGG;IACH,OAFU,gBAAgB,CAEK;IAE/B;;;OAGG;IACH,QAFU,OAAO,CAEO;IAExB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAEhB;;;OAGG;IACH,cAHW,YAAY,GACV,OAAO,CAMnB;IAED,eAMC;IAED;;;;;;;;;;;;;;;;;;;;;;;MAMC;IAED,0BAQC;CAWJ;;;;iCA7EgC,4CAA4C;oBAFzD,kCAAkC"}

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

@@ -0,0 +1,83 @@
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import Vector1 from "../../../../core/geom/Vector1.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { EventDescription } from "../../sopra/definition/EventDescription.js";
+
+/**
+ * Native ECS sound component (the user-facing replacement for the legacy `SoundEmitter`). Unlike
+ * `SoundEmitter` — which holds a list of tracks that get *translated* into sopra events — an
+ * `AudioEmitter` OWNS its authored sopra {@link EventDescription} directly (full clip graph: samples /
+ * sequence / random / switch / blend; effects; bus routing; 3D / attenuation; voice config). It is the
+ * ECS-native data container the engine's data model makes possible (no FMOD-style global bank needed).
+ *
+ * Played + spatialised by {@link AudioEmitterSystem}; the entity's {@link Transform} supplies position.
+ */
+export class AudioEmitter {
+
+    /**
+     * The authored event this emitter plays.
+     * @type {EventDescription}
+     */
+    event = new EventDescription();
+
+    /**
+     * Live volume multiplier applied on top of the event's own gain (carried by the instance gain).
+     * @type {Vector1}
+     */
+    volume = new Vector1(1);
+
+    /**
+     * Play automatically when the component links to an entity (e.g. looping ambience). A finite event
+     * self-releases when it finishes; a looping event persists until unlink.
+     * @type {boolean}
+     */
+    autoplay = true;
+
+    /**
+     * @param {AudioEmitter} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.autoplay === other.autoplay
+            && this.volume.getValue() === other.volume.getValue()
+            && this.event.equals(other.event);
+    }
+
+    hash() {
+        return combine_hash(
+            this.event.hash(),
+            this.autoplay ? 1 : 0,
+            computeHashFloat(this.volume.getValue())
+        );
+    }
+
+    toJSON() {
+        return {
+            event: this.event.toJSON(),
+            volume: this.volume.toJSON(),
+            autoplay: this.autoplay
+        };
+    }
+
+    fromJSON(json) {
+        if (json.event !== undefined) {
+            this.event.fromJSON(json.event);
+        }
+        if (json.volume !== undefined) {
+            this.volume.fromJSON(json.volume);
+        }
+        this.autoplay = json.autoplay !== undefined ? json.autoplay : true;
+    }
+
+    /**
+     * @param {*} json
+     * @returns {AudioEmitter}
+     */
+    static fromJSON(json) {
+        const r = new AudioEmitter();
+        r.fromJSON(json);
+        return r;
+    }
+}
+
+AudioEmitter.typeName = "AudioEmitter";

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

@@ -0,0 +1,97 @@
+/**
+ * Drives {@link AudioEmitter} components through the shared sopra engine — the native counterpart to
+ * the legacy `SoundEmitterSystem`. Each emitter owns its {@link EventDescription} directly (no track
+ * translation); the entity's {@link Transform} feeds position; `volume` changes plumb to the instance
+ * gain. 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 —
+ * mutating `autoplay`/`is3D` afterward does nothing without an unlink/relink):
+ * - **Spatially managed** (`autoplay && is3D && looping`): registered with a {@link LiveEmitterSet} and
+ *   left *dormant* until a refresh promotes the nearest in-range emitters up to a global voice budget —
+ *   this is what lets the system carry far more emitters than can sound at once (the 100k-bird case). A
+ *   dormant emitter costs only a BVH leaf; no instance, no nodes, no per-frame work. NOTE: for a crowd
+ *   of content-equal managed events to all sound, their `maxInstances` must be ≥ the live budget — they
+ *   share one sopra polyphony bucket (keyed by event content), so a lower cap gates the budget. Only
+ *   *looping* events are managed: the live set models a persistent source whose phase is reconstructed
+ *   on (re-)promotion — meaningless for a finite one-shot, and a dead one-shot would otherwise keep
+ *   re-promoting and occupying a budget slot — so finite events take the direct path.
+ * - **Direct** (any other `autoplay` event — 2D sounds, or finite 3D one-shots): played immediately on
+ *   link, stopped on unlink. 2D sounds (music, ambience beds) have nothing to cull by distance; a finite
+ *   3D one-shot still spatializes (its instance attenuates by position) and self-releases when it ends.
+ *
+ * Non-autoplay emitters are inert: neither played nor registered, awaiting a future explicit trigger.
+ *
+ * Shares the single {@link SopraEngine} owned by {@link SoundEngine} (created on demand, idempotent),
+ * so it coexists with the legacy `SoundEmitterSystem` during the strangler migration.
+ */
+export class AudioEmitterSystem extends System<any, any, any, any, any> {
+    /**
+     * @param {AssetManager} assetManager
+     * @param {SoundEngine} soundEngine owns the AudioContext + master destination + sopra engine
+     * @param {{budget?:number, liveStickiness?:number, fadeOutSeconds?:number}} [liveEmitterSetOptions]
+     *        forwarded to the {@link LiveEmitterSet} that manages 3D emitters
+     */
+    constructor(assetManager: AssetManager, soundEngine: SoundEngine, liveEmitterSetOptions?: {
+        budget?: number;
+        liveStickiness?: number;
+        fadeOutSeconds?: number;
+    });
+    dependencies: (typeof Transform | typeof AudioEmitter)[];
+    /**
+     * @type {SoundEngine}
+     */
+    soundEngine: SoundEngine;
+    /**
+     * @type {AudioContext}
+     */
+    webAudioContext: AudioContext;
+    /**
+     * @type {AssetManager}
+     */
+    assetManager: AssetManager;
+    /**
+     * The shared sopra engine (idempotent create — reused if the legacy system already made it).
+     * @type {SopraEngine}
+     */
+    sopra: SopraEngine;
+    /**
+     * Spatial lifecycle for 3D ("managed") emitters: BVH cull → promote nearest-in-range up to the
+     * budget, demote the rest. 2D emitters bypass this and play directly.
+     * @type {LiveEmitterSet}
+     */
+    liveSet: LiveEmitterSet;
+    /**
+     * Per-entity records: { emitter, transform, managed, instance, onVolume }. 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[]}
+     */
+    data: object[];
+    /**
+     * @param {AudioEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(emitter: AudioEmitter, transform: Transform, entity: number): void;
+    /**
+     * @param {AudioEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(emitter: AudioEmitter, transform: Transform, entity: number): void;
+    /**
+     * The currently-playing instance for an entity, or null. For a managed (3D) emitter this is the live
+     * instance only while it is promoted (null while dormant or out of range); for a direct (2D) emitter
+     * it is the instance held since link.
+     * @param {number} entity
+     * @returns {EventInstance|null}
+     */
+    instanceFor(entity: number): EventInstance | null;
+    update(timeDelta: any): void;
+    #private;
+}
+import { System } from "../../../ecs/System.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { AudioEmitter } from "./AudioEmitter.js";
+import { LiveEmitterSet } from "./LiveEmitterSet.js";
+//# sourceMappingURL=AudioEmitterSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/audio/AudioEmitterSystem.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IACI;;;;;OAKG;IACH,0FAHW;QAAC,MAAM,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAC;QAAC,cAAc,CAAC,EAAC,MAAM,CAAA;KAAC,EAiD1E;IA3CG,yDAA6C;IAE7C;;OAEG;IACH,yBAA8B;IAE9B;;OAEG;IACH,iBAFU,YAAY,CAEoB;IAE1C;;OAEG;IACH,2BAAgC;IAQhC;;;OAGG;IACH,mBAAkF;IAElF;;;;OAIG;IACH,SAFU,cAAc,CAE4C;IAEpE;;;;;OAKG;IACH,MAFU,MAAM,EAAE,CAEJ;IAGlB;;;;OAIG;IACH,cAJW,YAAY,aACZ,SAAS,UACT,MAAM,QAuBhB;IAED;;;;OAIG;IACH,gBAJW,YAAY,aACZ,SAAS,UACT,MAAM,QAmBhB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,gBAAc,IAAI,CAe9B;IAuCD,6BAiCC;;CACJ;uBA3OsB,wBAAwB;0BACrB,qCAAqC;6BAKlC,mBAAmB;+BACjB,qBAAqB"}