@woosh/meep-engine 3.2.0 → 3.4.0

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

@@ -1,357 +1,278 @@
-import { assert } from "../../../../core/assert.js";
-import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
-import Signal from "../../../../core/events/signal/Signal.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 { SoundTrackFlags } from "./SoundTrackFlags.js";
-
-const DEFAULT_FLAGS = SoundTrackFlags.StartWhenReady;
-
-export class SoundTrack {
-
-    /**
-     *
-     * @type {String|null}
-     */
-    url = null;
-
-    /**
-     * Playback cursor in seconds. Backed by the bound sopra instance when linked.
-     * @type {number}
-     */
-    #time = 0;
-
-    /**
-     * Bound sopra EventInstance (set by SoundEmitterComponentContext while this track is linked), or
-     * null. Lets time reads/seeks plumb into sopra.
-     * @type {EventInstance|null}
-     */
-    __instance = null;
-
-    /**
-     * Owning translation record while this track is linked, or null. Lets a live `volume` set plumb
-     * into the bound sopra instance gain.
-     * @type {SoundEmitterComponentContext|null}
-     */
-    __soundRuntime = null;
-
-    /**
-     * @deprecated Not used
-     * @type {String|null}
-     */
-    channel = "";
-
-    /**
-     * @private
-     * @type {number}
-     */
-    __volume = 1;
-
-
-    /**
-     *
-     * @type {number|SoundTrackFlags}
-     */
-    flags = DEFAULT_FLAGS;
-
-    on = {
-        /**
-         * @type {Signal<this>}
-         */
-        ended: new Signal()
-    };
-
-    /**
-     * @deprecated sopra owns the audio graph — the track no longer holds WebAudio nodes.
-     */
-    get nodes() {
-        throw new Error("SoundTrack.nodes is deprecated — sopra owns the audio graph");
-    }
-
-    /**
-     * Playback cursor in seconds. Reads the bound sopra instance's playhead when linked, else the
-     * last value set.
-     * @returns {number}
-     */
-    get time() {
-        return this.__instance !== null ? this.__instance.playhead : this.#time;
-    }
-
-    /**
-     * Setting the cursor seeks the bound sopra instance (e.g. resetSoundEmitterTracks sets 0).
-     * @param {number} v
-     */
-    set time(v) {
-        this.#time = v;
-
-        if (this.__instance !== null) {
-            this.__instance.seek(v);
-        }
-    }
-
-    /**
-     *
-     * @param {SoundTrack} other
-     * @returns number
-     */
-    compare(other) {
-        const url = compareStrings(this.url, other.url);
-
-        if (url !== 0) {
-            return url;
-        }
-
-        const time = number_compare_ascending(this.time, other.time);
-
-        if (time !== 0) {
-            return time;
-        }
-
-        const channel = compareStrings(this.channel, other.channel);
-
-        if (channel !== 0) {
-            return channel;
-        }
-
-        const volume = number_compare_ascending(this.__volume, other.__volume);
-
-        if (volume !== 0) {
-            return volume;
-        }
-
-        const flags = number_compare_ascending(this.flags, other.flags);
-
-        if (flags !== 0) {
-            return flags;
-        }
-
-        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;
-    }
-
-    /**
-     * Linearly transition volume to a target value over a certain duration.
-     * Useful for fading sounds in and out of the mix.
-     *
-     * NOTE: volume property of the object is updated instantly, transition happens at the AudioNode level only
-     *
-     * @param {number} target target volume value
-     * @param {number} duration How long the transition should take, in seconds
-     * @param {number} [startAfter] when fading should start, see WebAudio docs on {@link AudioContext#currentTime}
-     */
-    setVolumeOverTime() {
-        throw new Error("SoundTrack.setVolumeOverTime is deprecated — fades are owned by the sopra instance");
-    }
-
-    /**
-     *
-     * @param {number} v
-     */
-    set volume(v) {
-        this.__volume = v;
-
-        // when linked, a live volume change is heard immediately (emitter.volume × track.volume)
-        if (this.__soundRuntime !== null) {
-            this.__soundRuntime.refreshTrackVolume(this);
-        }
-    }
-
-    /**
-     *
-     * @return {number}
-     */
-    get volume() {
-        return this.__volume;
-    }
-
-    /**
-     * @deprecated
-     * @return {boolean}
-     */
-    get loop() {
-        return this.getFlag(SoundTrackFlags.Loop);
-    }
-
-    /**
-     * @deprecated
-     * @param {boolean} v
-     */
-    set loop(v) {
-        this.writeFlag(SoundTrackFlags.Loop, v);
-    }
-
-    /**
-     * @deprecated
-     * @return {boolean}
-     */
-    get playing() {
-        return this.getFlag(SoundTrackFlags.Playing);
-    }
-
-    /**
-     * @deprecated
-     * @param {boolean} v
-     */
-    set playing(v) {
-        this.writeFlag(SoundTrackFlags.Playing, v);
-    }
-
-    /**
-     * @deprecated
-     * @return {boolean}
-     */
-    get startWhenReady() {
-        return this.getFlag(SoundTrackFlags.StartWhenReady);
-    }
-
-    /**
-     * @deprecated
-     * @param {boolean} v
-     */
-    set startWhenReady(v) {
-        this.writeFlag(SoundTrackFlags.StartWhenReady, v);
-    }
-
-    /**
-     *
-     * @param {SoundTrack} other
-     */
-    copy(other) {
-        this.url = other.url;
-        this.time = other.time;
-        this.volume = other.volume;
-        this.flags = other.flags;
-    }
-
-    /**
-     *
-     * @param {SoundTrack} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return this.url === other.url
-            && this.time === other.time
-            && this.__volume === other.__volume
-            && this.flags === other.flags
-            ;
-    }
-
-    /**
-     *
-     * @return {number}
-     */
-    hash() {
-        return combine_hash(
-            computeStringHash(this.url),
-            computeHashFloat(this.time),
-            computeHashFloat(this.__volume),
-            this.flags
-        );
-    }
-
-    /**
-     *
-     * @return {SoundTrack}
-     */
-    clone() {
-        const r = new SoundTrack();
-
-        r.copy(this);
-
-        return r;
-    }
-
-    toJSON() {
-        return {
-            url: this.url,
-            loop: this.getFlag(SoundTrackFlags.Loop),
-            time: this.time,
-            volume: this.volume,
-            playing: this.getFlag(SoundTrackFlags.Playing),
-            startWhenReady: this.getFlag(SoundTrackFlags.StartWhenReady),
-            usingAssetAlias: this.getFlag(SoundTrackFlags.UsingAliasURL),
-            synchronized: this.getFlag(SoundTrackFlags.Synchronized)
-        };
-    }
-
-    fromJSON(
-        {
-            url,
-            loop = false,
-            time = 0,
-            volume = 1,
-            playing = false,
-            startWhenReady = true,
-            usingAssetAlias = false,
-            synchronized = false
-        }
-    ) {
-        assert.isString(url, 'url');
-
-        this.url = url;
-
-        this.writeFlag(SoundTrackFlags.Loop, loop);
-
-        this.writeFlag(SoundTrackFlags.UsingAliasURL, usingAssetAlias);
-
-        this.time = time;
-
-        this.volume = volume;
-
-        this.writeFlag(SoundTrackFlags.Playing, playing);
-
-        this.writeFlag(SoundTrackFlags.StartWhenReady, startWhenReady);
-
-        this.writeFlag(SoundTrackFlags.Synchronized, synchronized);
-    }
-
-    static fromJSON(json) {
-        const track = new SoundTrack();
-
-        track.fromJSON(json);
-
-        return track;
-    }
-
-}
+import { assert } from "../../../../core/assert.js";
+import { combine_hash } from "../../../../core/collection/array/combine_hash.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 { SoundTrackFlags } from "./SoundTrackFlags.js";
+
+const DEFAULT_FLAGS = SoundTrackFlags.StartWhenReady;
+
+/**
+ * @deprecated Frozen legacy reader — one track of a legacy {@link SoundEmitter}. Data only: it has no
+ * runtime behaviour and nothing plays it. It exists so that saves written before the native audio path
+ * still deserialize, and so {@link convertLegacySoundComponents} can turn what they carry into an
+ * authored sopra event. Do not author new content with it.
+ */
+export class SoundTrack {
+
+    /**
+     *
+     * @type {String|null}
+     */
+    url = null;
+
+    /**
+     * Playback cursor in seconds, as it was written. Never restored into playback — the legacy runtime
+     * always started a loaded track from zero — so the converter drops it.
+     * @type {number}
+     */
+    time = 0;
+
+    /**
+     * @deprecated Not used
+     * @type {String|null}
+     */
+    channel = "";
+
+    /**
+     * @type {number}
+     */
+    volume = 1;
+
+
+    /**
+     *
+     * @type {number|SoundTrackFlags}
+     */
+    flags = DEFAULT_FLAGS;
+
+    /**
+     *
+     * @param {SoundTrack} other
+     * @returns number
+     */
+    compare(other) {
+        const url = compareStrings(this.url, other.url);
+
+        if (url !== 0) {
+            return url;
+        }
+
+        const time = number_compare_ascending(this.time, other.time);
+
+        if (time !== 0) {
+            return time;
+        }
+
+        const channel = compareStrings(this.channel, other.channel);
+
+        if (channel !== 0) {
+            return channel;
+        }
+
+        const volume = number_compare_ascending(this.volume, other.volume);
+
+        if (volume !== 0) {
+            return volume;
+        }
+
+        const flags = number_compare_ascending(this.flags, other.flags);
+
+        if (flags !== 0) {
+            return flags;
+        }
+
+        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
+     * @return {boolean}
+     */
+    get loop() {
+        return this.getFlag(SoundTrackFlags.Loop);
+    }
+
+    /**
+     * @deprecated
+     * @param {boolean} v
+     */
+    set loop(v) {
+        this.writeFlag(SoundTrackFlags.Loop, v);
+    }
+
+    /**
+     * @deprecated
+     * @return {boolean}
+     */
+    get playing() {
+        return this.getFlag(SoundTrackFlags.Playing);
+    }
+
+    /**
+     * @deprecated
+     * @param {boolean} v
+     */
+    set playing(v) {
+        this.writeFlag(SoundTrackFlags.Playing, v);
+    }
+
+    /**
+     * @deprecated
+     * @return {boolean}
+     */
+    get startWhenReady() {
+        return this.getFlag(SoundTrackFlags.StartWhenReady);
+    }
+
+    /**
+     * @deprecated
+     * @param {boolean} v
+     */
+    set startWhenReady(v) {
+        this.writeFlag(SoundTrackFlags.StartWhenReady, v);
+    }
+
+    /**
+     *
+     * @param {SoundTrack} other
+     */
+    copy(other) {
+        this.url = other.url;
+        this.time = other.time;
+        this.volume = other.volume;
+        this.flags = other.flags;
+    }
+
+    /**
+     *
+     * @param {SoundTrack} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.url === other.url
+            && this.time === other.time
+            && this.volume === other.volume
+            && this.flags === other.flags
+            ;
+    }
+
+    /**
+     *
+     * @return {number}
+     */
+    hash() {
+        return combine_hash(
+            computeStringHash(this.url),
+            computeHashFloat(this.time),
+            computeHashFloat(this.volume),
+            this.flags
+        );
+    }
+
+    /**
+     *
+     * @return {SoundTrack}
+     */
+    clone() {
+        const r = new SoundTrack();
+
+        r.copy(this);
+
+        return r;
+    }
+
+    toJSON() {
+        return {
+            url: this.url,
+            loop: this.getFlag(SoundTrackFlags.Loop),
+            time: this.time,
+            volume: this.volume,
+            playing: this.getFlag(SoundTrackFlags.Playing),
+            startWhenReady: this.getFlag(SoundTrackFlags.StartWhenReady),
+            usingAssetAlias: this.getFlag(SoundTrackFlags.UsingAliasURL),
+            synchronized: this.getFlag(SoundTrackFlags.Synchronized)
+        };
+    }
+
+    fromJSON(
+        {
+            url,
+            loop = false,
+            time = 0,
+            volume = 1,
+            playing = false,
+            startWhenReady = true,
+            usingAssetAlias = false,
+            synchronized = false
+        }
+    ) {
+        assert.isString(url, 'url');
+
+        this.url = url;
+
+        this.writeFlag(SoundTrackFlags.Loop, loop);
+
+        this.writeFlag(SoundTrackFlags.UsingAliasURL, usingAssetAlias);
+
+        this.time = time;
+
+        this.volume = volume;
+
+        this.writeFlag(SoundTrackFlags.Playing, playing);
+
+        this.writeFlag(SoundTrackFlags.StartWhenReady, startWhenReady);
+
+        this.writeFlag(SoundTrackFlags.Synchronized, synchronized);
+    }
+
+    static fromJSON(json) {
+        const track = new SoundTrack();
+
+        track.fromJSON(json);
+
+        return track;
+    }
+
+}

package/src/engine/sound/sopra/legacy/SoundTrackFlags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SoundTrackFlags.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/legacy/SoundTrackFlags.js"],"names":[],"mappings":"8BAEU,MAAM"}

package/src/engine/sound/sopra/legacy/convertLegacySoundComponents.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Turns legacy sound components in a deserialized dataset into their native equivalents:
+ * `SoundEmitter` → {@link AudioEmitter}, `SoundController` → {@link AudioEventTrigger}. Old saves and
+ * old scenes keep loading — their bytes still deserialize through the registered legacy adapters — and
+ * this pass is what makes what they loaded playable by the native systems.
+ *
+ * **Hosts call this themselves, after deserialization.** It is deliberately not run inside the
+ * deserializer: a host owns its load pipeline, and `populateEngineSerializationRegistry` promises only
+ * to know how to read the bytes.
+ *
+ * What is deliberately dropped, because it never survived a load anyway:
+ * - `track.time` — the legacy runtime always started a restored track from zero.
+ * - `panningModel` — the v2 binary adapter never wrote it, so a binary-sourced emitter has the HRTF
+ *   default already, which is what a conversion produces.
+ *
+ * @param {EntityComponentDataset} dataset mutated in place
+ * @param {{knownBusIds?: Set<string>|string[]|null}} [options] the bus ids the target mixer actually
+ *        has. A legacy `channel` is a free string on decade-old authored data, and sopra's
+ *        `BusGraph.getInput` THROWS on an unknown id — so a stale channel name would fail the emitter's
+ *        first play. Given this set, an unrecognised channel is logged and rewritten to
+ *        `effects`, which is the contract the legacy runtime applied at play time. Omit it only when
+ *        the channel names are already known to be good. A host on the default mixer can pass
+ *        `Object.values(SopraDefaultBus)`.
+ * @returns {{emitters: number, triggers: number, discarded: number}} what the pass did: emitters and
+ *          triggers created, and legacy components removed without a replacement (nothing to play)
+ */
+export function convertLegacySoundComponents(dataset: EntityComponentDataset, { knownBusIds }?: {
+    knownBusIds?: Set<string> | string[] | null;
+}): {
+    emitters: number;
+    triggers: number;
+    discarded: number;
+};
+//# sourceMappingURL=convertLegacySoundComponents.d.ts.map