melonjs 19.4.0 → 19.6.0

package/build/audio/backend.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Audio backend — the shared internal surface every other audio module
+ * (procedural, playback) builds on. Keeps the Howler reference and the
+ * cross-module mutable state in one place so the public surface modules
+ * stay backend-agnostic.
+ *
+ * Not part of the public `me.audio.*` API — the two getters
+ * `getAudioContext` / `getMasterGain` are re-exported from `audio.ts`
+ * for end users; everything else (the `state` object, `soundLoadError`)
+ * is internal.
+ */
+import { Howl } from "howler";
+/**
+ * Whether to stop on an audio loading error.
+ *
+ * When `true`, melonJS throws an exception and aborts loading.
+ * When `false`, melonJS disables sound and logs a warning to the console.
+ * @default true
+ */
+export declare let stopOnAudioError: boolean;
+/**
+ * Cross-module mutable state. A single object so multiple consumers
+ * can read and mutate the same fields without the "ESM `let` exports
+ * don't share writes across modules" footgun.
+ *
+ * Fields:
+ * - `tracks` — loaded Howl instances keyed by logical sound name.
+ *   `Howl | undefined` because missing keys return undefined at runtime
+ *   even though the type signature wouldn't normally admit it.
+ * - `currentTrackId` — the name of the currently-playing track managed
+ *   by the `playTrack` / `stopTrack` helpers.
+ * - `retryCounter` — retry counter for `soundLoadError`'s back-off.
+ * - `audioExts` — the active list of audio formats set by `init`.
+ * @ignore
+ */
+export declare const state: {
+    tracks: Record<string, Howl | undefined>;
+    currentTrackId: string | null;
+    retryCounter: number;
+    audioExts: string[];
+};
+/**
+ * Look up a loaded `Howl` instance by logical name, or throw a
+ * uniform "audio clip X does not exist" error if it isn't loaded.
+ * Used by every per-clip helper across `playback.ts` / `audio.ts` so
+ * the error contract stays identical across the whole surface.
+ * @ignore
+ */
+export declare function getSoundOrThrow(sound_name: string): Howl;
+/**
+ * Event listener callback on load error. Retries the load up to 3
+ * times, then either throws or disables audio (depending on the
+ * `stopOnAudioError` flag re-exported from `audio.ts`).
+ * @ignore
+ */
+export declare const soundLoadError: (sound_name: string, onerror_cb?: () => void, stopOnError?: boolean) => void;
+/**
+ * Returns the underlying WebAudio `AudioContext` used by the audio
+ * module (the same one shared with file-based playback), or `null` if
+ * audio is disabled or no compatible WebAudio implementation is
+ * available.
+ *
+ * Use this when you need to build a custom WebAudio graph — procedural
+ * SFX, custom filters / spatial nodes, audio analysis — without
+ * spawning a second context. Browsers throttle or refuse multiple
+ * `AudioContext` instances on the same page and each has its own
+ * suspend-until-gesture state, so sharing matters.
+ *
+ * The context is lazily created on first access; the call also returns
+ * the cached instance on every subsequent call.
+ * @category Audio
+ */
+export declare function getAudioContext(): AudioContext | null;
+/**
+ * Return the audio module's master gain node — the single `GainNode`
+ * every playback path runs through on its way to `ctx.destination`,
+ * and the lever that {@link setVolume} / {@link muteAll} manipulate.
+ *
+ * Connect to this node (instead of `ctx.destination`) whenever you
+ * build a custom WebAudio graph and want the result to respect the
+ * engine's mute / volume state. Returns `null` when audio is disabled
+ * or unavailable.
+ * @category Audio
+ */
+export declare function getMasterGain(): GainNode | null;
+/**
+ * Get the audio module's global volume.
+ * @ignore
+ */
+export declare function getGlobalVolume(): number;
+/**
+ * Set the audio module's global volume.
+ * @ignore
+ */
+export declare function setGlobalVolume(v: number): void;
+/**
+ * Mute or unmute the audio module globally.
+ * @ignore
+ */
+export declare function setGlobalMuted(muted: boolean): void;
+/**
+ * Whether the audio module is currently muted globally.
+ * @ignore
+ */
+export declare function isGlobalMuted(): boolean;
+/**
+ * Stop every playing sound on every channel.
+ * @ignore
+ */
+export declare function stopAllPlayback(): void;
+/**
+ * Whether the given audio codec is supported by the backend / browser.
+ * @ignore
+ */
+export declare function hasCodec(codec: string): boolean;
+/**
+ * Whether at least one audio backend (HTML5 or WebAudio) is available.
+ * @ignore
+ */
+export declare function isAudioAvailable(): boolean;
+//# sourceMappingURL=backend.d.ts.map

package/build/audio/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/audio/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAU,MAAM,QAAQ,CAAC;AAEtC;;;;;;GAMG;AAEH,eAAO,IAAI,gBAAgB,EAAE,OAAc,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK;YACH,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,SAAS,CAAC;oBACtB,MAAM,GAAG,IAAI;;eAEpB,MAAM,EAAE;CACzB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAMxD;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAC1B,YAAY,MAAM,EAClB,aAAa,MAAM,IAAI,EACvB,cAAa,OAAc,KACzB,IAeF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAmBrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,IAAI,QAAQ,GAAG,IAAI,CAS/C;AAUD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAKvC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAO/C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C"}

package/build/audio/playback.d.ts

@@ -0,0 +1,157 @@
+/**
+ * File-based playback — load audio assets, then play / pause / fade /
+ * seek / etc. Every function in this module operates on the shared
+ * `state.tracks` map exposed from `backend.ts`, so the audio module's
+ * other surfaces (track helpers, mix, unload) can see the same set of
+ * loaded sounds.
+ */
+import type { LoadSettings, PannerAttributes, SoundAsset } from "./types.ts";
+/**
+ * Load an audio file.
+ *
+ * `sound.src` is treated as a base path / prefix; the URL is built as
+ * `${sound.src}${sound.name}.${ext}` for each extension configured by
+ * {@link init}, until one loads. Data URLs (`data:audio/...`) are
+ * used as-is and skip the prefix-and-extension dance.
+ * @param sound - The {@link SoundAsset} descriptor — logical `name`,
+ *   `src` base path / prefix (or data URL), and optional playback
+ *   flags (`autoplay`, `loop`, `stream`, `html5`).
+ * @param onloadcb - Called when the resource has finished loading.
+ * @param onerrorcb - Called when loading fails.
+ * @param settings - Optional {@link LoadSettings} — `nocache` (query
+ *   string appended for cache busting) and `withCredentials` (forwarded
+ *   to the underlying XHR for cross-origin authenticated requests).
+ * @returns The number of assets loaded (always `1` on success).
+ * @category Audio
+ */
+export declare function load(sound: SoundAsset, onloadcb?: () => void, onerrorcb?: () => void, settings?: LoadSettings): number;
+/**
+ * Play the specified sound.
+ * @param sound_name - Audio clip name (case-sensitive).
+ * @param loop - Whether to loop the clip. Defaults to `false`.
+ * @param onend - Called when the sound instance ends playing.
+ * @param volume - Playback volume, `0.0..1.0`. Defaults to the current
+ *   global volume.
+ * @returns The sound instance ID.
+ * @example
+ * // play the "cling" audio clip
+ * me.audio.play("cling");
+ * // play & loop the "engine" audio clip
+ * me.audio.play("engine", true);
+ * // play the "gameover_sfx" audio clip and call myFunc when finished
+ * me.audio.play("gameover_sfx", false, myFunc);
+ * // play the "gameover_sfx" audio clip at half volume
+ * me.audio.play("gameover_sfx", false, null, 0.5);
+ * @category Audio
+ */
+export declare function play(sound_name: string, loop?: boolean, onend?: (() => void) | null, volume?: number): number;
+/**
+ * Fade a currently playing sound between two volumes.
+ * @param sound_name - Audio clip name (case-sensitive).
+ * @param from - Volume to fade from, `0.0..1.0`.
+ * @param to - Volume to fade to, `0.0..1.0`.
+ * @param duration - Fade time in milliseconds.
+ * @param id - Sound instance ID. When omitted, all sounds in the group
+ *   are faded.
+ * @category Audio
+ */
+export declare function fade(sound_name: string, from: number, to: number, duration: number, id?: number): void;
+/**
+ * Get or set the playback position of a sound.
+ * @param sound_name - Audio clip name (case-sensitive).
+ * @param args - Optional seek position in seconds, optionally followed
+ *   by the sound instance ID.
+ * @returns The current seek position when no extra arguments are given.
+ * @example
+ * // read the current position of the background music
+ * let current_pos = me.audio.seek("dst-gameforest");
+ * // rewind the background music to the beginning
+ * me.audio.seek("dst-gameforest", 0);
+ * @category Audio
+ */
+export declare function seek(sound_name: string, ...args: number[]): number;
+/**
+ * Get or set the playback rate of a sound.
+ * @param sound_name - Audio clip name (case-sensitive).
+ * @param args - Optional playback rate (`0.5..4.0`, where `1.0` is
+ *   normal speed), optionally followed by the sound instance ID.
+ * @returns The current playback rate when no extra arguments are given.
+ * @example
+ * // read the current playback rate
+ * let rate = me.audio.rate("dst-gameforest");
+ * // speed it up 2×
+ * me.audio.rate("dst-gameforest", 2.0);
+ * @category Audio
+ */
+export declare function rate(sound_name: string, ...args: number[]): number;
+/** @inheritDoc */
+export declare function stereo(sound_name: string): number;
+/** @inheritDoc */
+export declare function stereo(sound_name: string, pan: number, id?: number): void;
+/** @inheritDoc */
+export declare function position(sound_name: string): [number, number, number];
+/** @inheritDoc */
+export declare function position(sound_name: string, x: number, y?: number, z?: number, id?: number): void;
+/** @inheritDoc */
+export declare function orientation(sound_name: string): [number, number, number];
+/** @inheritDoc */
+export declare function orientation(sound_name: string, x: number, y?: number, z?: number, id?: number): void;
+/**
+ * Get or set the panner-node attributes for a sound or sound group.
+ * @param sound_name - Audio clip name (case-sensitive).
+ * @param attributes - The {@link PannerAttributes} to apply (cone angles,
+ *   distance model, panning algorithm, …). See the interface for
+ *   per-field defaults.
+ * @param id - Sound instance ID. When omitted, all sounds in the group
+ *   are affected.
+ * @returns The resulting {@link PannerAttributes} after the update.
+ * @example
+ * me.audio.panner("cling", {
+ *     panningModel: "HRTF",
+ *     refDistance: 0.8,
+ *     rolloffFactor: 2.5,
+ *     distanceModel: "exponential",
+ * });
+ * @category Audio
+ */
+export declare function panner(sound_name: string, attributes?: PannerAttributes, id?: number): PannerAttributes;
+/**
+ * Stop the specified sound on all channels.
+ * @param sound_name - Audio clip name (case-sensitive). When omitted,
+ *   every sound currently playing is stopped.
+ * @param id - Sound instance ID. When omitted, all sounds in the group
+ *   are stopped.
+ * @example
+ * me.audio.stop("cling");
+ * @category Audio
+ */
+export declare function stop(sound_name?: string, id?: number): void;
+/**
+ * Pause the specified sound on all channels. Does not reset the
+ * current playback position.
+ * @param sound_name - Audio clip name (case-sensitive).
+ * @param id - Sound instance ID. When omitted, all sounds in the group
+ *   are paused.
+ * @example
+ * me.audio.pause("cling");
+ * @category Audio
+ */
+export declare function pause(sound_name: string, id?: number): void;
+/**
+ * Resume the specified sound on all channels.
+ * @param sound_name - Audio clip name (case-sensitive).
+ * @param id - Sound instance ID. When omitted, all sounds in the group
+ *   are resumed.
+ * @example
+ * // play an audio clip
+ * let id = me.audio.play("myClip");
+ * // ...
+ * // pause it
+ * me.audio.pause("myClip", id);
+ * // ...
+ * // resume
+ * me.audio.resume("myClip", id);
+ * @category Audio
+ */
+export declare function resume(sound_name: string, id?: number): void;
+//# sourceMappingURL=playback.d.ts.map

package/build/audio/playback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playback.d.ts","sourceRoot":"","sources":["../../src/audio/playback.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CACnB,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,IAAI,EACrB,SAAS,CAAC,EAAE,MAAM,IAAI,EACtB,QAAQ,GAAE,YAAiB,GACzB,MAAM,CAqCR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CACnB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,OAAe,EACrB,KAAK,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,EAC3B,MAAM,CAAC,EAAE,MAAM,GACb,MAAM,CAgBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,EAAE,CAAC,EAAE,MAAM,GACT,IAAI,CAEN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAElE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAElE;AAED,kBAAkB;AAClB,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;AACnD,kBAAkB;AAClB,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;AA8B3E,kBAAkB;AAClB,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACvE,kBAAkB;AAClB,wBAAgB,QAAQ,CACvB,UAAU,EAAE,MAAM,EAClB,CAAC,EAAE,MAAM,EACT,CAAC,CAAC,EAAE,MAAM,EACV,CAAC,CAAC,EAAE,MAAM,EACV,EAAE,CAAC,EAAE,MAAM,GACT,IAAI,CAAC;AA+BR,kBAAkB;AAClB,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC1E,kBAAkB;AAClB,wBAAgB,WAAW,CAC1B,UAAU,EAAE,MAAM,EAClB,CAAC,EAAE,MAAM,EACT,CAAC,CAAC,EAAE,MAAM,EACV,CAAC,CAAC,EAAE,MAAM,EACV,EAAE,CAAC,EAAE,MAAM,GACT,IAAI,CAAC;AAiCR;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CACrB,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,gBAAgB,EAC7B,EAAE,CAAC,EAAE,MAAM,GACT,gBAAgB,CAelB;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAS3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAE5D"}

package/build/audio/procedural.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Procedural audio — fire-and-forget envelope-shaped primitives that
+ * build on the shared `AudioContext` exposed by `backend.ts`. Designed
+ * for "just play a beep / explosion / whoosh" use cases where loading
+ * an audio file would be overkill.
+ *
+ * Two primitives:
+ *   - `tone` for pitched sources (clicks, chimes, lasers, chord pings).
+ *   - `noise` for non-pitched sources (explosions, hi-hats, swooshes,
+ *     wind, footsteps).
+ *
+ * Both share the same envelope + output routing rails so future
+ * primitives can be added with zero copy-paste.
+ */
+import type { NoiseOptions, ToneOptions } from "./types.ts";
+/**
+ * Fire a single-shot envelope-shaped oscillator on the shared
+ * {@link getAudioContext} context. Designed for the "just play a beep"
+ * niche where loading an audio file is overkill — UI clicks, hit
+ * confirms, retro arcade-style cues, placeholder feedback during
+ * prototyping.
+ *
+ * Multi-partial `freq` makes chimes, bells, and simple chords a single
+ * call; `pitchSlide` covers percussive pitch-drops and rising stings.
+ * The context is shared with file-based playback, so the usual browser
+ * autoplay gating applies: the first call after a user gesture lets
+ * every subsequent call play.
+ *
+ * **Requires WebAudio.** When WebAudio is not supported (or audio is
+ * explicitly disabled) this is a silent no-op: {@link getAudioContext}
+ * returns `null` and nothing is scheduled. Use the return value of
+ * {@link getAudioContext} to detect that case up front if your game
+ * wants to show a "no audio" badge or fall back to a different
+ * feedback channel.
+ * @param opts - the {@link ToneOptions} (frequency, duration,
+ *   envelope, pan, slide). See the interface for per-field defaults.
+ * @example
+ * // simple UI click
+ * me.audio.tone({ freq: 1200, duration: 0.08, pitchSlide: 0.5 });
+ * // chime, panned right, two partials a fifth apart
+ * me.audio.tone({ freq: [880, 1320], duration: 0.4, gain: 0.18, pan: 0.5 });
+ * // descending "thud" — square wave with a wide pitch drop
+ * me.audio.tone({ freq: 200, duration: 0.15, wave: "square", pitchSlide: 0.25 });
+ * @category Audio
+ */
+export declare function tone(opts: ToneOptions): void;
+/**
+ * Fire a single-shot envelope-shaped noise burst on the shared
+ * {@link getAudioContext} context. Sits alongside {@link tone} as the
+ * non-pitched half of the procedural-audio surface — `tone` is the right
+ * tool for anything with a clear pitch (clicks, chimes, lasers), `noise`
+ * is the right tool for anything percussive without one (explosions,
+ * hi-hats, swooshes, footsteps, wind).
+ *
+ * The output runs through the master gain shared with file-based
+ * playback, so {@link muteAll} / {@link setVolume} apply uniformly.
+ * Browser autoplay gating applies — the first call after a user
+ * gesture lets every subsequent call play.
+ *
+ * **Requires WebAudio.** When WebAudio is not supported (or audio is
+ * explicitly disabled) this is a silent no-op: {@link getAudioContext}
+ * returns `null` and nothing is scheduled.
+ * @param opts - the {@link NoiseOptions} (duration, spectral colour,
+ *   envelope, pan, optional filter + sweep). See the interface for
+ *   per-field defaults.
+ * @example
+ * // Explosion: brown rumble closing into a thud
+ * me.audio.noise({
+ *     duration: 0.8,
+ *     type: "brown",
+ *     gain: 0.4,
+ *     filter: { type: "lowpass", frequency: 800 },
+ *     filterSweep: 0.3,
+ * });
+ * // Hi-hat: short, bright, top-end only
+ * me.audio.noise({
+ *     duration: 0.05,
+ *     filter: { type: "highpass", frequency: 7000 },
+ *     gain: 0.2,
+ * });
+ * // Swoosh: bandpass white with rising sweep — UI transition, melee whoosh
+ * me.audio.noise({
+ *     duration: 0.3,
+ *     filter: { type: "bandpass", frequency: 400, Q: 1.5 },
+ *     filterSweep: 4,
+ *     gain: 0.3,
+ * });
+ * // Wind / breath: long, low-pink, no sweep
+ * me.audio.noise({
+ *     duration: 2,
+ *     type: "pink",
+ *     filter: { type: "bandpass", frequency: 600 },
+ *     gain: 0.08,
+ * });
+ * // Footstep on dirt — short brown thump
+ * me.audio.noise({
+ *     duration: 0.08,
+ *     type: "brown",
+ *     filter: { type: "lowpass", frequency: 200 },
+ *     gain: 0.25,
+ * });
+ * @category Audio
+ */
+export declare function noise(opts: NoiseOptions): void;
+//# sourceMappingURL=procedural.d.ts.map

package/build/audio/procedural.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"procedural.d.ts","sourceRoot":"","sources":["../../src/audio/procedural.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAmF5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CA0D5C;AAkDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA6D9C"}

package/build/audio/types.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Public type declarations for the audio module. Kept in a dedicated
+ * file so the runtime entry point (`audio.ts`) stays focused on
+ * implementation; consumers can import types from
+ * `me.audio` exactly as before.
+ */
+/**
+ * Sound asset descriptor passed to `audio.load`.
+ * @category Audio
+ */
+export interface SoundAsset {
+    /** Logical name used to play / stop / reference the sound later. */
+    name: string;
+    /**
+     * Base path / prefix for the audio resource. The loader builds the
+     * full URL as `${src}${name}.${ext}` for each format configured by
+     * `audio.init()`, so `src` is typically a directory ending in `/`.
+     * Data URLs (`data:audio/...`) are used as-is and skip the prefix
+     * + extension construction.
+     */
+    src: string;
+    /** Begin playback immediately on load. Defaults to `false`. */
+    autoplay?: boolean;
+    /** Loop playback when the clip ends. Defaults to `false`. */
+    loop?: boolean;
+    /**
+     * Stream the resource instead of fully decoding upfront — preferred
+     * for long music tracks. Defaults to `false`.
+     */
+    stream?: boolean;
+    /**
+     * Force the HTML5 `<audio>` element backend instead of WebAudio
+     * decoding. Defaults to `false`.
+     */
+    html5?: boolean;
+}
+/**
+ * Optional settings applied to the audio resource load. The loader
+ * uses an XHR under the hood (via Howler), so the available knobs
+ * mirror what an XHR can be told to do.
+ * @category Audio
+ */
+export interface LoadSettings {
+    /** Cache-busting query string appended to the resource URL. */
+    nocache?: string;
+    /**
+     * Forwarded to `XMLHttpRequest.withCredentials`. Set `true` so
+     * cross-origin loads include cookies / auth headers (e.g. when
+     * the audio is served from an authenticated CDN).
+     */
+    withCredentials?: boolean;
+}
+/**
+ * Spatial-audio cone + distance attributes passed to `audio.panner`.
+ * Mirrors the WebAudio `PannerNode` configuration so positional sound
+ * effects can be set up declaratively (see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics#creating_a_panner_node | MDN — creating a panner node}
+ * for an end-to-end conceptual overview).
+ * @category Audio
+ */
+export interface PannerAttributes {
+    /**
+     * Inner cone angle in degrees within which there is no volume
+     * reduction. Defaults to `360` (omnidirectional).
+     */
+    coneInnerAngle?: number | undefined;
+    /**
+     * Outer cone angle in degrees outside which the volume is reduced
+     * to `coneOuterGain`. Defaults to `360`.
+     */
+    coneOuterAngle?: number | undefined;
+    /**
+     * Linear volume multiplier (`0..1`) applied outside
+     * `coneOuterAngle`. Defaults to `0` (silent outside the cone).
+     */
+    coneOuterGain?: number | undefined;
+    /**
+     * Distance-attenuation algorithm — `"inverse"` (default), `"linear"`,
+     * or `"exponential"`. Matches the WebAudio `PannerNode.distanceModel`
+     * union.
+     */
+    distanceModel?: DistanceModelType;
+    /**
+     * Distance at which volume reduction stops (used by the `"linear"`
+     * model; clamps the falloff curve for the other one). Defaults to
+     * `10000`.
+     */
+    maxDistance?: number;
+    /**
+     * Spatialization algorithm — `"equalpower"` (cheap, stereo-only) or
+     * `"HRTF"` (head-related, full 3D). Defaults to `"HRTF"`.
+     */
+    panningModel?: "HRTF" | "equalpower";
+    /**
+     * Reference distance for the falloff curve — volume is `1` at this
+     * distance from the listener. Defaults to `1`.
+     */
+    refDistance?: number;
+    /**
+     * Steepness of the falloff curve for the `"inverse"` model.
+     * Defaults to `1`.
+     */
+    rolloffFactor?: number;
+}
+/**
+ * Optional band-shaping filter applied to the procedural noise burst
+ * produced by `noise`. Mirrors a subset of the WebAudio `BiquadFilterNode`
+ * configuration so users can sculpt the spectral colour without dropping
+ * to a custom WebAudio graph.
+ * @category Audio
+ */
+export interface NoiseFilter {
+    /**
+     * Filter shape — `"lowpass"`, `"highpass"`, `"bandpass"`,
+     * `"lowshelf"`, `"highshelf"`, `"peaking"`, `"notch"`, or
+     * `"allpass"`. See the WebAudio `BiquadFilterNode` docs.
+     */
+    type: BiquadFilterType;
+    /** Centre / cutoff frequency in Hz. */
+    frequency: number;
+    /** Filter resonance / quality factor. Defaults to the WebAudio default (`1`). */
+    Q?: number;
+}
+/**
+ * Options for `noise`.
+ * @category Audio
+ */
+export interface NoiseOptions {
+    /** Total burst length in seconds (envelope decays over this window). */
+    duration: number;
+    /**
+     * Spectral colour of the noise source:
+     *   - `"white"` — flat, all frequencies equal (default).
+     *   - `"pink"` — −3 dB / octave roll-off, perceptually balanced —
+     *     classic for breath, wind, and acoustic-sounding ambient texture.
+     *   - `"brown"` (red) — −6 dB / octave roll-off, low and rumbly —
+     *     classic for distant thunder, ocean, low-fi rumble.
+     */
+    type?: "white" | "pink" | "brown";
+    /** Peak gain at attack end, `0..1`. Defaults to `0.1`. */
+    gain?: number;
+    /**
+     * Attack time in seconds — linear ramp from 0 up to `gain`. Clamped
+     * to `[0.001, duration / 2]`. For very short durations (< 2 ms) the
+     * upper bound wins so the envelope still fits inside the playback
+     * window. Defaults to `0.005`.
+     */
+    attack?: number;
+    /**
+     * Stereo pan, `-1` (full left) to `1` (full right). Defaults to `0`.
+     */
+    pan?: number;
+    /**
+     * Optional {@link NoiseFilter} applied to the noise source before
+     * the master gain. Use this to colour the noise — a lowpass on
+     * brown noise gives "explosion thump", a highpass on white gives
+     * "hi-hat tick", a bandpass gives "swoosh".
+     */
+    filter?: NoiseFilter;
+    /**
+     * Frequency multiplier applied to {@link NoiseFilter.frequency}
+     * over `duration` as an exponential ramp. `1` = no sweep (default);
+     * `>1` = filter opens upward (rising swoosh, laser pew);
+     * `<1` = filter closes downward (descending thunk, explosion settle).
+     * Has no effect when `filter` is unset.
+     */
+    filterSweep?: number;
+}
+/**
+ * Options for `tone`.
+ * @category Audio
+ */
+export interface ToneOptions {
+    /**
+     * Carrier frequency in Hz. Pass an array to layer multiple
+     * partials (chord, bell ring, fundamental + harmonic) — they
+     * share the gain envelope, pan, and pitch slide.
+     */
+    freq: number | number[];
+    /** Total sound length in seconds (envelope decays over this window). */
+    duration: number;
+    /** Oscillator waveform. Defaults to `"sine"`. */
+    wave?: OscillatorType;
+    /** Peak gain at attack end, `0..1`. Defaults to `0.1`. */
+    gain?: number;
+    /**
+     * Attack time in seconds — linear ramp from 0 up to `gain`. Clamped
+     * to `[0.001, duration / 2]`. For very short durations (< 2 ms) the
+     * upper bound wins so the envelope still fits inside the playback
+     * window. Defaults to `0.005`.
+     */
+    attack?: number;
+    /**
+     * Stereo pan, `-1` (full left) to `1` (full right). Defaults to `0`.
+     */
+    pan?: number;
+    /**
+     * Frequency multiplier applied over `duration` as an exponential
+     * ramp. `1` = no slide (default); `0.5` = slide an octave down;
+     * `2` = slide an octave up. Useful for percussive impacts (small
+     * value < 1) or rising stings (value > 1).
+     */
+    pitchSlide?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/audio/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/audio/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;;OAIG;IACH,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IACrC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;OAIG;IACH,IAAI,EAAE,gBAAgB,CAAC;IACvB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,CAAC,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;OAIG;IACH,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/build/index.d.ts

@@ -21,8 +21,8 @@ import { ColorMatrix } from "./math/color_matrix.ts";
 import ParticleEmitter from "./particles/emitter.ts";
 import Particle from "./particles/particle.ts";
 import ParticleEmitterSettings from "./particles/settings.js";
-import Body from "./physics/body.js";
-import QuadTree from "./physics/quadtree.js";
+import Body from "./physics/builtin/body.js";
+import QuadTree from "./physics/builtin/quadtree.js";
 import World from "./physics/world.js";
 import { cache as plugins } from "./plugin/plugin.ts";
 import Collectable from "./renderable/collectable.js";
@@ -75,6 +75,7 @@ import OutlineEffect from "./video/webgl/effects/outline.js";
 import PixelateEffect from "./video/webgl/effects/pixelate.js";
 import ScanlineEffect from "./video/webgl/effects/scanline.js";
 import SepiaEffect from "./video/webgl/effects/sepia.js";
+import ShineEffect from "./video/webgl/effects/shine.js";
 import TintPulseEffect from "./video/webgl/effects/tintPulse.js";
 import VignetteEffect from "./video/webgl/effects/vignette.js";
 import WaveEffect from "./video/webgl/effects/wave.js";
@@ -105,7 +106,9 @@ export { ObservableVector2d } from "./math/observableVector2d.ts";
 export { ObservableVector3d } from "./math/observableVector3d.ts";
 export { Vector2d } from "./math/vector2d.ts";
 export { Vector3d } from "./math/vector3d.ts";
+export type { AdapterCapabilities, AdapterOptions, BodyDefinition, BodyShape, BodyType, CollisionResponse, PhysicsAdapter, PhysicsBody, RaycastHit, } from "./physics/adapter.ts";
 export { Bounds } from "./physics/bounds.ts";
+export { default as BuiltinAdapter } from "./physics/builtin/builtin-adapter.ts";
 export { collision } from "./physics/collision.js";
 export * as plugin from "./plugin/plugin.ts";
 export { getPool } from "./pool.ts";
@@ -115,7 +118,7 @@ export * as utils from "./utils/utils.ts";
 export * from "./version.ts";
 export * as video from "./video/video.js";
 export { Application, Batcher, BitmapText, BitmapTextData, BlurEffect, Body, Camera2d, CameraEffect, CanvasRenderer, CanvasRenderTarget, ChromaticAberrationEffect, Collectable, ColorLayer, ColorMatrix, ColorMatrixEffect, Container, DesaturateEffect, DissolveEffect, Draggable, DropShadowEffect, DropTarget, Entity, // eslint-disable-line @typescript-eslint/no-deprecated
-FadeEffect, FlashEffect, GLShader, GlowEffect, Gradient, HologramEffect, ImageLayer, InvertEffect, Light2d, MaskEffect, Mesh, NineSliceSprite, OutlineEffect, Particle, ParticleEmitter, ParticleEmitterSettings, PixelateEffect, Pointer, PrimitiveBatcher, plugins, pool, QuadBatcher, QuadTree, Renderable, Renderer, RenderState, RenderTarget, ScanlineEffect, SepiaEffect, ShaderEffect, ShakeEffect, Sprite, Stage, save, state, Text, TextureAtlas, Tile, TintPulseEffect, TMXHexagonalRenderer, TMXIsometricRenderer, TMXLayer, TMXOrthogonalRenderer, TMXRenderer, TMXStaggeredRenderer, TMXTileMap, TMXTileset, TMXTilesetGroup, TMXUtils, Trail, Trigger, Tween, timer, UIBaseElement, UISpriteElement, UITextButton, VignetteEffect, WaveEffect, WebGLRenderer, World, };
+FadeEffect, FlashEffect, GLShader, GlowEffect, Gradient, HologramEffect, ImageLayer, InvertEffect, Light2d, MaskEffect, Mesh, NineSliceSprite, OutlineEffect, Particle, ParticleEmitter, ParticleEmitterSettings, PixelateEffect, Pointer, PrimitiveBatcher, plugins, pool, QuadBatcher, QuadTree, Renderable, Renderer, RenderState, RenderTarget, ScanlineEffect, SepiaEffect, ShaderEffect, ShakeEffect, ShineEffect, Sprite, Stage, save, state, Text, TextureAtlas, Tile, TintPulseEffect, TMXHexagonalRenderer, TMXIsometricRenderer, TMXLayer, TMXOrthogonalRenderer, TMXRenderer, TMXStaggeredRenderer, TMXTileMap, TMXTileset, TMXTilesetGroup, TMXUtils, Trail, Trigger, Tween, timer, UIBaseElement, UISpriteElement, UITextButton, VignetteEffect, WaveEffect, WebGLRenderer, World, };
 /**
  * disable melonJS auto-initialization
  * @see {@link boot}