@woosh/meep-engine 2.155.0 → 2.157.0

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"}

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

@@ -0,0 +1,238 @@
+import { GameAssetType } from "../../../asset/GameAssetType.js";
+import { SoundAssetLoader } from "../../../asset/loaders/SoundAssetLoader.js";
+import { System } from "../../../ecs/System.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { AssetManagerBufferProvider } from "../../sopra/asset/AssetManagerBufferProvider.js";
+import { EventInstanceState } from "../../sopra/runtime/EventInstance.js";
+import { volume2dB } from "../../volume2dB.js";
+import SoundListener from "../SoundListener.js";
+import { AudioEmitter } from "./AudioEmitter.js";
+import { LiveEmitterSet } from "./LiveEmitterSet.js";
+
+/**
+ * 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 {
+    /**
+     * @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, soundEngine, liveEmitterSetOptions = {}) {
+        super();
+
+        this.dependencies = [AudioEmitter, Transform];
+
+        /**
+         * @type {SoundEngine}
+         */
+        this.soundEngine = soundEngine;
+
+        /**
+         * @type {AudioContext}
+         */
+        this.webAudioContext = soundEngine.context;
+
+        /**
+         * @type {AssetManager}
+         */
+        this.assetManager = assetManager;
+
+        // Self-sufficient: register the Sound asset loader if nothing has yet (so this system works
+        // standalone, without the legacy SoundEmitterSystem). Guarded against double-registration (D7).
+        if (!assetManager.hasLoaderForType(GameAssetType.Sound)) {
+            assetManager.registerLoader(GameAssetType.Sound, new SoundAssetLoader(soundEngine.context));
+        }
+
+        /**
+         * The shared sopra engine (idempotent create — reused if the legacy system already made it).
+         * @type {SopraEngine}
+         */
+        this.sopra = soundEngine.createSopra(new AssetManagerBufferProvider(assetManager));
+
+        /**
+         * 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}
+         */
+        this.liveSet = new LiveEmitterSet(this.sopra, liveEmitterSetOptions);
+
+        /**
+         * 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[]}
+         */
+        this.data = [];
+    }
+
+    /**
+     * @param {AudioEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(emitter, transform, entity) {
+        // Spatially managed = a persistent (looping) 3D autoplay source. Finite 3D one-shots and all 2D
+        // sounds take the direct path; non-autoplay emitters are inert. Routing is fixed at link. See the
+        // class doc.
+        const managed = emitter.autoplay && emitter.event.is3D && emitter.event.rootClip.loops();
+
+        const record = { emitter, transform, managed, instance: null, onVolume: null };
+
+        if (managed) {
+            this.liveSet.add(entity, emitter.event, transform.position, volume2dB(emitter.volume.getValue()));
+            record.onVolume = () => this.liveSet.setGainDb(entity, volume2dB(emitter.volume.getValue()));
+        } else {
+            if (emitter.autoplay) {
+                record.instance = this.#play(emitter, transform);
+            }
+            record.onVolume = () => this.#applyVolume(record);
+        }
+
+        emitter.volume.onChanged.add(record.onVolume);
+
+        this.data[entity] = record;
+    }
+
+    /**
+     * @param {AudioEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(emitter, transform, entity) {
+        const record = this.data[entity];
+
+        if (record === undefined) {
+            return;
+        }
+
+        delete this.data[entity];
+
+        emitter.volume.onChanged.remove(record.onVolume);
+
+        if (record.managed) {
+            this.liveSet.remove(entity); // demotes (hard cut) if live, then unregisters
+        } else if (record.instance !== null) {
+            record.instance.stop();
+            record.instance = null;
+        }
+    }
+
+    /**
+     * 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) {
+        const record = this.data[entity];
+
+        if (record === undefined) {
+            return null;
+        }
+
+        if (record.managed) {
+            const instance = this.liveSet.instanceOf(entity);
+            return instance === undefined ? null : instance;
+        }
+
+        return record.instance;
+    }
+
+    /**
+     * @param {AudioEmitter} emitter
+     * @param {Transform} transform
+     * @returns {EventInstance|null}
+     */
+    #play(emitter, transform) {
+        const event = emitter.event;
+
+        // A looping event is a persistent source (plays until unlink); a finite event is a one-shot that
+        // self-releases when it finishes. oneShot ALSO arms the max-lifetime backstop, so marking a loop
+        // oneShot would wrongly kill it after maxLifetimeSeconds.
+        const oneShot = !event.rootClip.loops();
+
+        const instance = this.sopra.playEvent(event, {
+            busId: event.busId,
+            position: transform.position, // shared Vector3 — tracks the entity as it moves
+            oneShot
+        });
+
+        if (instance !== null) {
+            instance.setGainDb(volume2dB(emitter.volume.getValue()));
+        }
+
+        return instance;
+    }
+
+    /**
+     * @param {object} record
+     */
+    #applyVolume(record) {
+        const instance = record.instance;
+
+        if (instance !== null && instance.state !== EventInstanceState.Stopped) {
+            instance.setGainDb(volume2dB(record.emitter.volume.getValue()));
+        }
+    }
+
+    update(timeDelta) {
+        const sopra = this.sopra;
+
+        const ecd = this.entityManager.dataset;
+
+        let listenerPosition = null;
+
+        if (ecd !== null) {
+            const soundListener = ecd.getAnyComponent(SoundListener);
+
+            if (soundListener.entity !== -1) {
+                // A SoundListener entity is expected to also carry a Transform (SoundListenerSystem
+                // depends on both). Tolerate a misconfigured one rather than throwing every frame and
+                // freezing all audio: a missing Transform is treated as "no usable listener" (below).
+                const listenerTransform = ecd.getComponent(soundListener.entity, Transform);
+
+                if (listenerTransform !== undefined) {
+                    listenerPosition = listenerTransform.position;
+                    sopra.setListener(listenerPosition);
+                }
+            }
+        }
+
+        // Promote/demote the spatial live set (throttled internally). Refresh BEFORE the tick so a
+        // freshly-promoted instance spatializes on the same frame. With no usable listener the live set
+        // is not refreshed: never-promoted managed emitters stay dormant, while any already-live ones
+        // keep playing against the last known listener pose until a listener returns. The direct (2D)
+        // instances and the sopra tick run regardless.
+        if (listenerPosition !== null) {
+            this.liveSet.refresh(listenerPosition);
+        }
+
+        sopra.update(this.webAudioContext.currentTime);
+    }
+}