@woosh/meep-engine 3.3.0 → 3.4.0

package/src/engine/sound/{ecs/emitter → sopra/legacy}/SoundEmitter.js

@@ -1,382 +1,352 @@
-import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
-import List from '../../../../core/collection/list/List.js';
-import Vector1 from "../../../../core/geom/Vector1.js";
-import { objectKeyByValue } from "../../../../core/model/object/objectKeyByValue.js";
-import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
-import { number_compare_ascending } from "../../../../core/primitives/numbers/number_compare_ascending.js";
-import { compareStrings } from "../../../../core/primitives/strings/compareStrings.js";
-import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
-import { SoundAttenuationFunction } from "./SoundAttenuationFunction.js";
-import { SoundEmitterFlags } from "./SoundEmitterFlags.js";
-import { SoundPanningModelType } from "./SoundPanningModelType.js";
-import { SoundTrack } from "./SoundTrack.js";
-
-const DEFAULT_DISTANCE_MIN = 1;
-const DEFAULT_DISTANCE_MAX = 10000;
-
-const DEFAULT_CHANNEL = null;
-
-/**
- * @deprecated Legacy sound component — superseded by the native {@link AudioEmitter}, which owns a
- * sopra `EventDescription` directly. Retained as a deprecate-and-plumb compat reader (it still routes
- * through sopra via {@link SoundEmitterSystem}); prefer `AudioEmitter` for new content.
- * @class
- */
-export class SoundEmitter {
-
-
-    /**
-     * @readonly
-     * @type {List<SoundTrack>}
-     */
-    tracks = new List();
-
-    /**
-     *
-     * @type {String|SoundEmitterChannels|null}
-     */
-    channel = DEFAULT_CHANNEL;
-
-    /**
-     *
-     * @type {number}
-     * @private
-     */
-    __distanceMin = 1;
-
-    /**
-     *
-     * @type {number}
-     * @private
-     */
-    __distanceMax = 10000;
-
-    /**
-     * TODO add to binary serialization
-     * @type {SoundPanningModelType}
-     */
-    panningModel = SoundPanningModelType.HRTF;
-
-    /**
-     * Type of attenuation used for sound fall-off, this is only used if Attenuation flag is set
-     * @type {SoundAttenuationFunction|number}
-     */
-    attenuation = SoundAttenuationFunction.Smith;
-
-    /**
-     *
-     * @type {number|SoundEmitterFlags}
-     */
-    flags = 0;
-
-    /**
-     *
-     * @type {Vector1}
-     */
-    volume = new Vector1(1);
-
-    /**
-     * Back-reference to the per-entity sopra translation record (set on link by
-     * {@link SoundEmitterComponentContext}). Used by the deprecated fade/stop helpers to reach the
-     * live sopra instances.
-     * @type {SoundEmitterComponentContext|null}
-     */
-    __soundRuntime = null;
-
-    /**
-     * @deprecated sopra owns the audio graph — the emitter no longer holds WebAudio nodes.
-     */
-    get nodes() {
-        throw new Error("SoundEmitter.nodes is deprecated — sopra owns the audio graph");
-    }
-
-    /**
-     *
-     * @param {SoundEmitter} other
-     * @returns number
-     */
-    compare(other) {
-        const tracks = this.tracks.compare(other.tracks);
-
-        if (tracks !== 0) {
-            return tracks;
-        }
-
-        const channel = compareStrings(this.channel, other.channel);
-
-        if (channel !== 0) {
-            return channel;
-        }
-
-        const distanceMin = number_compare_ascending(this.__distanceMin, other.__distanceMin);
-
-        if (distanceMin !== 0) {
-            return distanceMin;
-        }
-        const distanceMax = number_compare_ascending(this.__distanceMax, other.__distanceMax);
-
-        if (distanceMax !== 0) {
-            return distanceMax;
-        }
-
-        const panningModel = number_compare_ascending(this.panningModel, other.panningModel);
-
-        if (panningModel !== 0) {
-            return panningModel;
-        }
-
-        const attenuation = number_compare_ascending(this.attenuation, other.attenuation);
-
-        if (attenuation !== 0) {
-            return attenuation;
-        }
-
-        const flags = number_compare_ascending(this.flags, other.flags);
-
-        if (flags !== 0) {
-            return flags;
-        }
-
-        const volume = number_compare_ascending(this.volume.getValue(), other.volume.getValue());
-
-        if (volume !== 0) {
-            return volume;
-        }
-
-
-        return 0;
-    }
-
-
-    /**
-     *
-     * @param {number|SoundEmitterFlags} flag
-     * @returns {void}
-     */
-    setFlag(flag) {
-        this.flags |= flag;
-    }
-
-    /**
-     *
-     * @param {number|SoundEmitterFlags} flag
-     * @returns {void}
-     */
-    clearFlag(flag) {
-        this.flags &= ~flag;
-    }
-
-    /**
-     *
-     * @param {number|SoundEmitterFlags} flag
-     * @param {boolean} value
-     */
-    writeFlag(flag, value) {
-        if (value) {
-            this.setFlag(flag);
-        } else {
-            this.clearFlag(flag);
-        }
-    }
-
-    /**
-     *
-     * @param {number|SoundEmitterFlags} flag
-     * @returns {boolean}
-     */
-    getFlag(flag) {
-        return (this.flags & flag) === flag;
-    }
-
-
-    /**
-     * @deprecated
-     * @param {boolean} v
-     */
-    set isPositioned(v) {
-        this.writeFlag(SoundEmitterFlags.Spatialization, v);
-    }
-
-    /**
-     * @deprecated
-     * @return {boolean}
-     */
-    get isPositioned() {
-        return this.getFlag(SoundEmitterFlags.Spatialization);
-    }
-
-    /**
-     * @returns {boolean}
-     * @param {SoundEmitter} other
-     */
-    equals(other) {
-        return this.channel === other.channel
-            && this.flags === other.flags
-            && this.__distanceMin === other.__distanceMin
-            && this.__distanceMax === other.__distanceMax
-            && this.attenuation === other.attenuation
-            && this.tracks.equals(other.tracks)
-            ;
-    }
-
-    /**
-     *
-     * @return {number}
-     */
-    hash() {
-        return combine_hash(
-            computeStringHash(this.channel),
-            this.flags,
-            computeHashFloat(this.__distanceMin),
-            computeHashFloat(this.__distanceMax),
-            this.attenuation,
-            this.tracks.hash()
-        );
-    }
-
-    /**
-     *
-     * @returns {number}
-     */
-    get distanceMin() {
-        return this.__distanceMin;
-    }
-
-    /**
-     * @param {number} v
-     */
-    set distanceMin(v) {
-        this.__distanceMin = v;
-    }
-
-    /**
-     *
-     * @returns {number}
-     */
-    get distanceMax() {
-        return this.__distanceMax;
-    }
-
-    /**
-     * @param {number} v
-     */
-    set distanceMax(v) {
-        this.__distanceMax = v;
-    }
-
-    /**
-     * @deprecated plumbs into sopra — fades every playing track out and stops it.
-     * @param {number} [duration] fade duration in seconds
-     */
-    fadeOutAllTracks(duration = 1) {
-        if (this.__soundRuntime !== null) {
-            this.__soundRuntime.fadeOutAll(duration);
-        }
-    }
-
-    /**
-     * @deprecated plumbs into sopra — stops every playing track on this emitter.
-     */
-    stopAllTracks() {
-        if (this.__soundRuntime !== null) {
-            this.__soundRuntime.stopAll();
-        }
-    }
-
-    toJSON() {
-        return {
-            isPositioned: this.getFlag(SoundEmitterFlags.Spatialization),
-            isAttenuated: this.getFlag(SoundEmitterFlags.Attenuation),
-            channel: this.channel,
-            volume: this.volume.toJSON(),
-            tracks: this.tracks.toJSON(),
-            distanceMin: this.distanceMin,
-            distanceMax: this.distanceMax,
-            attenuation: objectKeyByValue(SoundAttenuationFunction, this.attenuation),
-            panningModel: objectKeyByValue(SoundPanningModelType, this.panningModel)
-        };
-    }
-
-    fromJSON(json) {
-        if (json.isPositioned !== undefined) {
-            this.writeFlag(SoundEmitterFlags.Spatialization, json.isPositioned);
-        } else {
-            this.clearFlag(SoundEmitterFlags.Spatialization);
-        }
-
-        if (json.channel !== undefined) {
-            this.channel = json.channel;
-        } else {
-            this.channel = DEFAULT_CHANNEL;
-        }
-
-        if (json.volume !== undefined) {
-            this.volume.fromJSON(json.volume);
-        }
-
-        if (typeof json.distanceMin === "number") {
-            this.distanceMin = json.distanceMin;
-        } else {
-            this.distanceMin = DEFAULT_DISTANCE_MIN;
-        }
-
-        if (typeof json.distanceMax === "number") {
-            this.distanceMax = json.distanceMax;
-        } else {
-            this.distanceMax = DEFAULT_DISTANCE_MAX;
-        }
-
-        if (typeof json.isAttenuated === "boolean") {
-            this.writeFlag(SoundEmitterFlags.Attenuation, json.isAttenuated);
-        } else {
-            this.setFlag(SoundEmitterFlags.Attenuation);
-        }
-
-        if (typeof json.attenuation === "string") {
-            const attenuation = SoundAttenuationFunction[json.attenuation];
-
-            if (attenuation === undefined) {
-                throw new Error(`Unknown attenuation type '${json.attenuation}', valid types are: ${Object.keys(SoundAttenuationFunction)}`);
-            }
-
-            this.attenuation = attenuation;
-        } else {
-            this.attenuation = SoundAttenuationFunction.Linear;
-        }
-
-        //tracks
-        if (json.tracks !== undefined) {
-            this.tracks.fromJSON(json.tracks, SoundTrack);
-        }
-
-        if (json.panningModel === undefined) {
-            this.panningModel = SoundPanningModelType.HRTF;
-        } else {
-            const model = SoundPanningModelType[json.panningModel];
-
-            if (model === undefined) {
-                throw new Error(`Unknown panning model '${json.panningModel}', valid types are: ${Object.keys(SoundPanningModelType)}`);
-            }
-
-            this.panningModel = model;
-        }
-    }
-
-
-    /**
-     *
-     * @param json
-     * @returns {SoundEmitter}
-     */
-    static fromJSON(json) {
-        const result = new SoundEmitter();
-
-        result.fromJSON(json);
-
-        return result;
-    }
-}
-
-SoundEmitter.typeName = "SoundEmitter";
-
-
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import List from '../../../../core/collection/list/List.js';
+import Vector1 from "../../../../core/geom/Vector1.js";
+import { objectKeyByValue } from "../../../../core/model/object/objectKeyByValue.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { number_compare_ascending } from "../../../../core/primitives/numbers/number_compare_ascending.js";
+import { compareStrings } from "../../../../core/primitives/strings/compareStrings.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
+import { SoundAttenuationFunction } from "./SoundAttenuationFunction.js";
+import { SoundEmitterFlags } from "./SoundEmitterFlags.js";
+import { SoundPanningModelType } from "./SoundPanningModelType.js";
+import { SoundTrack } from "./SoundTrack.js";
+
+const DEFAULT_DISTANCE_MIN = 1;
+const DEFAULT_DISTANCE_MAX = 10000;
+
+const DEFAULT_CHANNEL = null;
+
+/**
+ * @deprecated Frozen legacy reader — superseded by the native {@link AudioEmitter}, which owns a sopra
+ * `EventDescription` directly. Data only: no system links it and nothing plays it. It survives so that
+ * saves written before the native audio path still deserialize, and so
+ * {@link convertLegacySoundComponents} can turn what they carry into authored sopra events. Do not
+ * author new content with it.
+ * @class
+ */
+export class SoundEmitter {
+
+
+    /**
+     * @readonly
+     * @type {List<SoundTrack>}
+     */
+    tracks = new List();
+
+    /**
+     * Free-string mixer channel name. Resolved against the live bus set by
+     * {@link convertLegacySoundComponents}, which falls back to `effects` for a name the mixer no
+     * longer has — sopra's bus lookup throws on an unknown id.
+     * @type {String|null}
+     */
+    channel = DEFAULT_CHANNEL;
+
+    /**
+     *
+     * @type {number}
+     * @private
+     */
+    __distanceMin = 1;
+
+    /**
+     *
+     * @type {number}
+     * @private
+     */
+    __distanceMax = 10000;
+
+    /**
+     * TODO add to binary serialization
+     * @type {SoundPanningModelType}
+     */
+    panningModel = SoundPanningModelType.HRTF;
+
+    /**
+     * Type of attenuation used for sound fall-off, this is only used if Attenuation flag is set
+     * @type {SoundAttenuationFunction|number}
+     */
+    attenuation = SoundAttenuationFunction.Smith;
+
+    /**
+     *
+     * @type {number|SoundEmitterFlags}
+     */
+    flags = 0;
+
+    /**
+     *
+     * @type {Vector1}
+     */
+    volume = new Vector1(1);
+
+    /**
+     *
+     * @param {SoundEmitter} other
+     * @returns number
+     */
+    compare(other) {
+        const tracks = this.tracks.compare(other.tracks);
+
+        if (tracks !== 0) {
+            return tracks;
+        }
+
+        const channel = compareStrings(this.channel, other.channel);
+
+        if (channel !== 0) {
+            return channel;
+        }
+
+        const distanceMin = number_compare_ascending(this.__distanceMin, other.__distanceMin);
+
+        if (distanceMin !== 0) {
+            return distanceMin;
+        }
+        const distanceMax = number_compare_ascending(this.__distanceMax, other.__distanceMax);
+
+        if (distanceMax !== 0) {
+            return distanceMax;
+        }
+
+        const panningModel = number_compare_ascending(this.panningModel, other.panningModel);
+
+        if (panningModel !== 0) {
+            return panningModel;
+        }
+
+        const attenuation = number_compare_ascending(this.attenuation, other.attenuation);
+
+        if (attenuation !== 0) {
+            return attenuation;
+        }
+
+        const flags = number_compare_ascending(this.flags, other.flags);
+
+        if (flags !== 0) {
+            return flags;
+        }
+
+        const volume = number_compare_ascending(this.volume.getValue(), other.volume.getValue());
+
+        if (volume !== 0) {
+            return volume;
+        }
+
+
+        return 0;
+    }
+
+
+    /**
+     *
+     * @param {number|SoundEmitterFlags} flag
+     * @returns {void}
+     */
+    setFlag(flag) {
+        this.flags |= flag;
+    }
+
+    /**
+     *
+     * @param {number|SoundEmitterFlags} flag
+     * @returns {void}
+     */
+    clearFlag(flag) {
+        this.flags &= ~flag;
+    }
+
+    /**
+     *
+     * @param {number|SoundEmitterFlags} flag
+     * @param {boolean} value
+     */
+    writeFlag(flag, value) {
+        if (value) {
+            this.setFlag(flag);
+        } else {
+            this.clearFlag(flag);
+        }
+    }
+
+    /**
+     *
+     * @param {number|SoundEmitterFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag) {
+        return (this.flags & flag) === flag;
+    }
+
+
+    /**
+     * @deprecated
+     * @param {boolean} v
+     */
+    set isPositioned(v) {
+        this.writeFlag(SoundEmitterFlags.Spatialization, v);
+    }
+
+    /**
+     * @deprecated
+     * @return {boolean}
+     */
+    get isPositioned() {
+        return this.getFlag(SoundEmitterFlags.Spatialization);
+    }
+
+    /**
+     * @returns {boolean}
+     * @param {SoundEmitter} other
+     */
+    equals(other) {
+        return this.channel === other.channel
+            && this.flags === other.flags
+            && this.__distanceMin === other.__distanceMin
+            && this.__distanceMax === other.__distanceMax
+            && this.attenuation === other.attenuation
+            && this.tracks.equals(other.tracks)
+            ;
+    }
+
+    /**
+     *
+     * @return {number}
+     */
+    hash() {
+        return combine_hash(
+            computeStringHash(this.channel),
+            this.flags,
+            computeHashFloat(this.__distanceMin),
+            computeHashFloat(this.__distanceMax),
+            this.attenuation,
+            this.tracks.hash()
+        );
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get distanceMin() {
+        return this.__distanceMin;
+    }
+
+    /**
+     * @param {number} v
+     */
+    set distanceMin(v) {
+        this.__distanceMin = v;
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get distanceMax() {
+        return this.__distanceMax;
+    }
+
+    /**
+     * @param {number} v
+     */
+    set distanceMax(v) {
+        this.__distanceMax = v;
+    }
+
+    toJSON() {
+        return {
+            isPositioned: this.getFlag(SoundEmitterFlags.Spatialization),
+            isAttenuated: this.getFlag(SoundEmitterFlags.Attenuation),
+            channel: this.channel,
+            volume: this.volume.toJSON(),
+            tracks: this.tracks.toJSON(),
+            distanceMin: this.distanceMin,
+            distanceMax: this.distanceMax,
+            attenuation: objectKeyByValue(SoundAttenuationFunction, this.attenuation),
+            panningModel: objectKeyByValue(SoundPanningModelType, this.panningModel)
+        };
+    }
+
+    fromJSON(json) {
+        if (json.isPositioned !== undefined) {
+            this.writeFlag(SoundEmitterFlags.Spatialization, json.isPositioned);
+        } else {
+            this.clearFlag(SoundEmitterFlags.Spatialization);
+        }
+
+        if (json.channel !== undefined) {
+            this.channel = json.channel;
+        } else {
+            this.channel = DEFAULT_CHANNEL;
+        }
+
+        if (json.volume !== undefined) {
+            this.volume.fromJSON(json.volume);
+        }
+
+        if (typeof json.distanceMin === "number") {
+            this.distanceMin = json.distanceMin;
+        } else {
+            this.distanceMin = DEFAULT_DISTANCE_MIN;
+        }
+
+        if (typeof json.distanceMax === "number") {
+            this.distanceMax = json.distanceMax;
+        } else {
+            this.distanceMax = DEFAULT_DISTANCE_MAX;
+        }
+
+        if (typeof json.isAttenuated === "boolean") {
+            this.writeFlag(SoundEmitterFlags.Attenuation, json.isAttenuated);
+        } else {
+            this.setFlag(SoundEmitterFlags.Attenuation);
+        }
+
+        if (typeof json.attenuation === "string") {
+            const attenuation = SoundAttenuationFunction[json.attenuation];
+
+            if (attenuation === undefined) {
+                throw new Error(`Unknown attenuation type '${json.attenuation}', valid types are: ${Object.keys(SoundAttenuationFunction)}`);
+            }
+
+            this.attenuation = attenuation;
+        } else {
+            this.attenuation = SoundAttenuationFunction.Linear;
+        }
+
+        //tracks
+        if (json.tracks !== undefined) {
+            this.tracks.fromJSON(json.tracks, SoundTrack);
+        }
+
+        if (json.panningModel === undefined) {
+            this.panningModel = SoundPanningModelType.HRTF;
+        } else {
+            const model = SoundPanningModelType[json.panningModel];
+
+            if (model === undefined) {
+                throw new Error(`Unknown panning model '${json.panningModel}', valid types are: ${Object.keys(SoundPanningModelType)}`);
+            }
+
+            this.panningModel = model;
+        }
+    }
+
+
+    /**
+     *
+     * @param json
+     * @returns {SoundEmitter}
+     */
+    static fromJSON(json) {
+        const result = new SoundEmitter();
+
+        result.fromJSON(json);
+
+        return result;
+    }
+}
+
+SoundEmitter.typeName = "SoundEmitter";
+
+