@woosh/meep-engine 2.155.0 → 2.156.0

package/src/engine/sound/sopra/definition/clip/RandomContainerAudioClip.d.ts

@@ -0,0 +1,101 @@
+/**
+ * On each trigger, plays one child chosen at weighted random, avoiding the last
+ * {@link avoid_repeating_last} choices. Selection and recent-history state live on the runtime
+ * {@link SopraPlaybackContext} (P1), seeded deterministically (see D5 in the implementation plan);
+ * never on this definition.
+ */
+export class RandomContainerAudioClip extends ContainerAudioClip {
+    /**
+     *
+     * @param {AbstractAudioClip[]} [children]
+     * @param {{avoidRepeatingLast?:number, weights?:number[]}} [options] `weights` is optional; any
+     *        child without a supplied (finite) weight defaults to 1.
+     * @returns {RandomContainerAudioClip}
+     */
+    static from(children?: AbstractAudioClip[], { avoidRepeatingLast, weights }?: {
+        avoidRepeatingLast?: number;
+        weights?: number[];
+    }): RandomContainerAudioClip;
+    /**
+     * Try not to repeat the last X played children.
+     * @type {number}
+     */
+    avoid_repeating_last: number;
+    /**
+     * Per-child selection weight, parallel to {@link ContainerAudioClip.children} — exactly one entry
+     * per child, kept in sync by {@link addChild}/{@link clearChildren}/{@link setWeights}. A higher
+     * weight makes a child proportionally more likely; the default is `1` (so an unconfigured
+     * container picks uniformly). A weight of `0` (or any non-positive value) means the child is
+     * NEVER picked.
+     *
+     * Degenerate-but-accepted: if EVERY weight is 0 the container still resolves — deterministically —
+     * to a single child (there is simply nothing to weight, so the pick collapses to a fixed index).
+     * That is a content-authoring mistake, not an engine fault; the engine stays well-defined. In
+     * other words, ten children all weighted 0 will "work", but you get the dog food.
+     * @type {number[]}
+     */
+    weights: number[];
+    /**
+     * Keeps {@link weights} parallel to the children: a newly added child defaults to weight 1.
+     * @override
+     * @param {AbstractAudioClip} clip
+     * @returns {this}
+     */
+    override addChild(clip: AbstractAudioClip): this;
+    /**
+     * Replace the per-child weights, normalising to exactly one entry per child: any missing or
+     * non-finite entry defaults to 1. A weight of 0 (or any non-positive value) means the child is
+     * never picked. See {@link weights}.
+     * @param {number[]} weights
+     * @returns {this}
+     */
+    setWeights(weights: number[]): this;
+    /**
+     *
+     * @param {RandomContainerAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other: RandomContainerAudioClip): boolean;
+    clone(): RandomContainerAudioClip;
+    toJSON(): {
+        gain: number;
+        pitch: number;
+        avoidRepeatingLast: number;
+        weights: number[];
+        children: {
+            type: string;
+            data: any;
+        }[];
+    };
+    fromJSON({ gain, pitch, avoidRepeatingLast, weights, children }: {
+        gain?: number;
+        pitch?: number;
+        avoidRepeatingLast?: number;
+        weights?: any[];
+        children?: any[];
+    }): void;
+    /**
+     * Pick a child index to play, avoiding the last {@link avoid_repeating_last} picks and weighting
+     * by {@link weights} (one weight per child; 0 = never picked). The recent-pick history is
+     * per-source mutable state, so it is kept on the supplied {@link SopraPlaybackContext} (keyed by
+     * this clip) rather than on this shared, immutable definition; this method owns both the selection
+     * algorithm and the maintenance of that history ring.
+     * @param {SopraPlaybackContext} playback
+     * @returns {number} chosen child index
+     */
+    pickChildIndex(playback: SopraPlaybackContext): number;
+    planTimeline(env: any, gainDb?: number, pitchCents?: number, offset?: number): {
+        plays: {
+            clip: SampleAudioClip;
+            offset: number;
+            gainDb: number;
+            pitchCents: number;
+        }[];
+        duration: number;
+    };
+}
+export namespace RandomContainerAudioClip {
+    let typeName: string;
+}
+import { ContainerAudioClip } from "./ContainerAudioClip.js";
+//# sourceMappingURL=RandomContainerAudioClip.d.ts.map

package/src/engine/sound/sopra/definition/clip/RandomContainerAudioClip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RandomContainerAudioClip.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/RandomContainerAudioClip.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH;IAqEI;;;;;;OAMG;IACH,uBALW,mBAAmB,oCACnB;QAAC,kBAAkB,CAAC,EAAC,MAAM,CAAC;QAAC,OAAO,CAAC,EAAC,MAAM,EAAE,CAAA;KAAC,GAE7C,wBAAwB,CAapC;IArFD;;;OAGG;IACH,sBAFU,MAAM,CAES;IAEzB;;;;;;;;;;;;OAYG;IACH,SAFU,MAAM,EAAE,CAEL;IAEb;;;;;OAKG;IACH,4CAFa,IAAI,CAQhB;IAWD;;;;;;OAMG;IACH,oBAHW,MAAM,EAAE,GACN,IAAI,CAgBhB;IAsBD;;;;OAIG;IACH,cAHW,wBAAwB,GACtB,OAAO,CAuBnB;IAkBD,kCAaC;IAED;;;;;;;;;MAQC;IAED;;;;;;aAQC;IAED;;;;;;;;OAQG;IACH,gDAFa,MAAM,CA6BlB;IAED;;;;;;;;MAQC;CACJ;;;;mCAhOkC,yBAAyB"}

package/src/engine/sound/sopra/definition/clip/RandomContainerAudioClip.js

@@ -0,0 +1,230 @@
+import { combine_hash } from "../../../../../core/collection/array/combine_hash.js";
+import { weightedRandomFromArray } from "../../../../../core/collection/array/weightedRandomFromArray.js";
+import { computeHashFloat } from "../../../../../core/primitives/numbers/computeHashFloat.js";
+import { ContainerAudioClip } from "./ContainerAudioClip.js";
+import { deserializeAudioClipFromJSON, serializeAudioClipToJSON } from "../../serialization/sopraJSON.js";
+
+/**
+ * On each trigger, plays one child chosen at weighted random, avoiding the last
+ * {@link avoid_repeating_last} choices. Selection and recent-history state live on the runtime
+ * {@link SopraPlaybackContext} (P1), seeded deterministically (see D5 in the implementation plan);
+ * never on this definition.
+ */
+export class RandomContainerAudioClip extends ContainerAudioClip {
+
+    /**
+     * Try not to repeat the last X played children.
+     * @type {number}
+     */
+    avoid_repeating_last = 1;
+
+    /**
+     * Per-child selection weight, parallel to {@link ContainerAudioClip.children} — exactly one entry
+     * per child, kept in sync by {@link addChild}/{@link clearChildren}/{@link setWeights}. A higher
+     * weight makes a child proportionally more likely; the default is `1` (so an unconfigured
+     * container picks uniformly). A weight of `0` (or any non-positive value) means the child is
+     * NEVER picked.
+     *
+     * Degenerate-but-accepted: if EVERY weight is 0 the container still resolves — deterministically —
+     * to a single child (there is simply nothing to weight, so the pick collapses to a fixed index).
+     * That is a content-authoring mistake, not an engine fault; the engine stays well-defined. In
+     * other words, ten children all weighted 0 will "work", but you get the dog food.
+     * @type {number[]}
+     */
+    weights = [];
+
+    /**
+     * Keeps {@link weights} parallel to the children: a newly added child defaults to weight 1.
+     * @override
+     * @param {AbstractAudioClip} clip
+     * @returns {this}
+     */
+    addChild(clip) {
+        super.addChild(clip);
+
+        this.weights.push(1);
+
+        return this;
+    }
+
+    /**
+     * @override drops the parallel weights along with the children.
+     */
+    clearChildren() {
+        super.clearChildren();
+
+        this.weights = [];
+    }
+
+    /**
+     * Replace the per-child weights, normalising to exactly one entry per child: any missing or
+     * non-finite entry defaults to 1. A weight of 0 (or any non-positive value) means the child is
+     * never picked. See {@link weights}.
+     * @param {number[]} weights
+     * @returns {this}
+     */
+    setWeights(weights) {
+        const n = this.children.length;
+
+        const normalized = new Array(n);
+
+        for (let i = 0; i < n; i++) {
+            const v = weights[i];
+
+            normalized[i] = Number.isFinite(v) ? v : 1;
+        }
+
+        this.weights = normalized;
+
+        return this;
+    }
+
+    /**
+     *
+     * @param {AbstractAudioClip[]} [children]
+     * @param {{avoidRepeatingLast?:number, weights?:number[]}} [options] `weights` is optional; any
+     *        child without a supplied (finite) weight defaults to 1.
+     * @returns {RandomContainerAudioClip}
+     */
+    static from(children = [], { avoidRepeatingLast = 1, weights } = {}) {
+        const r = new RandomContainerAudioClip();
+
+        r.addChildren(children); // each child defaults to weight 1
+        r.avoid_repeating_last = avoidRepeatingLast;
+
+        if (weights !== undefined) {
+            r.setWeights(weights);
+        }
+
+        return r;
+    }
+
+    /**
+     *
+     * @param {RandomContainerAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (!super.equals(other)) { // gain/pitch + children
+            return false;
+        }
+
+        if (this.avoid_repeating_last !== other.avoid_repeating_last) {
+            return false;
+        }
+
+        // weights are always parallel to children, so a length mismatch implies a child-count mismatch
+        if (this.weights.length !== other.weights.length) {
+            return false;
+        }
+
+        for (let i = 0; i < this.weights.length; i++) {
+            if (this.weights[i] !== other.weights[i]) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    hash() {
+        let h = combine_hash(super.hash(), this.avoid_repeating_last);
+
+        const children = this.children;
+        for (let i = 0; i < children.length; i++) {
+            h = combine_hash(h, children[i].hash());
+        }
+
+        const weights = this.weights;
+        for (let i = 0; i < weights.length; i++) {
+            h = combine_hash(h, computeHashFloat(weights[i]));
+        }
+
+        return h;
+    }
+
+    clone() {
+        const r = new RandomContainerAudioClip();
+
+        r.copyBaseFrom(this);
+        r.avoid_repeating_last = this.avoid_repeating_last;
+
+        for (let i = 0; i < this.children.length; i++) {
+            r.addChild(this.children[i].clone());
+        }
+
+        r.setWeights(this.weights);
+
+        return r;
+    }
+
+    toJSON() {
+        return {
+            gain: this.gain,
+            pitch: this.pitch,
+            avoidRepeatingLast: this.avoid_repeating_last,
+            weights: this.weights,
+            children: this.children.map(serializeAudioClipToJSON)
+        };
+    }
+
+    fromJSON({ gain = 0, pitch = 0, avoidRepeatingLast = 1, weights = [], children = [] }) {
+        this.gain = gain;
+        this.pitch = pitch;
+        this.avoid_repeating_last = avoidRepeatingLast;
+
+        this.clearChildren();
+        this.addChildren(children.map(deserializeAudioClipFromJSON));
+        this.setWeights(weights); // normalise to one weight per child (older data may be empty/short)
+    }
+
+    /**
+     * Pick a child index to play, avoiding the last {@link avoid_repeating_last} picks and weighting
+     * by {@link weights} (one weight per child; 0 = never picked). The recent-pick history is
+     * per-source mutable state, so it is kept on the supplied {@link SopraPlaybackContext} (keyed by
+     * this clip) rather than on this shared, immutable definition; this method owns both the selection
+     * algorithm and the maintenance of that history ring.
+     * @param {SopraPlaybackContext} playback
+     * @returns {number} chosen child index
+     */
+    pickChildIndex(playback) {
+        const children = this.children;
+        const n = children.length;
+
+        // can't avoid every option — cap so at least one candidate remains
+        const avoid = Math.min(this.avoid_repeating_last, n - 1);
+
+        const recent = playback.getState(this, () => []);
+
+        const candidates = [];
+        for (let i = 0; i < n; i++) {
+            if (recent.indexOf(i) === -1) {
+                candidates.push(i);
+            }
+        }
+
+        // weighted pick among the surviving candidates (weight looked up by child index). With the
+        // default all-1 weights this is a uniform draw; a 0 weight removes that child from contention.
+        const weights = this.weights;
+        const index = weightedRandomFromArray(candidates, playback.random, i => weights[i]);
+
+        recent.push(index);
+        while (recent.length > avoid) {
+            recent.shift();
+        }
+
+        return index;
+    }
+
+    planTimeline(env, gainDb = 0, pitchCents = 0, offset = 0) {
+        if (this.children.length === 0) {
+            return { plays: [], duration: 0 };
+        }
+
+        const index = this.pickChildIndex(env.playback);
+
+        return this.children[index].planTimeline(env, gainDb + this.gain, pitchCents + this.pitch, offset);
+    }
+}
+
+RandomContainerAudioClip.typeName = "SopraRandomContainerAudioClip";

package/src/engine/sound/sopra/definition/clip/RandomContainerAudioClipSerializationAdapter.d.ts

@@ -0,0 +1,17 @@
+export class RandomContainerAudioClipSerializationAdapter extends ObjectBasedClassSerializationAdapter {
+    klass: typeof RandomContainerAudioClip;
+    version: number;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {RandomContainerAudioClip} value
+     */
+    serialize(buffer: BinaryBuffer, value: RandomContainerAudioClip): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {RandomContainerAudioClip} value
+     */
+    deserialize(buffer: BinaryBuffer, value: RandomContainerAudioClip): void;
+}
+import { ObjectBasedClassSerializationAdapter } from "../../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
+import { RandomContainerAudioClip } from "./RandomContainerAudioClip.js";
+//# sourceMappingURL=RandomContainerAudioClipSerializationAdapter.d.ts.map

package/src/engine/sound/sopra/definition/clip/RandomContainerAudioClipSerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RandomContainerAudioClipSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/RandomContainerAudioClipSerializationAdapter.js"],"names":[],"mappings":"AAGA;IACI,uCAAiC;IACjC,gBAAY;IAEZ;;;OAGG;IACH,uCAFW,wBAAwB,QAkBlC;IAED;;;OAGG;IACH,yCAFW,wBAAwB,QAqBlC;CACJ;qDArDoD,+EAA+E;yCAC3F,+BAA+B"}

package/src/engine/sound/sopra/definition/clip/RandomContainerAudioClipSerializationAdapter.js

@@ -0,0 +1,54 @@
+import { ObjectBasedClassSerializationAdapter } from "../../../../ecs/storage/binary/object/ObjectBasedClassSerializationAdapter.js";
+import { RandomContainerAudioClip } from "./RandomContainerAudioClip.js";
+
+export class RandomContainerAudioClipSerializationAdapter extends ObjectBasedClassSerializationAdapter {
+    klass = RandomContainerAudioClip;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {RandomContainerAudioClip} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat32(value.gain);
+        buffer.writeFloat32(value.pitch);
+        buffer.writeUintVar(value.avoid_repeating_last);
+
+        const weights = value.weights;
+        buffer.writeUintVar(weights.length);
+        for (let i = 0; i < weights.length; i++) {
+            buffer.writeFloat32(weights[i]);
+        }
+
+        const children = value.children;
+        buffer.writeUintVar(children.length);
+        for (let i = 0; i < children.length; i++) {
+            this.objectAdapter.serialize(buffer, children[i]);
+        }
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {RandomContainerAudioClip} value
+     */
+    deserialize(buffer, value) {
+        value.gain = buffer.readFloat32();
+        value.pitch = buffer.readFloat32();
+        value.avoid_repeating_last = buffer.readUintVar();
+
+        const weightCount = buffer.readUintVar();
+        const weights = [];
+        for (let i = 0; i < weightCount; i++) {
+            weights.push(buffer.readFloat32());
+        }
+
+        const childCount = buffer.readUintVar();
+        value.clearChildren();
+        for (let i = 0; i < childCount; i++) {
+            value.addChild(this.objectAdapter.deserialize(buffer));
+        }
+
+        // normalise to one weight per child (older payloads may carry an empty/short weights array)
+        value.setWeights(weights);
+    }
+}

package/src/engine/sound/sopra/definition/clip/SampleAudioClip.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The only buffer-referencing clip — a leaf that plays a single audio asset.
+ * Replaces the "definition" half of the legacy {@link SoundTrack} (which conflated definition,
+ * live node and playback state).
+ */
+export class SampleAudioClip extends AbstractAudioClip {
+    /**
+     *
+     * @param {string} url
+     * @param {{usingAlias?:boolean, loop?:boolean, gain?:number, pitch?:number, loopStart?:number, loopEnd?:number, pitchRandom?:number, gainRandom?:number}} [options]
+     * @returns {SampleAudioClip}
+     */
+    static from(url: string, { usingAlias, loop, gain, pitch, loopStart, loopEnd, pitchRandom, gainRandom }?: {
+        usingAlias?: boolean;
+        loop?: boolean;
+        gain?: number;
+        pitch?: number;
+        loopStart?: number;
+        loopEnd?: number;
+        pitchRandom?: number;
+        gainRandom?: number;
+    }): SampleAudioClip;
+    /**
+     * Asset path, or asset alias if {@link usingAlias} is set.
+     * @type {string}
+     */
+    url: string;
+    /**
+     * When true, {@link url} is an asset alias to be resolved via the AssetManager rather than a path.
+     * @type {boolean}
+     */
+    usingAlias: boolean;
+    /**
+     * @type {boolean}
+     */
+    loop: boolean;
+    /**
+     * Loop region start, in seconds. Only meaningful when {@link loop} is set. 0 = start of buffer.
+     * @type {number}
+     */
+    loopStart: number;
+    /**
+     * Loop region end, in seconds. Only meaningful when {@link loop} is set. 0 = end of buffer.
+     * @type {number}
+     */
+    loopEnd: number;
+    /**
+     * Per-trigger pitch randomization, applied as a symmetric +/- offset in cents.
+     * @type {number}
+     */
+    pitchRandom: number;
+    /**
+     * Per-trigger gain randomization, applied as a symmetric +/- offset in decibels.
+     * @type {number}
+     */
+    gainRandom: number;
+    /**
+     *
+     * @param {SampleAudioClip} other
+     * @returns {boolean}
+     */
+    equals(other: SampleAudioClip): boolean;
+    /**
+     * @returns {SampleAudioClip}
+     */
+    clone(): SampleAudioClip;
+    toJSON(): {
+        gain: number;
+        pitch: number;
+        url: string;
+        usingAlias: boolean;
+        loop: boolean;
+        loopStart: number;
+        loopEnd: number;
+        pitchRandom: number;
+        gainRandom: number;
+    };
+    fromJSON({ gain, pitch, url, usingAlias, loop, loopStart, loopEnd, pitchRandom, gainRandom }: {
+        gain?: number;
+        pitch?: number;
+        url?: string;
+        usingAlias?: boolean;
+        loop?: boolean;
+        loopStart?: number;
+        loopEnd?: number;
+        pitchRandom?: number;
+        gainRandom?: number;
+    }): void;
+    planTimeline(env: any, gainDb?: number, pitchCents?: number, offset?: number): {
+        plays: {
+            clip: this;
+            offset: number;
+            gainDb: number;
+            pitchCents: number;
+        }[];
+        duration: any;
+    };
+}
+export namespace SampleAudioClip {
+    let typeName: string;
+}
+import { AbstractAudioClip } from "./AbstractAudioClip.js";
+//# sourceMappingURL=SampleAudioClip.d.ts.map

package/src/engine/sound/sopra/definition/clip/SampleAudioClip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SampleAudioClip.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/sound/sopra/definition/clip/SampleAudioClip.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH;IA2CI;;;;;OAKG;IACH,iBAJW,MAAM,mFACN;QAAC,UAAU,CAAC,EAAC,OAAO,CAAC;QAAC,IAAI,CAAC,EAAC,OAAO,CAAC;QAAC,IAAI,CAAC,EAAC,MAAM,CAAC;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,OAAO,CAAC,EAAC,MAAM,CAAC;QAAC,WAAW,CAAC,EAAC,MAAM,CAAC;QAAC,UAAU,CAAC,EAAC,MAAM,CAAA;KAAC,GAC5I,eAAe,CAyB3B;IAtED;;;OAGG;IACH,KAFU,MAAM,CAEP;IAET;;;OAGG;IACH,YAFU,OAAO,CAEE;IAEnB;;OAEG;IACH,MAFU,OAAO,CAEJ;IAEb;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,YAFU,MAAM,CAED;IAiCf;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CAWnB;IAkBD;;OAEG;IACH,SAFa,eAAe,CAe3B;IAED;;;;;;;;;;MAYC;IAED;;;;;;;;;;aAUC;IAED;;;;;;;;MAkBC;CAUJ;;;;kCAzLiC,wBAAwB"}