@datamoc/mw_games 0.44.2 → 0.45.0

package/dist/audio/MusicPlayer.d.ts

@@ -1,80 +0,0 @@
-import { Signal } from '../core/Signal.ts';
-import { type RenderedMidi } from './MidiRender.ts';
-export interface MusicPlayerOptions {
-    /** level, 0 to 1; 1 when omitted */
-    volume?: number;
-    /** where the sound goes; the context's destination when omitted (pass a gain or compressor to shape it) */
-    destination?: AudioNode;
-}
-export interface MusicPlayOptions {
-    /** start offset in seconds */
-    pos?: number;
-    /** true repeats the track through its loop region instead of ending; false when omitted */
-    repeat?: boolean;
-}
-/**
- * One music track at a time with the controls a game's jukebox needs: load a decoded track or a
- * rendered MIDI file, play, pause, resume, read the position, seek, and be told when the track
- * ends so the game can pick the next one. It wraps a `Channel`, so the buffer, the loop region
- * and the playhead behave as they do there; what it adds is the paused state and the end of the
- * track. Like `Music`, nothing advances on its own: call `update()` each frame.
- *
- * @example
- * ```ts
- * import { MusicPlayer, renderMidiToBufferAsync } from '@datamoc/mw_games/audio';
- *
- * declare const context: AudioContext;
- * declare const midiBytes: ArrayBuffer;
- * declare function nextTrack(): Promise<ArrayBuffer>;
- *
- * const player = new MusicPlayer(context, { volume: 0.8 });
- * player.load(await renderMidiToBufferAsync(midiBytes));
- * player.play();
- * async function playNext(): Promise<void> {
- * 	player.load(await renderMidiToBufferAsync(await nextTrack()));
- * 	player.play();
- * }
- * player.onEnded.add(() => { void playNext(); });
- *
- * // in the scene's update:
- * player.update();
- * ```
- */
-export declare class MusicPlayer {
-    /** fires once when a track that was not repeating plays through to its end */
-    readonly onEnded: Signal<void>;
-    private readonly context;
-    private readonly channel;
-    private buffer;
-    private loop;
-    private repeat;
-    private playing;
-    private paused;
-    private resumeAt;
-    private volume_;
-    constructor(context: AudioContext, options?: MusicPlayerOptions);
-    /** stops what plays and makes this track the one to play; a rendered MIDI file is copied into a buffer first */
-    load(track: RenderedMidi | AudioBuffer): void;
-    /** plays the loaded track from the start, or from `pos` */
-    play(options?: MusicPlayOptions): void;
-    pause(): void;
-    resume(): void;
-    /** pauses a playing track and resumes a paused one */
-    togglePause(): void;
-    /** stops and forgets the position; `play()` starts over */
-    stop(): void;
-    get isPlaying(): boolean;
-    get isPaused(): boolean;
-    /** seconds of the loaded track */
-    get duration(): number;
-    /** seconds into the track, held while paused */
-    position(): number;
-    /** moves the playhead, keeping a paused track paused */
-    seek(pos: number): void;
-    get volume(): number;
-    set volume(level: number);
-    /** call each frame: fires `onEnded` once when a non-repeating track has finished */
-    update(): void;
-    private start;
-}
-//# sourceMappingURL=MusicPlayer.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"MusicPlayer.d.ts","sourceRoot":"","sources":["../../src/audio/MusicPlayer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEnE,MAAM,WAAW,kBAAkB;IAClC,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2GAA2G;IAC3G,WAAW,CAAC,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAChC,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,WAAW;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,eAAsB;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB,EAIlE;IAED,gHAAgH;IAChH,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,IAAI,CAS5C;IAED,2DAA2D;IAC3D,IAAI,CAAC,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAOzC;IAED,KAAK,IAAI,IAAI,CAKZ;IAED,MAAM,IAAI,IAAI,CAIb;IAED,sDAAsD;IACtD,WAAW,IAAI,IAAI,CAGlB;IAED,2DAA2D;IAC3D,IAAI,IAAI,IAAI,CAKX;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,kCAAkC;IAClC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,gDAAgD;IAChD,QAAQ,IAAI,MAAM,CAGjB;IAED,wDAAwD;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKtB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,EAGvB;IAED,oFAAoF;IACpF,MAAM,IAAI,IAAI,CAKb;IAED,OAAO,CAAC,KAAK;CASb"}

package/dist/audio/MusicPlayer.js

@@ -1,147 +0,0 @@
-import { Signal } from '../core/Signal.js';
-import { Channel } from './Channels.js';
-import { toAudioBuffer } from './MidiRender.js';
-/**
- * One music track at a time with the controls a game's jukebox needs: load a decoded track or a
- * rendered MIDI file, play, pause, resume, read the position, seek, and be told when the track
- * ends so the game can pick the next one. It wraps a `Channel`, so the buffer, the loop region
- * and the playhead behave as they do there; what it adds is the paused state and the end of the
- * track. Like `Music`, nothing advances on its own: call `update()` each frame.
- *
- * @example
- * ```ts
- * import { MusicPlayer, renderMidiToBufferAsync } from '@datamoc/mw_games/audio';
- *
- * declare const context: AudioContext;
- * declare const midiBytes: ArrayBuffer;
- * declare function nextTrack(): Promise<ArrayBuffer>;
- *
- * const player = new MusicPlayer(context, { volume: 0.8 });
- * player.load(await renderMidiToBufferAsync(midiBytes));
- * player.play();
- * async function playNext(): Promise<void> {
- * 	player.load(await renderMidiToBufferAsync(await nextTrack()));
- * 	player.play();
- * }
- * player.onEnded.add(() => { void playNext(); });
- *
- * // in the scene's update:
- * player.update();
- * ```
- */
-export class MusicPlayer {
-    constructor(context, options = {}) {
-        /** fires once when a track that was not repeating plays through to its end */
-        this.onEnded = new Signal();
-        this.buffer = null;
-        this.loop = null;
-        this.repeat = false;
-        this.playing = false;
-        this.paused = false;
-        this.resumeAt = 0;
-        this.context = context;
-        this.channel = new Channel(context, options.destination);
-        this.volume_ = Math.min(1, Math.max(0, options.volume ?? 1));
-    }
-    /** stops what plays and makes this track the one to play; a rendered MIDI file is copied into a buffer first */
-    load(track) {
-        this.stop();
-        if ('left' in track) {
-            this.buffer = toAudioBuffer(this.context, track);
-            this.loop = { start: track.loopStart, end: track.loopEnd };
-        }
-        else {
-            this.buffer = track;
-            this.loop = null;
-        }
-    }
-    /** plays the loaded track from the start, or from `pos` */
-    play(options = {}) {
-        if (!this.buffer)
-            return;
-        this.repeat = options.repeat ?? false;
-        this.paused = false;
-        this.playing = true;
-        this.resumeAt = options.pos ?? 0;
-        this.start();
-    }
-    pause() {
-        if (!this.playing || this.paused)
-            return;
-        this.resumeAt = this.channel.position();
-        this.paused = true;
-        this.channel.stop();
-    }
-    resume() {
-        if (!this.paused || !this.buffer)
-            return;
-        this.paused = false;
-        this.start();
-    }
-    /** pauses a playing track and resumes a paused one */
-    togglePause() {
-        if (this.paused)
-            this.resume();
-        else
-            this.pause();
-    }
-    /** stops and forgets the position; `play()` starts over */
-    stop() {
-        this.channel.stop();
-        this.playing = false;
-        this.paused = false;
-        this.resumeAt = 0;
-    }
-    get isPlaying() {
-        return this.playing && !this.paused;
-    }
-    get isPaused() {
-        return this.paused;
-    }
-    /** seconds of the loaded track */
-    get duration() {
-        return this.buffer?.duration ?? 0;
-    }
-    /** seconds into the track, held while paused */
-    position() {
-        if (!this.playing)
-            return 0;
-        return this.paused ? this.resumeAt : this.channel.position();
-    }
-    /** moves the playhead, keeping a paused track paused */
-    seek(pos) {
-        if (!this.buffer)
-            return;
-        const target = Math.min(Math.max(0, pos), this.buffer.duration);
-        if (this.paused)
-            this.resumeAt = target;
-        else if (this.playing)
-            this.play({ pos: target, repeat: this.repeat });
-    }
-    get volume() {
-        return this.volume_;
-    }
-    set volume(level) {
-        this.volume_ = Math.min(1, Math.max(0, level));
-        this.channel.update({ volume: this.volume_ });
-    }
-    /** call each frame: fires `onEnded` once when a non-repeating track has finished */
-    update() {
-        if (!this.playing || this.paused || this.channel.isPlaying)
-            return;
-        this.playing = false;
-        this.resumeAt = 0;
-        this.onEnded.dispatch();
-    }
-    start() {
-        if (!this.buffer)
-            return;
-        this.channel.play(this.buffer, {
-            volume: this.volume_,
-            pos: this.resumeAt,
-            loop: this.loop,
-            repeat: this.repeat,
-        });
-    }
-}
-//# sourceMappingURL=MusicPlayer.js.map

package/dist/audio/MusicPlayer.js.map

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

package/dist/audio/Orchestrator.d.ts

@@ -1,58 +0,0 @@
-import type { Music } from './Music.ts';
-import type { Sound } from './Sound.ts';
-/** what playing this state's music should look like - `fadeDuration` follows `Music.play`'s own default */
-export interface OrchestratorState {
-    track: string;
-    fadeDuration?: number;
-}
-/**
- * The data a game writes once instead of scattering `Music.play`/`Sound.play` calls across
- * every place a fight starts or a menu opens: name the states ("exploring", "combat",
- * "boss", "menu") and the cues ("hit", "levelUp"), and call `enter`/`trigger` by name from
- * then on.
- *
- * `enter` is idempotent by track, not by state name - two state names that happen to map to
- * the same track will not refade into each other either, since there is nothing to refade
- * to. Re-entering "combat" mid-fight (the same fight, the same track) must not reset the
- * music, which is the one behaviour a direct `Music.play` call at every call site cannot
- * give you for free: the orchestrator remembers the current track and treats entering an
- * already-current one as a no-op.
- *
- * Cues are separate from states because they are fire-and-forget one-shots (`Sound`, not
- * `Music`) - folding them into `enter` would conflate "this is where we are" with "this just
- * happened".
- *
- * @example
- * ```ts
- * import { Orchestrator, Music, Sound } from '@datamoc/mw_games/audio';
- *
- * const orchestrator = new Orchestrator(new Music());
- * orchestrator.define('exploring', { track: 'music/town.mp3' });
- * orchestrator.define('combat', { track: 'music/battle.mp3', fadeDuration: 0.5 });
- * orchestrator.on('levelUp', new Sound('sounds/level-up.mp3'));
- *
- * orchestrator.enter('combat'); // crossfades in
- * orchestrator.enter('combat'); // already playing - a no-op, does not refade
- * orchestrator.trigger('levelUp'); // fires the one-shot cue
- * ```
- */
-export declare class Orchestrator {
-    private states;
-    private cues;
-    private currentTrack;
-    private music;
-    constructor(music: Music);
-    /** defines or replaces one state's music mapping */
-    define(state: string, mapping: OrchestratorState): void;
-    /** switches to `state`'s track, crossfading; a no-op if that track is already playing */
-    enter(state: string): void;
-    /** registers the one-shot sound played by `trigger(event)` */
-    on(event: string, cue: Sound): void;
-    /** plays the sound registered for `event`, if any; silently does nothing otherwise */
-    trigger(event: string): void;
-    /** suspends the music and every cue - the rig a `Game` silences on page hide */
-    suspend(): void;
-    /** resumes the music and every cue after `suspend` */
-    resume(): void;
-}
-//# sourceMappingURL=Orchestrator.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Orchestrator.d.ts","sourceRoot":"","sources":["../../src/audio/Orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,2GAA2G;AAC3G,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,KAAK,CAAQ;IAErB,YAAY,KAAK,EAAE,KAAK,EAEvB;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAEtD;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAQzB;IAED,8DAA8D;IAC9D,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAElC;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE3B;IAED,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAGd;IAED,sDAAsD;IACtD,MAAM,IAAI,IAAI,CAGb;CACD"}

package/dist/audio/Orchestrator.js

@@ -1,74 +0,0 @@
-/**
- * The data a game writes once instead of scattering `Music.play`/`Sound.play` calls across
- * every place a fight starts or a menu opens: name the states ("exploring", "combat",
- * "boss", "menu") and the cues ("hit", "levelUp"), and call `enter`/`trigger` by name from
- * then on.
- *
- * `enter` is idempotent by track, not by state name - two state names that happen to map to
- * the same track will not refade into each other either, since there is nothing to refade
- * to. Re-entering "combat" mid-fight (the same fight, the same track) must not reset the
- * music, which is the one behaviour a direct `Music.play` call at every call site cannot
- * give you for free: the orchestrator remembers the current track and treats entering an
- * already-current one as a no-op.
- *
- * Cues are separate from states because they are fire-and-forget one-shots (`Sound`, not
- * `Music`) - folding them into `enter` would conflate "this is where we are" with "this just
- * happened".
- *
- * @example
- * ```ts
- * import { Orchestrator, Music, Sound } from '@datamoc/mw_games/audio';
- *
- * const orchestrator = new Orchestrator(new Music());
- * orchestrator.define('exploring', { track: 'music/town.mp3' });
- * orchestrator.define('combat', { track: 'music/battle.mp3', fadeDuration: 0.5 });
- * orchestrator.on('levelUp', new Sound('sounds/level-up.mp3'));
- *
- * orchestrator.enter('combat'); // crossfades in
- * orchestrator.enter('combat'); // already playing - a no-op, does not refade
- * orchestrator.trigger('levelUp'); // fires the one-shot cue
- * ```
- */
-export class Orchestrator {
-    constructor(music) {
-        this.states = new Map();
-        this.cues = new Map();
-        this.currentTrack = null;
-        this.music = music;
-    }
-    /** defines or replaces one state's music mapping */
-    define(state, mapping) {
-        this.states.set(state, mapping);
-    }
-    /** switches to `state`'s track, crossfading; a no-op if that track is already playing */
-    enter(state) {
-        const mapping = this.states.get(state);
-        if (!mapping)
-            throw new Error(`Orchestrator: no state defined for "${state}"`);
-        if (mapping.track === this.currentTrack)
-            return;
-        this.music.play(mapping.track, mapping.fadeDuration);
-        this.currentTrack = mapping.track;
-    }
-    /** registers the one-shot sound played by `trigger(event)` */
-    on(event, cue) {
-        this.cues.set(event, cue);
-    }
-    /** plays the sound registered for `event`, if any; silently does nothing otherwise */
-    trigger(event) {
-        this.cues.get(event)?.play();
-    }
-    /** suspends the music and every cue - the rig a `Game` silences on page hide */
-    suspend() {
-        this.music.suspend();
-        for (const cue of this.cues.values())
-            cue.suspend();
-    }
-    /** resumes the music and every cue after `suspend` */
-    resume() {
-        this.music.resume();
-        for (const cue of this.cues.values())
-            cue.resume();
-    }
-}
-//# sourceMappingURL=Orchestrator.js.map

package/dist/audio/Orchestrator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Orchestrator.js","sourceRoot":"","sources":["../../src/audio/Orchestrator.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,YAAY;IAMxB,YAAY,KAAY;QALhB,WAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;QAC9C,SAAI,GAAG,IAAI,GAAG,EAAiB,CAAC;QAChC,iBAAY,GAAkB,IAAI,CAAC;QAI1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAa,EAAE,OAA0B;QAC/C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAa;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,KAAK,GAAG,CAAC,CAAC;QAE/E,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,YAAY;YAAE,OAAO;QAEhD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QACrD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC;IACnC,CAAC;IAED,8DAA8D;IAC9D,EAAE,CAAC,KAAa,EAAE,GAAU;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAa;QACpB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED,gFAAgF;IAChF,OAAO;QACN,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACrB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,GAAG,CAAC,OAAO,EAAE,CAAC;IACrD,CAAC;IAED,sDAAsD;IACtD,MAAM;QACL,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IACpD,CAAC;CACD"}

package/dist/audio/Playable.d.ts

@@ -1,38 +0,0 @@
-/**
- * The surface `mwg/audio` needs from a playing sound - exactly what `HTMLAudioElement`
- * already provides, named here so a test (or a game with its own audio backend) can supply
- * a fake without a real `Audio` element existing, which nothing outside a browser can
- * create.
- *
- * A backend that synthesises its sound instead of decoding a file (see `StreamPlayable`) has to
- * answer the questions `HTMLAudioElement` answers implicitly: `currentTime` reads and seeks the
- * playhead and holds the duration once a track that does not loop has ended; `playbackRate` is
- * honoured (by resampling) or ignored but never throws; `onended` fires once at the end of a
- * track that does not loop and never for one that does; and `play()` may return a promise that
- * settles when the audio is allowed to start.
- */
-export interface Playable {
-    play(): void | Promise<void>;
-    pause(): void;
-    currentTime: number;
-    volume: number;
-    loop: boolean;
-    /** speed and pitch together, matching `HTMLAudioElement.playbackRate`; 1 is unchanged */
-    playbackRate?: number;
-    /** Optional completion hook, matching HTMLAudioElement.onended. Backends without an
-     * end event can omit it; single-track Music remains fully usable there. */
-    onended?: ((event: Event) => unknown) | null;
-}
-/**
- * The real thing: an `HTMLAudioElement` pointed at a resolved asset path.
- *
- * @example
- * ```ts
- * import { createAudio, Sound } from '@datamoc/mw_games/audio';
- *
- * // Sound/Music both default to this; supply your own only for a test or a non-browser backend
- * const hit = new Sound('sounds/hit.mp3', { create: createAudio });
- * ```
- */
-export declare function createAudio(path: string): Playable;
-//# sourceMappingURL=Playable.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Playable.d.ts","sourceRoot":"","sources":["../../src/audio/Playable.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACxB,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;+EAC2E;IAC3E,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAUlD"}

package/dist/audio/Playable.js

@@ -1,29 +0,0 @@
-import * as Resources from '../assets/paths.js';
-/**
- * The real thing: an `HTMLAudioElement` pointed at a resolved asset path.
- *
- * @example
- * ```ts
- * import { createAudio, Sound } from '@datamoc/mw_games/audio';
- *
- * // Sound/Music both default to this; supply your own only for a test or a non-browser backend
- * const hit = new Sound('sounds/hit.mp3', { create: createAudio });
- * ```
- */
-export function createAudio(path) {
-    let url;
-    try {
-        url = Resources.resolve(path);
-    }
-    catch (error) {
-        //a sound missing from the build must not stop the game from starting: it plays as silence
-        console.warn(`${error.message} - "${path}" will be silent`);
-        return silentPlayable();
-    }
-    return new Audio(url);
-}
-/** a `Playable` that makes no sound, standing in for an asset that could not be resolved */
-function silentPlayable() {
-    return { play() { }, pause() { }, currentTime: 0, volume: 1, loop: false };
-}
-//# sourceMappingURL=Playable.js.map

package/dist/audio/Playable.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Playable.js","sourceRoot":"","sources":["../../src/audio/Playable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC;AA4BhD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACvC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACJ,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,0FAA0F;QAC1F,OAAO,CAAC,IAAI,CAAC,GAAI,KAAe,CAAC,OAAO,OAAO,IAAI,kBAAkB,CAAC,CAAC;QACvE,OAAO,cAAc,EAAE,CAAC;IACzB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,4FAA4F;AAC5F,SAAS,cAAc;IACtB,OAAO,EAAE,IAAI,KAAI,CAAC,EAAE,KAAK,KAAI,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1E,CAAC"}

package/dist/audio/Positional.d.ts

@@ -1,133 +0,0 @@
-/** anything a `SoundSource` can play at a mix: a `Sound`, or an `SfxSound` that also takes a pan */
-export interface PositionalSound {
-    play(gain?: number, pitch?: number, pan?: number): unknown;
-}
-/** A point in the same 2D space the game's camera works in, in world units. */
-export interface AudioPoint {
-    x: number;
-    y: number;
-}
-/**
- * How far away a source can be heard from, and how fast it fades.
- *
- * `refDistance` is full volume, `maxDistance` is silence, and `rolloff` shapes the drop
- * between them: 1 is inverse-linear, 2 inverse-square. These are the names the Web Audio
- * `PannerNode` uses for the same three numbers, so a game that later moves to a real panner
- * does not have to re-author them.
- */
-export interface AudioFalloff {
-    /** distance at which the source is at full volume; defaults to 1 */
-    refDistance?: number;
-    /** distance at which the source is silent; defaults to Infinity */
-    maxDistance?: number;
-    /** exponent of the inverse-distance drop; defaults to 1 */
-    rolloff?: number;
-}
-/**
- * The gain a listener at `distance` hears a source at, clamped to [0, 1]: 1 at or inside
- * `refDistance`, 0 at or beyond `maxDistance`, an inverse-distance curve between them.
- *
- * @example
- * ```ts
- * import { audioGain } from '@datamoc/mw_games/audio';
- *
- * audioGain(0, { refDistance: 2 }); // 1 - inside the full-volume radius
- * audioGain(2, { refDistance: 2 }); // 1 - the reference distance itself
- * audioGain(4, { refDistance: 2 }); // 0.5 - one doubling away
- * audioGain(4, { refDistance: 2, maxDistance: 4 }); // 0 - at the edge of hearing
- * ```
- */
-export declare function audioGain(distance: number, falloff?: AudioFalloff): number;
-/**
- * Stereo pan in [-1, 1] for a source: -1 is hard left of the listener, 1 hard right, 0
- * directly ahead or behind. The listener's `facing` is its heading in radians (0 faces +x,
- * increasing clockwise on a screen where y grows downward), so turning the listener turns
- * what counts as "right" with it - a sound to the world's east is centred when the listener
- * faces east and hard right when the listener faces north.
- *
- * A game with a stereo backend applies this itself; the framework has no panner node of its
- * own, so it reports the number rather than pretending to pan.
- *
- * @example
- * ```ts
- * import { audioPan } from '@datamoc/mw_games/audio';
- *
- * const listener = { x: 0, y: 0, facing: 0 }; // facing east
- * audioPan(listener, { x: 10, y: 0 }); // 0 - straight ahead
- * audioPan(listener, { x: 0, y: 10 }); // 1 - to the listener's right
- * audioPan(listener, { x: 0, y: -10 }); // -1 - to its left
- * ```
- */
-export declare function audioPan(listener: AudioPoint & {
-    facing: number;
-}, source: AudioPoint): number;
-/**
- * Where sounds are heard from: a game moves one listener to its camera or its party leader
- * each frame, and every `SoundSource` is mixed against it.
- *
- * @example
- * ```ts
- * import { AudioListener } from '@datamoc/mw_games/audio';
- *
- * const listener = new AudioListener({ x: 40, y: 12 });
- * listener.moveTo(41, 12); // following the camera
- * listener.face(Math.PI / 2); // now facing the world's south
- * ```
- */
-export declare class AudioListener implements AudioPoint {
-    x: number;
-    y: number;
-    /** heading in radians: 0 faces +x, increasing clockwise on a y-down screen */
-    facing: number;
-    constructor(options?: {
-        x?: number;
-        y?: number;
-        facing?: number;
-    });
-    moveTo(x: number, y: number): void;
-    face(radians: number): void;
-}
-export interface SoundSourceOptions extends AudioFalloff {
-    x?: number;
-    y?: number;
-}
-/**
- * One positional one-shot: a `Sound` attached to a point in the world, heard from a
- * listener with the distance gain `audioGain` computes. `playFor` applies that gain through
- * `Sound.play(gain)`, and stays silent past `maxDistance` rather than playing at volume 0.
- *
- * Long-running position (a waterfall, an engine) is the game's own loop calling `playFor` on
- * a cadence it chooses; this is the placement and the mix, not a scheduler.
- *
- * @example
- * ```ts
- * import { AudioListener, Sound, SoundSource } from '@datamoc/mw_games/audio';
- *
- * const listener = new AudioListener({ x: 0, y: 0 });
- * const arrow = new Sound('sounds/arrow.mp3');
- * const source = new SoundSource(arrow, { x: 6, y: 8, refDistance: 4, maxDistance: 20 });
- *
- * const gain = source.gainTo(listener); // 0.4 at distance 10
- * source.playFor(listener); // plays at that gain, or not at all when silent
- * ```
- */
-export declare class SoundSource implements AudioPoint {
-    x: number;
-    y: number;
-    private readonly sound;
-    private readonly falloff;
-    constructor(sound: PositionalSound, options?: SoundSourceOptions);
-    moveTo(x: number, y: number): void;
-    gainTo(listener: AudioPoint): number;
-    panTo(listener: AudioPoint & {
-        facing: number;
-    }): number;
-    /**
-     * Plays the source at the gain the listener hears it; returns the gain actually used. A listener
-     * with a `facing` also pans the sound, for a sound that takes a pan (a `Sound` ignores it).
-     */
-    playFor(listener: AudioPoint | (AudioPoint & {
-        facing: number;
-    })): number;
-}
-//# sourceMappingURL=Positional.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Positional.d.ts","sourceRoot":"","sources":["../../src/audio/Positional.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3D;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC5B,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CAU9E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAW9F;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,UAAU;IAC/C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IAEf,YAAY,OAAO,GAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,EAIpE;IAED,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjC;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1B;CACD;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACvD,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,YAAY,KAAK,EAAE,eAAe,EAAE,OAAO,GAAE,kBAAuB,EASnE;IAED,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGjC;IAED,MAAM,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAEnC;IAED,KAAK,CAAC,QAAQ,EAAE,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAEvD;IAED;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,GAAG,CAAC,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,MAAM,CAKxE;CACD"}