@woosh/meep-engine 3.3.0 → 3.4.0

package/src/engine/sound/ecs/trigger/AudioEventTrigger.d.ts

@@ -0,0 +1,143 @@
+/**
+ * One trigger rule: "when this entity receives `startEvent`, play `event`; when it receives
+ * `stopEvent`, stop what this rule started".
+ *
+ * The legacy `SoundController.Rule` carried `tracks[] / loop / volume / channel` alongside its event
+ * names, and its system did the picking and the routing at trigger time. Here all four collapse into
+ * the {@link EventDescription} itself — a random pick is a `RandomContainerAudioClip`, looping is the
+ * clip's own loop flag, volume is `gainDb`, and the channel is `busId`. That is the whole point of the
+ * native model: what plays is authored data, not a rule the runtime re-interprets on every trigger.
+ */
+export class AudioEventTriggerRule {
+    /**
+     * @param {string} startEvent
+     * @param {EventDescription} event
+     * @param {string|null} [stopEvent]
+     * @returns {AudioEventTriggerRule}
+     */
+    static from(startEvent: string, event: EventDescription, stopEvent?: string | null): AudioEventTriggerRule;
+    /**
+     * @param {*} json
+     * @returns {AudioEventTriggerRule}
+     */
+    static fromJSON(json: any): AudioEventTriggerRule;
+    /**
+     * Entity event name that starts this rule's event. Required — a rule with nothing to start does
+     * nothing at all.
+     * @type {string}
+     */
+    startEvent: string;
+    /**
+     * Entity event name that stops whatever this rule started, or null for a fire-and-forget rule
+     * (a one-shot ends on its own; a looping event then lives until the component unlinks).
+     * @type {string|null}
+     */
+    stopEvent: string | null;
+    /**
+     * The authored event this rule plays. Same data an {@link AudioEmitter} would hold — the difference
+     * is only in what makes it sound: linking, versus receiving an entity event.
+     * @type {EventDescription}
+     */
+    event: EventDescription;
+    /**
+     * @param {AudioEventTriggerRule} other
+     * @returns {boolean}
+     */
+    equals(other: AudioEventTriggerRule): boolean;
+    hash(): number;
+    toJSON(): {
+        startEvent: string;
+        stopEvent: string;
+        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;
+        };
+    };
+    fromJSON(json: any): void;
+}
+/**
+ * Plays authored sopra events in response to entity events — the native replacement for the legacy
+ * `SoundController`, whose system wrote `SoundTrack`s into the entity's `SoundEmitter` and so could not
+ * outlive it.
+ *
+ * Where an {@link AudioEmitter} sounds because it was linked, an `AudioEventTrigger` sounds because the
+ * entity received an event: "unit took damage" → a hurt sound. Driven by {@link AudioEventTriggerSystem};
+ * the entity's {@link Transform} supplies position, exactly as for an emitter.
+ */
+export class AudioEventTrigger {
+    /**
+     * @param {AudioEventTriggerRule[]} rules
+     * @returns {AudioEventTrigger}
+     */
+    static from(rules: AudioEventTriggerRule[]): AudioEventTrigger;
+    /**
+     * @param {*} json
+     * @returns {AudioEventTrigger}
+     */
+    static fromJSON(json: any): AudioEventTrigger;
+    /**
+     * Authored rules, evaluated independently — several may listen to the same event, and each owns the
+     * instances it started.
+     *
+     * Read once when the component links: the system registers one entity-event listener per rule then,
+     * so mutating this array on a linked component has no effect until it is re-linked (remove and
+     * re-add the component), which mirrors {@link AudioEmitter.event}.
+     *
+     * @type {AudioEventTriggerRule[]}
+     */
+    rules: AudioEventTriggerRule[];
+    /**
+     * @param {AudioEventTrigger} other
+     * @returns {boolean}
+     */
+    equals(other: AudioEventTrigger): boolean;
+    hash(): number;
+    toJSON(): {
+        rules: {
+            startEvent: string;
+            stopEvent: string;
+            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;
+            };
+        }[];
+    };
+    fromJSON(json: any): void;
+}
+export namespace AudioEventTrigger {
+    let typeName: string;
+}
+import { EventDescription } from "../../sopra/definition/EventDescription.js";
+//# sourceMappingURL=AudioEventTrigger.d.ts.map

package/src/engine/sound/ecs/trigger/AudioEventTrigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEventTrigger.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/trigger/AudioEventTrigger.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH;IAuBI;;;;;OAKG;IACH,wBALW,MAAM,SACN,gBAAgB,cAChB,MAAM,GAAC,IAAI,GACT,qBAAqB,CAUjC;IAuCD;;;OAGG;IACH,4BAFa,qBAAqB,CAMjC;IAlFD;;;;OAIG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,WAFU,MAAM,GAAC,IAAI,CAEJ;IAEjB;;;;OAIG;IACH,OAFU,gBAAgB,CAEK;IAkB/B;;;OAGG;IACH,cAHW,qBAAqB,GACnB,OAAO,CAMnB;IAED,eAMC;IAED;;;;;;;;;;;;;;;;;;;;;;;MAMC;IAED,0BASC;CAWJ;AAED;;;;;;;;GAQG;AACH;IAcI;;;OAGG;IACH,mBAHW,qBAAqB,EAAE,GACrB,iBAAiB,CAQ7B;IA6CD;;;OAGG;IACH,4BAFa,iBAAiB,CAM7B;IA3ED;;;;;;;;;OASG;IACH,OAFU,qBAAqB,EAAE,CAEtB;IAcX;;;OAGG;IACH,cAHW,iBAAiB,GACf,OAAO,CAiBnB;IAED,eAUC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;MAIC;IAED,0BAEC;CAWJ;;;;iCA1LgC,4CAA4C"}

package/src/engine/sound/ecs/trigger/AudioEventTrigger.js

@@ -0,0 +1,191 @@
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
+import { EventDescription } from "../../sopra/definition/EventDescription.js";
+
+/**
+ * One trigger rule: "when this entity receives `startEvent`, play `event`; when it receives
+ * `stopEvent`, stop what this rule started".
+ *
+ * The legacy `SoundController.Rule` carried `tracks[] / loop / volume / channel` alongside its event
+ * names, and its system did the picking and the routing at trigger time. Here all four collapse into
+ * the {@link EventDescription} itself — a random pick is a `RandomContainerAudioClip`, looping is the
+ * clip's own loop flag, volume is `gainDb`, and the channel is `busId`. That is the whole point of the
+ * native model: what plays is authored data, not a rule the runtime re-interprets on every trigger.
+ */
+export class AudioEventTriggerRule {
+
+    /**
+     * Entity event name that starts this rule's event. Required — a rule with nothing to start does
+     * nothing at all.
+     * @type {string}
+     */
+    startEvent = "";
+
+    /**
+     * Entity event name that stops whatever this rule started, or null for a fire-and-forget rule
+     * (a one-shot ends on its own; a looping event then lives until the component unlinks).
+     * @type {string|null}
+     */
+    stopEvent = null;
+
+    /**
+     * The authored event this rule plays. Same data an {@link AudioEmitter} would hold — the difference
+     * is only in what makes it sound: linking, versus receiving an entity event.
+     * @type {EventDescription}
+     */
+    event = new EventDescription();
+
+    /**
+     * @param {string} startEvent
+     * @param {EventDescription} event
+     * @param {string|null} [stopEvent]
+     * @returns {AudioEventTriggerRule}
+     */
+    static from(startEvent, event, stopEvent = null) {
+        const r = new AudioEventTriggerRule();
+
+        r.startEvent = startEvent;
+        r.event = event;
+        r.stopEvent = stopEvent;
+
+        return r;
+    }
+
+    /**
+     * @param {AudioEventTriggerRule} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.startEvent === other.startEvent
+            && this.stopEvent === other.stopEvent
+            && this.event.equals(other.event);
+    }
+
+    hash() {
+        return combine_hash(
+            computeStringHash(this.startEvent),
+            this.stopEvent === null ? 0 : computeStringHash(this.stopEvent),
+            this.event.hash()
+        );
+    }
+
+    toJSON() {
+        return {
+            startEvent: this.startEvent,
+            stopEvent: this.stopEvent,
+            event: this.event.toJSON()
+        };
+    }
+
+    fromJSON(json) {
+        this.startEvent = json.startEvent !== undefined ? json.startEvent : "";
+        this.stopEvent = json.stopEvent !== undefined && json.stopEvent !== null ? json.stopEvent : null;
+
+        this.event = new EventDescription();
+
+        if (json.event !== undefined) {
+            this.event.fromJSON(json.event);
+        }
+    }
+
+    /**
+     * @param {*} json
+     * @returns {AudioEventTriggerRule}
+     */
+    static fromJSON(json) {
+        const r = new AudioEventTriggerRule();
+        r.fromJSON(json);
+        return r;
+    }
+}
+
+/**
+ * Plays authored sopra events in response to entity events — the native replacement for the legacy
+ * `SoundController`, whose system wrote `SoundTrack`s into the entity's `SoundEmitter` and so could not
+ * outlive it.
+ *
+ * Where an {@link AudioEmitter} sounds because it was linked, an `AudioEventTrigger` sounds because the
+ * entity received an event: "unit took damage" → a hurt sound. Driven by {@link AudioEventTriggerSystem};
+ * the entity's {@link Transform} supplies position, exactly as for an emitter.
+ */
+export class AudioEventTrigger {
+
+    /**
+     * Authored rules, evaluated independently — several may listen to the same event, and each owns the
+     * instances it started.
+     *
+     * Read once when the component links: the system registers one entity-event listener per rule then,
+     * so mutating this array on a linked component has no effect until it is re-linked (remove and
+     * re-add the component), which mirrors {@link AudioEmitter.event}.
+     *
+     * @type {AudioEventTriggerRule[]}
+     */
+    rules = [];
+
+    /**
+     * @param {AudioEventTriggerRule[]} rules
+     * @returns {AudioEventTrigger}
+     */
+    static from(rules) {
+        const r = new AudioEventTrigger();
+
+        r.rules = rules;
+
+        return r;
+    }
+
+    /**
+     * @param {AudioEventTrigger} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        const rules = this.rules;
+        const otherRules = other.rules;
+
+        if (rules.length !== otherRules.length) {
+            return false;
+        }
+
+        for (let i = 0; i < rules.length; i++) {
+            if (!rules[i].equals(otherRules[i])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    hash() {
+        const rules = this.rules;
+
+        let hash = rules.length;
+
+        for (let i = 0; i < rules.length; i++) {
+            hash = combine_hash(hash, rules[i].hash());
+        }
+
+        return hash;
+    }
+
+    toJSON() {
+        return {
+            rules: this.rules.map(rule => rule.toJSON())
+        };
+    }
+
+    fromJSON(json) {
+        this.rules = json.rules === undefined ? [] : json.rules.map(AudioEventTriggerRule.fromJSON);
+    }
+
+    /**
+     * @param {*} json
+     * @returns {AudioEventTrigger}
+     */
+    static fromJSON(json) {
+        const r = new AudioEventTrigger();
+        r.fromJSON(json);
+        return r;
+    }
+}
+
+AudioEventTrigger.typeName = "AudioEventTrigger";

package/src/engine/sound/ecs/trigger/AudioEventTriggerSerializationAdapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Binary (de)serialization for the {@link AudioEventTrigger} component — what lets authored,
+ * event-driven audio live in a level rather than only being built in code.
+ *
+ * Each rule carries an {@link EventDescription} whose clip graph is polymorphic (sample / sequence /
+ * random / switch / blend), so the description's own adapter needs the engine's
+ * {@link BinaryObjectSerializationAdapter}. Component adapters are handed it as the SECOND initialize
+ * argument (the first being the engine/context), unlike nested object adapters which take it alone —
+ * hence the explicit forwarding below. Mirrors {@link AudioEmitterSerializationAdapter}.
+ */
+export class AudioEventTriggerSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof AudioEventTrigger;
+    /**
+     * @param {Engine} context
+     * @param {BinaryObjectSerializationAdapter} objectAdapter
+     */
+    initialize(context: Engine, objectAdapter: BinaryObjectSerializationAdapter): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AudioEventTrigger} value
+     */
+    serialize(buffer: BinaryBuffer, value: AudioEventTrigger): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AudioEventTrigger} value mutated in place
+     */
+    deserialize(buffer: BinaryBuffer, value: AudioEventTrigger): void;
+    #private;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { AudioEventTrigger } from "./AudioEventTrigger.js";
+//# sourceMappingURL=AudioEventTriggerSerializationAdapter.d.ts.map

package/src/engine/sound/ecs/trigger/AudioEventTriggerSerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEventTriggerSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/trigger/AudioEventTriggerSerializationAdapter.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH;;IACI,gCAA0B;IAQ1B;;;OAGG;IACH,mFAEC;IAED;;;OAGG;IACH,uCAFW,iBAAiB,QAuB3B;IAED;;;OAGG;IACH,yCAFW,iBAAiB,QAmB3B;;CACJ;gDAhF+C,gEAAgE;kCAEvD,wBAAwB"}

package/src/engine/sound/ecs/trigger/AudioEventTriggerSerializationAdapter.js

@@ -0,0 +1,81 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { EventDescriptionSerializationAdapter } from "../../sopra/definition/EventDescriptionSerializationAdapter.js";
+import { AudioEventTrigger, AudioEventTriggerRule } from "./AudioEventTrigger.js";
+
+/**
+ * Binary (de)serialization for the {@link AudioEventTrigger} component — what lets authored,
+ * event-driven audio live in a level rather than only being built in code.
+ *
+ * Each rule carries an {@link EventDescription} whose clip graph is polymorphic (sample / sequence /
+ * random / switch / blend), so the description's own adapter needs the engine's
+ * {@link BinaryObjectSerializationAdapter}. Component adapters are handed it as the SECOND initialize
+ * argument (the first being the engine/context), unlike nested object adapters which take it alone —
+ * hence the explicit forwarding below. Mirrors {@link AudioEmitterSerializationAdapter}.
+ */
+export class AudioEventTriggerSerializationAdapter extends BinaryClassSerializationAdapter {
+    klass = AudioEventTrigger;
+    version = 0;
+
+    /**
+     * @type {EventDescriptionSerializationAdapter}
+     */
+    #event = new EventDescriptionSerializationAdapter();
+
+    /**
+     * @param {Engine} context
+     * @param {BinaryObjectSerializationAdapter} objectAdapter
+     */
+    initialize(context, objectAdapter) {
+        this.#event.initialize(objectAdapter);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AudioEventTrigger} value
+     */
+    serialize(buffer, value) {
+        const rules = value.rules;
+
+        buffer.writeUintVar(rules.length);
+
+        for (let i = 0; i < rules.length; i++) {
+            const rule = rules[i];
+
+            buffer.writeUTF8String(rule.startEvent);
+
+            // stopEvent is optional, and "no stop event" is not the same as "stop on the empty string" —
+            // flag it rather than encoding absence as a magic string
+            if (rule.stopEvent === null) {
+                buffer.writeUint8(0);
+            } else {
+                buffer.writeUint8(1);
+                buffer.writeUTF8String(rule.stopEvent);
+            }
+
+            this.#event.serialize(buffer, rule.event);
+        }
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {AudioEventTrigger} value mutated in place
+     */
+    deserialize(buffer, value) {
+        const count = buffer.readUintVar();
+
+        const rules = [];
+
+        for (let i = 0; i < count; i++) {
+            const rule = new AudioEventTriggerRule();
+
+            rule.startEvent = buffer.readUTF8String();
+            rule.stopEvent = buffer.readUint8() === 0 ? null : buffer.readUTF8String();
+
+            this.#event.deserialize(buffer, rule.event);
+
+            rules.push(rule);
+        }
+
+        value.rules = rules;
+    }
+}

package/src/engine/sound/ecs/trigger/AudioEventTriggerSystem.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Drives {@link AudioEventTrigger} components: on link it subscribes each rule to its entity event, and
+ * plays the rule's authored event through the shared sopra engine when that event arrives.
+ *
+ * Instances started by a rule are held until they end (a one-shot self-releases) or until the rule's
+ * `stopEvent` arrives; unlinking removes every listener and stops everything still sounding, so a
+ * destroyed entity is silent and leaves nothing subscribed.
+ *
+ * Shares the single {@link SopraEngine} owned by {@link SoundEngine} (created on demand, idempotent).
+ * It deliberately has **no** `update`: the per-frame sopra tick and the listener pose belong to
+ * {@link AudioEmitterSystem}, which is the single tick owner — a second ticker would advance the same
+ * instances twice per frame. Register this system alongside it.
+ */
+export class AudioEventTriggerSystem extends System<any> {
+    /**
+     * @param {AssetManager} assetManager
+     * @param {SoundEngine} soundEngine owns the AudioContext + master destination + sopra engine
+     */
+    constructor(assetManager: AssetManager, soundEngine: SoundEngine);
+    dependencies: (typeof Transform | typeof AudioEventTrigger)[];
+    /**
+     * Per-entity records: { listeners: [{name, handler}], live: Map<AudioEventTriggerRule, Set<EventInstance>> }.
+     * @type {object[]}
+     */
+    data: object[];
+    /**
+     * @type {SoundEngine}
+     */
+    soundEngine: SoundEngine;
+    /**
+     * @type {AssetManager}
+     */
+    assetManager: AssetManager;
+    /**
+     * The shared sopra engine (idempotent create — reused if another sound system already made it).
+     * @type {SopraEngine}
+     */
+    sopra: SopraEngine;
+    /**
+     * @param {AudioEventTrigger} trigger
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(trigger: AudioEventTrigger, transform: Transform, entity: number): void;
+    /**
+     * @param {AudioEventTrigger} trigger
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(trigger: AudioEventTrigger, transform: Transform, entity: number): void;
+    /**
+     * Instances a given rule currently has sounding on an entity, in start order. The observation point
+     * for callers that need to reach a triggered sound (there is no component-level handle by design —
+     * a trigger is fire-and-forget).
+     * @param {number} entity
+     * @param {AudioEventTriggerRule} rule
+     * @returns {EventInstance[]}
+     */
+    instancesFor(entity: number, rule: AudioEventTriggerRule): EventInstance[];
+    #private;
+}
+import { System } from "../../../ecs/System.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { AudioEventTrigger } from "./AudioEventTrigger.js";
+//# sourceMappingURL=AudioEventTriggerSystem.d.ts.map

package/src/engine/sound/ecs/trigger/AudioEventTriggerSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEventTriggerSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/ecs/trigger/AudioEventTriggerSystem.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH;IASI;;;OAGG;IACH,kEAwBC;IApCD,8DAA8C;IAE9C;;;OAGG;IACH,MAFU,MAAM,EAAE,CAER;IASN;;OAEG;IACH,yBAA8B;IAE9B;;OAEG;IACH,2BAAgC;IAQhC;;;OAGG;IACH,mBAAkF;IAGtF;;;;OAIG;IACH,cAJW,iBAAiB,aACjB,SAAS,UACT,MAAM,QA6BhB;IAED;;;;OAIG;IACH,gBAJW,iBAAiB,aACjB,SAAS,UACT,MAAM,QAoBhB;IAED;;;;;;;OAOG;IACH,qBAJW,MAAM,gCAEJ,eAAe,CAY3B;;CA+CJ;uBArLsB,wBAAwB;0BACrB,qCAAqC;kCAE7B,wBAAwB"}