@datamoc/mw_games 0.42.0 → 0.44.2

package/dist/audio/Settings.d.ts

@@ -0,0 +1,99 @@
+import type { AudioBus, BusKind } from './Channels.ts';
+/** the television standard a retro machine ran at: it sets the clock its music was timed by */
+export type AudioRegion = 'pal' | 'ntsc';
+/**
+ * How a machine profile's output stage is treated: `faithful` keeps what the hardware did
+ * (DC offset, aliasing and all), `clean` removes the DC and softens the top end.
+ */
+export type OutputStage = 'faithful' | 'clean';
+/** player-facing audio settings as plain data, the shape a save or a settings file holds */
+export interface AudioSettingsData {
+    /** volume per bus kind, 0 to 100 like every other volume in the bus API */
+    busVolumes: Record<BusKind, number>;
+    /** the MIDI engine name content is voiced by first, or null for the internal path */
+    preferredEngine: string | null;
+    region: AudioRegion;
+    outputStage: OutputStage;
+    /** whether caption text is shown for captioned sounds */
+    captions: boolean;
+    /** dynamics control, 0 (untouched) to 1 (a soft limiter at full), for loudness comfort */
+    dynamics: number;
+    /** softening of bright or broadband sounds, 0 (untouched) to 1 (most softened) */
+    soften: number;
+}
+/**
+ * The playback rate a tune authored for one region runs at on the other: a PAL machine's
+ * 50 Hz clock against NTSC's 60 Hz makes the same file slower and lower, which is the
+ * difference a player who grew up with the other standard hears first.
+ *
+ * @example
+ * ```ts
+ * import { regionPlaybackRate } from '@datamoc/mw_games/audio';
+ *
+ * console.log(regionPlaybackRate('pal', 'ntsc')); // 0.8333..., slower on PAL
+ * console.log(regionPlaybackRate('ntsc', 'ntsc')); // 1, its own region
+ * ```
+ */
+export declare function regionPlaybackRate(region: AudioRegion, authored?: AudioRegion): number;
+/**
+ * The low-pass cutoff, in hertz, that a `soften` amount asks an output stage for: nothing
+ * at 0, down to a muffled 3.5 kHz at 1, never above what the sample rate can represent.
+ *
+ * @example
+ * ```ts
+ * import { softenCutoff } from '@datamoc/mw_games/audio';
+ *
+ * console.log(softenCutoff(0, 44100)); // 18000, effectively open
+ * console.log(softenCutoff(1, 44100) < softenCutoff(0.5, 44100)); // true, more soften, lower cutoff
+ * ```
+ */
+export declare function softenCutoff(soften: number, sampleRate: number): number;
+/**
+ * One sample through the dynamics control: at 0 the sample is untouched, and as the amount
+ * rises a soft knee pulls peaks toward full scale without ever passing it, so a loud game
+ * gets quieter peaks rather than clipped ones.
+ *
+ * @example
+ * ```ts
+ * import { dynamicsLimit } from '@datamoc/mw_games/audio';
+ *
+ * console.log(dynamicsLimit(0.5, 0)); // 0.5, untouched
+ * console.log(dynamicsLimit(4, 1) < 1); // true, a hot sample is pulled under full scale
+ * ```
+ */
+export declare function dynamicsLimit(sample: number, dynamics: number): number;
+/**
+ * The player's audio settings in one place, over the pieces that already exist: bus
+ * volumes apply to an `AudioBus` (`applyToBus`), the preferred engine names what
+ * `resolveMidiSynth` is asked for first, the region and output stage describe the machine
+ * profile a retro package renders for, and captions, dynamics and soften are the
+ * accessibility dials. Everything clamps on the way in, and `snapshot`/`restore` round-trip
+ * the plain-data shape a settings screen persists.
+ *
+ * @example
+ * ```ts
+ * import { AudioSettings } from '@datamoc/mw_games/audio';
+ *
+ * const settings = new AudioSettings({ preferredEngine: 'retro:mt32', soften: 0.4 });
+ * settings.setBusVolume('se', 130);
+ * console.log(settings.snapshot().busVolumes.se); // 100, clamped
+ * ```
+ */
+export declare class AudioSettings {
+    private data;
+    constructor(initial?: Partial<AudioSettingsData>);
+    /** a copy of the current settings, safe to store */
+    snapshot(): AudioSettingsData;
+    /** takes settings in, clamping every dial; a partial update keeps the rest */
+    restore(data: Partial<AudioSettingsData>): void;
+    setBusVolume(kind: BusKind, volume: number): void;
+    /** pushes the per-bus volumes onto a bus's mixer, the settings' one live connection */
+    applyToBus(bus: AudioBus): void;
+    /** the rate content authored for `authored` should play at under this region */
+    playbackRate(authored?: AudioRegion): number;
+    /** the cutoff the current soften amount (and a clean stage's extra softening) asks for */
+    cutoff(sampleRate: number): number;
+    /** one sample through the current dynamics amount */
+    limit(sample: number): number;
+}
+//# sourceMappingURL=Settings.d.ts.map

package/dist/audio/Settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../../src/audio/Settings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAEvD,+FAA+F;AAC/F,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AAE/C,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACpC,qFAAqF;IACrF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAC;IAClB,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAE,WAAoB,GAAG,MAAM,CAG9F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAIvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,IAAI,CAAoB;IAEhC,YAAY,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,EAWnD;IAED,oDAAoD;IACpD,QAAQ,IAAI,iBAAiB,CAE5B;IAED,8EAA8E;IAC9E,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAY9C;IAED,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAEhD;IAED,uFAAuF;IACvF,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAI9B;IAED,gFAAgF;IAChF,YAAY,CAAC,QAAQ,GAAE,WAAoB,GAAG,MAAM,CAEnD;IAED,0FAA0F;IAC1F,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGjC;IAED,qDAAqD;IACrD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5B;CACD"}

package/dist/audio/Settings.js

@@ -0,0 +1,134 @@
+import { clamp } from '../core/Math.js';
+/**
+ * The playback rate a tune authored for one region runs at on the other: a PAL machine's
+ * 50 Hz clock against NTSC's 60 Hz makes the same file slower and lower, which is the
+ * difference a player who grew up with the other standard hears first.
+ *
+ * @example
+ * ```ts
+ * import { regionPlaybackRate } from '@datamoc/mw_games/audio';
+ *
+ * console.log(regionPlaybackRate('pal', 'ntsc')); // 0.8333..., slower on PAL
+ * console.log(regionPlaybackRate('ntsc', 'ntsc')); // 1, its own region
+ * ```
+ */
+export function regionPlaybackRate(region, authored = 'ntsc') {
+    if (region === authored)
+        return 1;
+    return region === 'pal' ? 50 / 60 : 60 / 50;
+}
+/**
+ * The low-pass cutoff, in hertz, that a `soften` amount asks an output stage for: nothing
+ * at 0, down to a muffled 3.5 kHz at 1, never above what the sample rate can represent.
+ *
+ * @example
+ * ```ts
+ * import { softenCutoff } from '@datamoc/mw_games/audio';
+ *
+ * console.log(softenCutoff(0, 44100)); // 18000, effectively open
+ * console.log(softenCutoff(1, 44100) < softenCutoff(0.5, 44100)); // true, more soften, lower cutoff
+ * ```
+ */
+export function softenCutoff(soften, sampleRate) {
+    const amount = clamp(soften, 0, 1);
+    const cutoff = 18000 * (3500 / 18000) ** amount;
+    return Math.min(cutoff, sampleRate / 2);
+}
+/**
+ * One sample through the dynamics control: at 0 the sample is untouched, and as the amount
+ * rises a soft knee pulls peaks toward full scale without ever passing it, so a loud game
+ * gets quieter peaks rather than clipped ones.
+ *
+ * @example
+ * ```ts
+ * import { dynamicsLimit } from '@datamoc/mw_games/audio';
+ *
+ * console.log(dynamicsLimit(0.5, 0)); // 0.5, untouched
+ * console.log(dynamicsLimit(4, 1) < 1); // true, a hot sample is pulled under full scale
+ * ```
+ */
+export function dynamicsLimit(sample, dynamics) {
+    const amount = clamp(dynamics, 0, 1);
+    if (amount === 0)
+        return sample;
+    const limited = Math.tanh(sample);
+    return sample * (1 - amount) + limited * amount;
+}
+/**
+ * The player's audio settings in one place, over the pieces that already exist: bus
+ * volumes apply to an `AudioBus` (`applyToBus`), the preferred engine names what
+ * `resolveMidiSynth` is asked for first, the region and output stage describe the machine
+ * profile a retro package renders for, and captions, dynamics and soften are the
+ * accessibility dials. Everything clamps on the way in, and `snapshot`/`restore` round-trip
+ * the plain-data shape a settings screen persists.
+ *
+ * @example
+ * ```ts
+ * import { AudioSettings } from '@datamoc/mw_games/audio';
+ *
+ * const settings = new AudioSettings({ preferredEngine: 'retro:mt32', soften: 0.4 });
+ * settings.setBusVolume('se', 130);
+ * console.log(settings.snapshot().busVolumes.se); // 100, clamped
+ * ```
+ */
+export class AudioSettings {
+    constructor(initial = {}) {
+        this.data = {
+            busVolumes: { bgm: 90, bgs: 90, me: 90, se: 90 },
+            preferredEngine: null,
+            region: 'ntsc',
+            outputStage: 'faithful',
+            captions: false,
+            dynamics: 0,
+            soften: 0,
+        };
+        this.restore(initial);
+    }
+    /** a copy of the current settings, safe to store */
+    snapshot() {
+        return { ...this.data, busVolumes: { ...this.data.busVolumes } };
+    }
+    /** takes settings in, clamping every dial; a partial update keeps the rest */
+    restore(data) {
+        if (data.busVolumes) {
+            for (const kind of Object.keys(data.busVolumes)) {
+                this.data.busVolumes[kind] = clamp(data.busVolumes[kind], 0, 100);
+            }
+        }
+        if (data.preferredEngine !== undefined)
+            this.data.preferredEngine = data.preferredEngine;
+        if (data.region !== undefined)
+            this.data.region = data.region;
+        if (data.outputStage !== undefined)
+            this.data.outputStage = data.outputStage;
+        if (data.captions !== undefined)
+            this.data.captions = data.captions;
+        if (data.dynamics !== undefined)
+            this.data.dynamics = clamp(data.dynamics, 0, 1);
+        if (data.soften !== undefined)
+            this.data.soften = clamp(data.soften, 0, 1);
+    }
+    setBusVolume(kind, volume) {
+        this.data.busVolumes[kind] = clamp(volume, 0, 100);
+    }
+    /** pushes the per-bus volumes onto a bus's mixer, the settings' one live connection */
+    applyToBus(bus) {
+        for (const kind of Object.keys(this.data.busVolumes)) {
+            bus.setMixer(kind, { volume: this.data.busVolumes[kind] / 100 });
+        }
+    }
+    /** the rate content authored for `authored` should play at under this region */
+    playbackRate(authored = 'ntsc') {
+        return regionPlaybackRate(this.data.region, authored);
+    }
+    /** the cutoff the current soften amount (and a clean stage's extra softening) asks for */
+    cutoff(sampleRate) {
+        const extra = this.data.outputStage === 'clean' ? 0.25 : 0;
+        return softenCutoff(clamp(this.data.soften + extra, 0, 1), sampleRate);
+    }
+    /** one sample through the current dynamics amount */
+    limit(sample) {
+        return dynamicsLimit(sample, this.data.dynamics);
+    }
+}
+//# sourceMappingURL=Settings.js.map

package/dist/audio/Settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Settings.js","sourceRoot":"","sources":["../../src/audio/Settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AA4BxC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAmB,EAAE,QAAQ,GAAgB,MAAM;IACrF,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,UAAkB;IAC9D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,KAAK,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,MAAM,CAAC;IAChD,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,QAAgB;IAC7D,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,aAAa;IAGzB,YAAY,OAAO,GAA+B,EAAE;QACnD,IAAI,CAAC,IAAI,GAAG;YACX,UAAU,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;YAChD,eAAe,EAAE,IAAI;YACrB,MAAM,EAAE,MAAM;YACd,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,KAAK;YACf,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,CAAC;SACT,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;IAED,oDAAoD;IACpD,QAAQ;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;IAClE,CAAC;IAED,8EAA8E;IAC9E,OAAO,CAAC,IAAgC;QACvC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAc,EAAE,CAAC;gBAC9D,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;YACnE,CAAC;QACF,CAAC;QACD,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;QACzF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC9D,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QAC7E,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QACpE,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACjF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,YAAY,CAAC,IAAa,EAAE,MAAc;QACzC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,uFAAuF;IACvF,UAAU,CAAC,GAAa;QACvB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAc,EAAE,CAAC;YACnE,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAClE,CAAC;IACF,CAAC;IAED,gFAAgF;IAChF,YAAY,CAAC,QAAQ,GAAgB,MAAM;QAC1C,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACvD,CAAC;IAED,0FAA0F;IAC1F,MAAM,CAAC,UAAkB;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACxE,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,MAAc;QACnB,OAAO,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;CACD"}

package/dist/audio/Sfx.d.ts

@@ -0,0 +1,148 @@
+/**
+ * A sound effect described as data and voiced by a synthesis backend instead of read from a
+ * file. mwg owns the shape the game and the mixer need (an id, a priority, what a second
+ * trigger does, a caption); whatever else a backend wants (chip, voices, curves) rides along
+ * untouched, so a retro-instrument package can carry its own `SfxDefinition` through unchanged.
+ */
+export interface SfxDefinition {
+    id: string;
+    /** higher cuts lower when the mixer is full; 0 when omitted */
+    priority?: number;
+    /** what a second trigger does while the first still sounds: `'restart'` (the default), `'ignore'`, or `'layer'` */
+    retrigger?: 'restart' | 'ignore' | 'layer';
+    /** shown by a captioning overlay each time the effect plays */
+    caption?: string;
+    [backendData: string]: unknown;
+}
+/** what a play carries into the backend: the mix mwg computed and a seed that makes any randomness reproducible */
+export interface SfxPlayOptions {
+    /** 0 to 1, after distance and the sound's own volume */
+    gain: number;
+    /** -1 (left) to 1 (right) */
+    pan: number;
+    /** playback ratio, 1 unchanged */
+    pitch: number;
+    /** the only source of chance an effect may use */
+    seed: number;
+}
+/** one effect sounding on a backend */
+export interface SfxVoice {
+    stop(): void;
+    /** false once it has finished by itself or been stopped */
+    readonly active: boolean;
+}
+/** the synthesis side: a chip engine that can voice an effect, wherever it keeps its voices */
+export interface SfxBackend {
+    /** returns null when it cannot voice the effect (no free channel, unknown chip), which is not an error */
+    play(definition: SfxDefinition, options: SfxPlayOptions): SfxVoice | null;
+}
+/** effects by id, so a sound can be made from an id the content named */
+export declare class SfxBank {
+    private readonly definitions;
+    constructor(definitions?: Iterable<SfxDefinition>);
+    define(definition: SfxDefinition): void;
+    has(id: string): boolean;
+    get(id: string): SfxDefinition;
+    ids(): string[];
+}
+/** a granted slot in the arbiter; `release` frees it */
+export interface SfxGrant {
+    release(): void;
+}
+/**
+ * The shared voice limit between chip effects and the bus's `'se'` jingles: both ask here before
+ * they sound, and when the limit is reached the lowest-priority voice (the oldest among equals)
+ * is cut for a new one of equal or higher priority; a new one below everything sounding is
+ * refused. One arbiter handed to a bus and to every `SfxSound` makes them a single pool.
+ *
+ * @example
+ * ```ts
+ * import { SfxArbiter } from '@datamoc/mw_games/audio';
+ *
+ * const arbiter = new SfxArbiter({ maxVoices: 2 });
+ * const a = arbiter.request(1, () => console.log('a cut'));
+ * arbiter.request(1, () => console.log('b cut'));
+ * arbiter.request(5, () => console.log('c cut')); // cuts a, the oldest of the lowest priority
+ * a?.release();
+ * ```
+ */
+export declare class SfxArbiter {
+    private readonly maxVoices;
+    private readonly voices;
+    constructor(options?: {
+        maxVoices?: number;
+    });
+    get active(): number;
+    /**
+     * Asks for a slot. `stop` cuts the voice when a better one needs its place; `active` says
+     * whether it still sounds, so a voice that ended by itself frees its slot for any asker, not
+     * only for the sound that owned it.
+     */
+    request(priority: number, stop: () => void, active?: () => boolean): SfxGrant | null;
+}
+/**
+ * A reproducible seed for an effect: the same id on the same game frame (and the same ordinal
+ * within that frame) always gives the same number, so a replay or a lockstep peer hears exactly
+ * what the original run heard, and audio never perturbs the simulation.
+ *
+ * @example
+ * ```ts
+ * import { sfxSeed } from '@datamoc/mw_games/audio';
+ *
+ * sfxSeed('arrow', 120) === sfxSeed('arrow', 120); // true
+ * ```
+ */
+export declare function sfxSeed(id: string, frame: number, ordinal?: number): number;
+export interface SfxSoundOptions {
+    /** where an effect given by id is looked up */
+    bank?: SfxBank;
+    /** the shared voice limit; none means a voice is never cut for another */
+    arbiter?: SfxArbiter;
+    /** the game's own frame counter, never the wall clock, so seeds repeat across runs; 0 when omitted */
+    frame?: () => number;
+    /** shown with each play when the definition has no caption of its own */
+    caption?: string;
+    /** level, 0 to 1; 1 when omitted */
+    volume?: number;
+}
+/**
+ * The data-driven counterpart of `Sound`: it plays an `SfxDefinition` (or the id of one in a
+ * bank) through a backend, with the same `play(gain, pitch)` shape so a `SoundSource` can
+ * attenuate it, and a pan on top. It applies the definition's retrigger rule, asks the shared
+ * arbiter for a voice, fires the caption, and hands the backend a deterministic seed.
+ *
+ * @example
+ * ```ts
+ * import { SfxArbiter, SfxBank, SfxSound, SoundSource, AudioListener, type SfxBackend } from '@datamoc/mw_games/audio';
+ *
+ * declare const chip: SfxBackend;
+ *
+ * const bank = new SfxBank([{ id: 'arrow', priority: 5, caption: 'an arrow flies' }]);
+ * const arrow = new SfxSound(chip, 'arrow', { bank, arbiter: new SfxArbiter(), frame: () => 0 });
+ * new SoundSource(arrow, { x: 3, y: 4 }).playFor(new AudioListener());
+ * ```
+ */
+export declare class SfxSound {
+    volume: number;
+    /** how many plays reached the backend, for a test to assert on without a speaker */
+    plays: number;
+    private readonly backend;
+    private readonly definition;
+    private readonly options;
+    private readonly live;
+    private suspended_;
+    private lastFrame;
+    private ordinal;
+    constructor(backend: SfxBackend, effect: SfxDefinition | string, options?: SfxSoundOptions);
+    get isSuspended(): boolean;
+    /** voices that still sound */
+    get activeVoices(): number;
+    /** plays the effect; returns false when it was ignored, refused by the arbiter or the backend had no voice */
+    play(gain?: number, pitch?: number, pan?: number): boolean;
+    stopAll(): void;
+    suspend(): void;
+    resume(): void;
+    /** drops voices that finished by themselves, returning their arbiter slots */
+    private prune;
+}
+//# sourceMappingURL=Sfx.d.ts.map

package/dist/audio/Sfx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sfx.d.ts","sourceRoot":"","sources":["../../src/audio/Sfx.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mHAAmH;IACnH,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3C,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED,mHAAmH;AACnH,MAAM,WAAW,cAAc;IAC9B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,QAAQ;IACxB,IAAI,IAAI,IAAI,CAAC;IACb,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED,+FAA+F;AAC/F,MAAM,WAAW,UAAU;IAC1B,0GAA0G;IAC1G,IAAI,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,GAAG,QAAQ,GAAG,IAAI,CAAC;CAC1E;AAED,yEAAyE;AACzE,qBAAa,OAAO;IACnB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAEhE,YAAY,WAAW,GAAE,QAAQ,CAAC,aAAa,CAAM,EAEpD;IAED,MAAM,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI,CAGtC;IAED,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvB;IAED,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,CAI7B;IAED,GAAG,IAAI,MAAM,EAAE,CAEd;CACD;AAED,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACxB,OAAO,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuE;IAE9F,YAAY,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,EAE/C;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,EAAE,MAAM,GAAE,MAAM,OAAoB,GAAG,QAAQ,GAAG,IAAI,CAmB/F;CACD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,MAAM,CAYtE;AAED,MAAM,WAAW,eAAe;IAC/B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,QAAQ;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,KAAK,SAAK;IAEV,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqD;IAC1E,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,OAAO,CAAK;IAEpB,YAAY,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,EAAE,OAAO,GAAE,eAAoB,EAU7F;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,8BAA8B;IAC9B,IAAI,YAAY,IAAI,MAAM,CAGzB;IAED,8GAA8G;IAC9G,IAAI,CAAC,IAAI,SAAI,EAAE,KAAK,SAAI,EAAE,GAAG,SAAI,GAAG,OAAO,CAoC1C;IAED,OAAO,IAAI,IAAI,CAKd;IAED,OAAO,IAAI,IAAI,CAGd;IAED,MAAM,IAAI,IAAI,CAEb;IAED,8EAA8E;IAC9E,OAAO,CAAC,KAAK;CAQb"}

package/dist/audio/Sfx.js

@@ -0,0 +1,213 @@
+import { onCaption } from './Captions.js';
+/** effects by id, so a sound can be made from an id the content named */
+export class SfxBank {
+    constructor(definitions = []) {
+        this.definitions = new Map();
+        for (const definition of definitions)
+            this.define(definition);
+    }
+    define(definition) {
+        if (!definition.id)
+            throw new Error('a sound effect needs an id');
+        this.definitions.set(definition.id, definition);
+    }
+    has(id) {
+        return this.definitions.has(id);
+    }
+    get(id) {
+        const definition = this.definitions.get(id);
+        if (!definition)
+            throw new Error(`no sound effect "${id}" in the bank`);
+        return definition;
+    }
+    ids() {
+        return [...this.definitions.keys()];
+    }
+}
+/**
+ * The shared voice limit between chip effects and the bus's `'se'` jingles: both ask here before
+ * they sound, and when the limit is reached the lowest-priority voice (the oldest among equals)
+ * is cut for a new one of equal or higher priority; a new one below everything sounding is
+ * refused. One arbiter handed to a bus and to every `SfxSound` makes them a single pool.
+ *
+ * @example
+ * ```ts
+ * import { SfxArbiter } from '@datamoc/mw_games/audio';
+ *
+ * const arbiter = new SfxArbiter({ maxVoices: 2 });
+ * const a = arbiter.request(1, () => console.log('a cut'));
+ * arbiter.request(1, () => console.log('b cut'));
+ * arbiter.request(5, () => console.log('c cut')); // cuts a, the oldest of the lowest priority
+ * a?.release();
+ * ```
+ */
+export class SfxArbiter {
+    constructor(options = {}) {
+        this.voices = [];
+        this.maxVoices = Math.max(1, Math.floor(options.maxVoices ?? 8));
+    }
+    get active() {
+        return this.voices.length;
+    }
+    /**
+     * Asks for a slot. `stop` cuts the voice when a better one needs its place; `active` says
+     * whether it still sounds, so a voice that ended by itself frees its slot for any asker, not
+     * only for the sound that owned it.
+     */
+    request(priority, stop, active = () => true) {
+        for (let i = this.voices.length - 1; i >= 0; i--)
+            if (!this.voices[i].active())
+                this.voices.splice(i, 1);
+        if (this.voices.length >= this.maxVoices) {
+            let victim = 0;
+            for (let i = 1; i < this.voices.length; i++) {
+                if (this.voices[i].priority < this.voices[victim].priority)
+                    victim = i;
+            }
+            if (this.voices[victim].priority > priority)
+                return null;
+            const [cut] = this.voices.splice(victim, 1);
+            cut.stop();
+        }
+        const entry = { priority, stop, active };
+        this.voices.push(entry);
+        return {
+            release: () => {
+                const at = this.voices.indexOf(entry);
+                if (at !== -1)
+                    this.voices.splice(at, 1);
+            },
+        };
+    }
+}
+/**
+ * A reproducible seed for an effect: the same id on the same game frame (and the same ordinal
+ * within that frame) always gives the same number, so a replay or a lockstep peer hears exactly
+ * what the original run heard, and audio never perturbs the simulation.
+ *
+ * @example
+ * ```ts
+ * import { sfxSeed } from '@datamoc/mw_games/audio';
+ *
+ * sfxSeed('arrow', 120) === sfxSeed('arrow', 120); // true
+ * ```
+ */
+export function sfxSeed(id, frame, ordinal = 0) {
+    let hash = 0x811c9dc5;
+    const mix = (value) => {
+        hash = Math.imul(hash ^ (value & 0xff), 0x01000193);
+        hash = Math.imul(hash ^ ((value >>> 8) & 0xff), 0x01000193);
+        hash = Math.imul(hash ^ ((value >>> 16) & 0xff), 0x01000193);
+        hash = Math.imul(hash ^ ((value >>> 24) & 0xff), 0x01000193);
+    };
+    for (let i = 0; i < id.length; i++)
+        mix(id.charCodeAt(i));
+    mix(Math.floor(frame));
+    mix(ordinal);
+    return hash >>> 0;
+}
+/**
+ * The data-driven counterpart of `Sound`: it plays an `SfxDefinition` (or the id of one in a
+ * bank) through a backend, with the same `play(gain, pitch)` shape so a `SoundSource` can
+ * attenuate it, and a pan on top. It applies the definition's retrigger rule, asks the shared
+ * arbiter for a voice, fires the caption, and hands the backend a deterministic seed.
+ *
+ * @example
+ * ```ts
+ * import { SfxArbiter, SfxBank, SfxSound, SoundSource, AudioListener, type SfxBackend } from '@datamoc/mw_games/audio';
+ *
+ * declare const chip: SfxBackend;
+ *
+ * const bank = new SfxBank([{ id: 'arrow', priority: 5, caption: 'an arrow flies' }]);
+ * const arrow = new SfxSound(chip, 'arrow', { bank, arbiter: new SfxArbiter(), frame: () => 0 });
+ * new SoundSource(arrow, { x: 3, y: 4 }).playFor(new AudioListener());
+ * ```
+ */
+export class SfxSound {
+    constructor(backend, effect, options = {}) {
+        /** how many plays reached the backend, for a test to assert on without a speaker */
+        this.plays = 0;
+        this.live = [];
+        this.suspended_ = false;
+        this.lastFrame = Number.NaN;
+        this.ordinal = 0;
+        this.backend = backend;
+        this.options = options;
+        this.volume = options.volume ?? 1;
+        if (typeof effect === 'string') {
+            if (!options.bank)
+                throw new Error(`a sound effect given by id ("${effect}") needs a bank`);
+            this.definition = options.bank.get(effect);
+        }
+        else {
+            this.definition = effect;
+        }
+    }
+    get isSuspended() {
+        return this.suspended_;
+    }
+    /** voices that still sound */
+    get activeVoices() {
+        this.prune();
+        return this.live.length;
+    }
+    /** plays the effect; returns false when it was ignored, refused by the arbiter or the backend had no voice */
+    play(gain = 1, pitch = 1, pan = 0) {
+        if (this.suspended_)
+            return false;
+        this.prune();
+        const rule = this.definition.retrigger ?? 'restart';
+        if (this.live.length > 0 && rule === 'ignore')
+            return false;
+        if (this.live.length > 0 && rule === 'restart')
+            this.stopAll();
+        const frame = this.options.frame?.() ?? 0;
+        this.ordinal = frame === this.lastFrame ? this.ordinal + 1 : 0;
+        this.lastFrame = frame;
+        let voice = null;
+        const grant = this.options.arbiter?.request(this.definition.priority ?? 0, () => {
+            voice?.stop();
+        }, () => voice?.active ?? true) ?? null;
+        if (this.options.arbiter && !grant)
+            return false;
+        voice = this.backend.play(this.definition, {
+            gain: Math.max(0, Math.min(1, gain * this.volume)),
+            pan: Math.max(-1, Math.min(1, pan)),
+            pitch,
+            seed: sfxSeed(this.definition.id, frame, this.ordinal),
+        });
+        if (!voice) {
+            grant?.release();
+            return false;
+        }
+        this.live.push({ voice, grant });
+        this.plays++;
+        const caption = this.definition.caption ?? this.options.caption;
+        if (caption)
+            onCaption.dispatch({ text: caption });
+        return true;
+    }
+    stopAll() {
+        for (const { voice, grant } of this.live.splice(0)) {
+            voice.stop();
+            grant?.release();
+        }
+    }
+    suspend() {
+        this.suspended_ = true;
+        this.stopAll();
+    }
+    resume() {
+        this.suspended_ = false;
+    }
+    /** drops voices that finished by themselves, returning their arbiter slots */
+    prune() {
+        for (let i = this.live.length - 1; i >= 0; i--) {
+            if (!this.live[i].voice.active) {
+                this.live[i].grant?.release();
+                this.live.splice(i, 1);
+            }
+        }
+    }
+}
+//# sourceMappingURL=Sfx.js.map

package/dist/audio/Sfx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sfx.js","sourceRoot":"","sources":["../../src/audio/Sfx.ts"],"names":[],"mappings":"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"}

package/dist/audio/Sound.d.ts

@@ -28,6 +28,8 @@ export declare class Sound {
     private caption?;
     private suspended_;
     volume: number;
+    /** how many times `play` actually started a clip (not counting calls made while suspended), for a test to assert on without a microphone */
+    plays: number;
     constructor(path: string, options?: SoundOptions);
     /**
      * Plays one instance from the pool.

package/dist/audio/Sound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,SAAI,EAAE,KAAK,SAAI,GAAG,IAAI,CAc9B;IAED,OAAO,IAAI,IAAI,CAKd;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI,CAGd;IAED,wCAAwC;IACxC,MAAM,IAAI,IAAI,CAEb;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;CACD"}
+{"version":3,"file":"Sound.d.ts","sourceRoot":"","sources":["../../src/audio/Sound.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;IAEpC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,4IAA4I;IAC5I,KAAK,SAAK;IAEV,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,EAMnD;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,IAAI,SAAI,EAAE,KAAK,SAAI,GAAG,IAAI,CAe9B;IAED,OAAO,IAAI,IAAI,CAKd;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI,CAGd;IAED,wCAAwC;IACxC,MAAM,IAAI,IAAI,CAEb;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;CACD"}

package/dist/audio/Sound.js

@@ -18,6 +18,8 @@ export class Sound {
     constructor(path, options = {}) {
         this.next = 0;
         this.suspended_ = false;
+        /** how many times `play` actually started a clip (not counting calls made while suspended), for a test to assert on without a microphone */
+        this.plays = 0;
         const size = Math.max(1, options.poolSize ?? 4);
         const create = options.create ?? createAudio;
         this.volume = options.volume ?? 1;
@@ -39,6 +41,7 @@ export class Sound {
     play(gain = 1, pitch = 1) {
         if (this.suspended_)
             return;
+        this.plays++;
         const audio = this.pool[this.next];
         this.next = (this.next + 1) % this.pool.length;
         audio.volume = this.volume * gain;