minimojs 1.0.0-alpha.30 → 1.0.0-alpha.31

package/README.md

@@ -91,6 +91,8 @@ Note: text defaults to `monospace`, so a game that names no font downloads none.
 
 Load images in `game.onPreload`, once, at boot. Only a game with many scenes that each carry many images of their own, such as one with many levels, should give scenes an `onPreload()` so each loads its images when the player reaches it; see `examples/level-loading/`.
 
+Sounds come from files too. Declare them as `sound` entries in an asset file, or load them with `game.loadSound(key, src)`, and play them with `game.playSound(key)`, which returns a playback you can `pause()`, `resume()`, and `stop()`; pass `{ loop: true }` for music. MP3 plays in every browser. `game.sound` and `game.soundSequence` still synthesize tones with no file at all; see `examples/sound-files/`.
+
 ## Examples
 
 - `examples/chickens-eggs-basket/`
@@ -105,6 +107,7 @@ Load images in `game.onPreload`, once, at boot. Only a game with many scenes tha
 - `examples/pseudo-3d-racer/`
 - `examples/animations/`
 - `examples/level-loading/`
+- `examples/sound-files/`
 
 Run locally from the `minimojs` directory:
 

package/dist/internal/AssetSystem.d.ts

@@ -1 +1,6 @@
-export {};
+/**
+ * Fetches and decodes one audio file. The engine passes one backed by its
+ * `AudioContext`; the asset system only stores what it returns, so it needs no
+ * audio API of its own and runs in tests without a browser.
+ */
+export type SoundLoader = (src: string) => Promise<unknown>;

package/dist/internal/AssetSystem.js

@@ -1,6 +1,13 @@
-/** @internal */
+/**
+ * Images and sounds, loaded by key. Both kinds share one queue, one progress
+ * count, one failure report, and one namespace of keys, so a game's loading
+ * screen and its retry cover every file it loads.
+ *
+ * @internal
+ */
 export class AssetSystem {
-    constructor() {
+    constructor(_soundLoader = null) {
+        this._soundLoader = _soundLoader;
         /** @internal */
         this._queuedImages = new Map();
         /** @internal */
@@ -19,6 +26,12 @@ export class AssetSystem {
         this._assetFileByKey = new Map();
         /** @internal */
         this._registeredAssetFiles = new WeakSet();
+        /** @internal */
+        this._queuedSounds = new Map();
+        /** @internal */
+        this._loadedSounds = new Map();
+        /** @internal */
+        this._soundSources = new Map();
     }
     queueImage(key, src) {
         const safeKey = key.trim();
@@ -30,8 +43,24 @@ export class AssetSystem {
             throw new Error("MinimoJS: Image sources must be non-empty strings.");
         }
         this.refuseAssetFileKey(safeKey, "loadImage()");
+        this.refuseSoundKey(safeKey, "loadImage()");
         this.enqueueImage(safeKey, safeSrc);
     }
+    queueSound(key, src) {
+        const safeKey = key.trim();
+        const safeSrc = src.trim();
+        if (safeKey.length === 0) {
+            throw new Error("MinimoJS: Sound keys must be non-empty strings.");
+        }
+        if (safeSrc.length === 0) {
+            throw new Error("MinimoJS: Sound sources must be non-empty strings.");
+        }
+        this.refuseAssetFileKey(safeKey, "loadSound()");
+        if (this._imageSources.has(safeKey) || this._loadedImages.has(safeKey)) {
+            throw new Error(`MinimoJS: loadSound() cannot use the key "${safeKey}", which an image uses. Keys must be unique in the whole game.`);
+        }
+        this.enqueueSound(safeKey, safeSrc);
+    }
     /**
      * Registers a parsed asset file and queues its images. `source` is the
      * object the game passed, which identifies the file, so loading the same
@@ -48,6 +77,9 @@ export class AssetSystem {
                 if (this._imageSources.has(entry.key) || this._loadedImages.has(entry.key)) {
                     throw new Error(`MinimoJS: Asset key "${entry.key}" is already registered with loadImage() or createTexture(). Keys must be unique in the whole game.`);
                 }
+                if (this._soundSources.has(entry.key)) {
+                    throw new Error(`MinimoJS: Asset key "${entry.key}" is already registered with loadSound(). Keys must be unique in the whole game.`);
+                }
             }
             else if (owner !== source) {
                 throw new Error(`MinimoJS: Asset key "${entry.key}" is declared by two asset files. Keys must be unique in the whole game.`);
@@ -58,6 +90,9 @@ export class AssetSystem {
             if (entry.type === "image") {
                 this.enqueueImage(entry.key, entry.src.trim());
             }
+            else if (entry.type === "sound") {
+                this.enqueueSound(entry.key, entry.src.trim());
+            }
         }
         const isFirstRegistration = !this._registeredAssetFiles.has(source);
         this._registeredAssetFiles.add(source);
@@ -72,6 +107,17 @@ export class AssetSystem {
         this._imageSources.set(safeKey, safeSrc);
         this._queuedImages.set(safeKey, safeSrc);
     }
+    /** @internal */
+    enqueueSound(safeKey, safeSrc) {
+        const existingSrc = this._soundSources.get(safeKey);
+        if (existingSrc !== undefined && existingSrc !== safeSrc) {
+            throw new Error(`MinimoJS: Sound key "${safeKey}" is already registered with a different source.`);
+        }
+        this._soundSources.set(safeKey, safeSrc);
+        if (!this._loadedSounds.has(safeKey)) {
+            this._queuedSounds.set(safeKey, safeSrc);
+        }
+    }
     createTexture(key, width, height, painter) {
         const safeKey = key.trim();
         if (safeKey.length === 0) {
@@ -81,6 +127,7 @@ export class AssetSystem {
             throw new Error("MinimoJS: createTexture() requires a painter function.");
         }
         this.refuseAssetFileKey(safeKey, "createTexture()");
+        this.refuseSoundKey(safeKey, "createTexture()");
         const canvas = document.createElement("canvas");
         canvas.width = Math.max(1, Math.round(Number.isFinite(width) ? width : 1));
         canvas.height = Math.max(1, Math.round(Number.isFinite(height) ? height : 1));
@@ -105,45 +152,78 @@ export class AssetSystem {
     hasImage(key) {
         return this._loadedImages.has(key);
     }
-    getQueuedImageCount() {
+    /** Returns a decoded sound, as the sound loader returned it, if it is loaded. */
+    getSound(key) {
+        return this._loadedSounds.get(key);
+    }
+    hasSound(key) {
+        return this._loadedSounds.has(key);
+    }
+    /** Counts the queued images and sounds that are not loaded yet. */
+    getQueuedAssetCount() {
         let total = 0;
         for (const key of this._queuedImages.keys()) {
             if (!this._loadedImages.has(key)) {
                 total++;
             }
         }
+        for (const key of this._queuedSounds.keys()) {
+            if (!this._loadedSounds.has(key)) {
+                total++;
+            }
+        }
         return total;
     }
     /**
-     * Loads every queued image that is not loaded yet, settling all of them
-     * before returning instead of stopping at the first failure.
+     * Loads every queued image and sound that is not loaded yet, settling all
+     * of them before returning instead of stopping at the first failure.
      *
-     * Loaded images leave the queue; failed ones stay in it, so a retry loads
+     * Loaded files leave the queue; failed ones stay in it, so a retry loads
      * only them. Returns the keys that failed, empty when all loaded.
      */
-    async loadQueuedImages(onProgress) {
-        const entries = [...this._queuedImages.entries()].filter(([key]) => !this._loadedImages.has(key));
-        const total = entries.length;
+    async loadQueuedAssets(onProgress) {
+        const images = [...this._queuedImages.entries()].filter(([key]) => !this._loadedImages.has(key));
+        const sounds = [...this._queuedSounds.entries()].filter(([key]) => !this._loadedSounds.has(key));
+        const total = images.length + sounds.length;
         let settled = 0;
         const failed = [];
         onProgress?.(0, total, null);
         if (total === 0) {
             this._queuedImages.clear();
+            this._queuedSounds.clear();
             return failed;
         }
-        await Promise.all(entries.map(async ([key, src]) => {
-            try {
-                const image = await this.loadImage(src);
-                this._loadedImages.set(key, image);
-                this.bumpImageVersion(key);
-                this._queuedImages.delete(key);
-            }
-            catch {
-                failed.push(key);
-            }
+        const settle = (key) => {
             settled += 1;
             onProgress?.(settled, total, key);
-        }));
+        };
+        await Promise.all([
+            ...images.map(async ([key, src]) => {
+                try {
+                    const image = await this.loadImage(src);
+                    this._loadedImages.set(key, image);
+                    this.bumpImageVersion(key);
+                    this._queuedImages.delete(key);
+                }
+                catch {
+                    failed.push(key);
+                }
+                settle(key);
+            }),
+            ...sounds.map(async ([key, src]) => {
+                try {
+                    if (!this._soundLoader) {
+                        throw new Error("MinimoJS: This game cannot load sounds.");
+                    }
+                    this._loadedSounds.set(key, await this._soundLoader(src));
+                    this._queuedSounds.delete(key);
+                }
+                catch {
+                    failed.push(key);
+                }
+                settle(key);
+            }),
+        ]);
         for (const key of [...this._queuedImages.keys()]) {
             if (this._loadedImages.has(key)) {
                 this._queuedImages.delete(key);
@@ -151,16 +231,23 @@ export class AssetSystem {
         }
         return failed;
     }
-    /** Returns the source registered for an image key, if any. */
-    getImageSource(key) {
-        return this._imageSources.get(key);
+    /** Returns the source registered for an image or sound key, if any. */
+    getAssetSource(key) {
+        return this._imageSources.get(key) ?? this._soundSources.get(key);
     }
     /**
-     * Drops queued images that were not loaded, so a later load does not pick
-     * them up. Their keys may be registered again.
+     * Drops queued images and sounds that were not loaded, so a later load does
+     * not pick them up. Their keys may be registered again.
      */
-    discardQueuedImages() {
+    discardQueuedAssets() {
         this._queuedImages.clear();
+        this._queuedSounds.clear();
+    }
+    /** @internal */
+    refuseSoundKey(safeKey, caller) {
+        if (this._soundSources.has(safeKey)) {
+            throw new Error(`MinimoJS: ${caller} cannot use the key "${safeKey}", which a sound uses. Keys must be unique in the whole game.`);
+        }
     }
     /** @internal */
     refuseAssetFileKey(safeKey, caller) {

package/dist/internal/SoundSystem.d.ts

@@ -1 +1,39 @@
-export {};
+/** Options for one play of a loaded sound. */
+export interface PlaySoundOptions {
+    /** Repeat the sound until it is stopped. Default `false`. */
+    loop?: boolean;
+    /** Volume from `0`, silent, to `1`, as recorded. Default `1`. */
+    volume?: number;
+}
+/** Where a {@link SoundPlayback} is: playing, paused, or stopped for good. */
+export type SoundPlaybackState = "playing" | "paused" | "stopped";
+/**
+ * One play of a loaded sound, returned by `game.playSound`. Keep it to pause,
+ * resume, or stop that play, such as the game's music:
+ *
+ * ```ts
+ * const music = game.playSound("theme", { loop: true, volume: 0.6 });
+ * music.pause();
+ * music.resume();
+ * music.stop();
+ * ```
+ *
+ * A stopped play cannot be resumed; call `game.playSound` again.
+ */
+export declare class SoundPlayback {
+    /** The key the sound was loaded under. */
+    readonly key: string;
+    /** Whether this play repeats until stopped. */
+    readonly loop: boolean;
+    /** `"playing"`, `"paused"`, or `"stopped"`. A one-shot play stops by itself when it ends. */
+    get state(): SoundPlaybackState;
+    /** This play's volume, from `0` to `1`. Takes effect immediately. */
+    get volume(): number;
+    set volume(value: number);
+    /** Pauses the play where it is. Does nothing unless it is playing. */
+    pause(): void;
+    /** Continues a paused play from where it paused. Does nothing unless it is paused. */
+    resume(): void;
+    /** Stops the play for good. */
+    stop(): void;
+}

package/dist/internal/SoundSystem.js

@@ -1,8 +1,153 @@
+/**
+ * One play of a loaded sound, returned by `game.playSound`. Keep it to pause,
+ * resume, or stop that play, such as the game's music:
+ *
+ * ```ts
+ * const music = game.playSound("theme", { loop: true, volume: 0.6 });
+ * music.pause();
+ * music.resume();
+ * music.stop();
+ * ```
+ *
+ * A stopped play cannot be resumed; call `game.playSound` again.
+ */
+export class SoundPlayback {
+    /** @internal */
+    constructor(
+    /** The key the sound was loaded under. */
+    key, 
+    /** Whether this play repeats until stopped. */
+    loop, volume, 
+    /** @internal */
+    _system, 
+    /** @internal */
+    _buffer) {
+        this.key = key;
+        this.loop = loop;
+        this._system = _system;
+        this._buffer = _buffer;
+        /** @internal */
+        this._state = "playing";
+        /** @internal */
+        this._source = null;
+        /** @internal */
+        this._gain = null;
+        /** Seconds into the sound where the current source started, or where it was paused. @internal */
+        this._offset = 0;
+        /** The context time at which the current source started. @internal */
+        this._startedAt = 0;
+        this._volume = clampVolume(volume);
+        if (!_system || !_buffer) {
+            this._state = "stopped";
+            return;
+        }
+        this._startSource();
+    }
+    /** `"playing"`, `"paused"`, or `"stopped"`. A one-shot play stops by itself when it ends. */
+    get state() {
+        return this._state;
+    }
+    /** This play's volume, from `0` to `1`. Takes effect immediately. */
+    get volume() {
+        return this._volume;
+    }
+    set volume(value) {
+        this._volume = clampVolume(value);
+        if (this._gain) {
+            this._gain.gain.value = this._volume;
+        }
+    }
+    /** Pauses the play where it is. Does nothing unless it is playing. */
+    pause() {
+        if (this._state !== "playing" || !this._system || !this._buffer)
+            return;
+        const elapsed = this._system.context.currentTime - this._startedAt;
+        const position = this._offset + Math.max(0, elapsed);
+        this._offset = this.loop
+            ? position % this._buffer.duration
+            : Math.min(position, this._buffer.duration);
+        this._stopSource();
+        this._state = "paused";
+    }
+    /** Continues a paused play from where it paused. Does nothing unless it is paused. */
+    resume() {
+        if (this._state !== "paused")
+            return;
+        this._state = "playing";
+        this._startSource();
+    }
+    /** Stops the play for good. */
+    stop() {
+        if (this._state === "stopped")
+            return;
+        this._stopSource();
+        this._state = "stopped";
+        this._system?.forget(this);
+    }
+    /** @internal */
+    _startSource() {
+        const system = this._system;
+        const buffer = this._buffer;
+        if (!system || !buffer)
+            return;
+        const ctx = system.context;
+        const gain = ctx.createGain();
+        gain.gain.value = this._volume;
+        gain.connect(ctx.destination);
+        const source = ctx.createBufferSource();
+        source.buffer = buffer;
+        source.loop = this.loop;
+        source.connect(gain);
+        source.onended = () => {
+            if (this._source !== source)
+                return;
+            this._source = null;
+            this._gain = null;
+            gain.disconnect();
+            this._state = "stopped";
+            system.forget(this);
+        };
+        this._source = source;
+        this._gain = gain;
+        this._startedAt = ctx.currentTime;
+        source.start(0, this._offset);
+        system.remember(this);
+    }
+    /** @internal */
+    _stopSource() {
+        const source = this._source;
+        const gain = this._gain;
+        this._source = null;
+        this._gain = null;
+        if (source) {
+            source.onended = null;
+            try {
+                source.stop();
+            }
+            catch {
+                // A source that already ended throws on some browsers.
+            }
+            source.disconnect();
+        }
+        gain?.disconnect();
+    }
+}
+function clampVolume(value) {
+    if (!Number.isFinite(value))
+        return 1;
+    return Math.min(1, Math.max(0, value));
+}
+/** The events that count as the player's first gesture, which lets a page play sound. */
+const UNLOCK_EVENTS = ["pointerdown", "touchend", "mousedown", "keydown"];
 /** @internal */
 export class SoundSystem {
     constructor() {
         /** @internal */
         this._audioCtx = null;
+        /** @internal */
+        this._playing = new Set();
+        /** Whether the page hid while sound could play, so showing it again resumes. @internal */
+        this._suspendedByHiding = false;
     }
     sound(freq, durationMs) {
         const ctx = this.getAudioContext();
@@ -41,15 +186,107 @@ export class SoundSystem {
             startTime += durationSec;
         }
     }
+    /**
+     * Fetches and decodes an audio file. Used by the asset system to load the
+     * sounds a game queues, so a file the browser cannot decode fails while the
+     * game loads, with every other file that failed.
+     */
+    async decode(src) {
+        const response = await fetch(src);
+        if (!response.ok) {
+            throw new Error(`MinimoJS: Failed to load sound "${src}" (HTTP ${response.status}).`);
+        }
+        const data = await response.arrayBuffer();
+        const ctx = this.getAudioContext();
+        // The callback form, because older Safari returns no promise.
+        return new Promise((resolve, reject) => {
+            const result = ctx.decodeAudioData(data, resolve, reject);
+            result?.catch?.(reject);
+        });
+    }
+    /**
+     * Plays a decoded sound. Before the player's first gesture the page cannot
+     * play sound: a looping play waits and starts with that gesture, while a
+     * one-shot play is dropped, so effects queued meanwhile do not all sound at
+     * once. A dropped play is returned already stopped.
+     */
+    play(key, buffer, options = {}) {
+        const loop = options.loop === true;
+        const volume = options.volume ?? 1;
+        const ctx = this.getAudioContext();
+        if (!loop && ctx.state !== "running") {
+            return new SoundPlayback(key, loop, volume, null, null);
+        }
+        return new SoundPlayback(key, loop, volume, this, buffer);
+    }
+    /** Stops every play of a loaded sound. Synthesized tones are not affected. */
+    stopAll() {
+        for (const playback of [...this._playing]) {
+            playback.stop();
+        }
+    }
+    /** @internal */
+    get context() {
+        return this.getAudioContext();
+    }
+    /** @internal */
+    remember(playback) {
+        this._playing.add(playback);
+    }
+    /** @internal */
+    forget(playback) {
+        this._playing.delete(playback);
+    }
     /** @internal */
     getAudioContext() {
         if (!this._audioCtx) {
             this._audioCtx = new AudioContext();
+            this.listenForUnlockAndVisibility();
         }
         const ctx = this._audioCtx;
-        if (ctx.state === "suspended") {
-            ctx.resume();
+        if (ctx.state === "suspended" && !this._suspendedByHiding) {
+            void ctx.resume().catch(() => { });
         }
         return ctx;
     }
+    /**
+     * Resumes the context on the player's first gesture, which is what lets a
+     * browser play sound, and pauses all sound while the page is hidden.
+     *
+     * @internal
+     */
+    listenForUnlockAndVisibility() {
+        if (typeof window === "undefined")
+            return;
+        const unlock = () => {
+            const ctx = this._audioCtx;
+            if (!ctx || this._suspendedByHiding)
+                return;
+            if (ctx.state === "running") {
+                for (const type of UNLOCK_EVENTS)
+                    window.removeEventListener(type, unlock, true);
+                return;
+            }
+            void ctx.resume().catch(() => { });
+        };
+        for (const type of UNLOCK_EVENTS)
+            window.addEventListener(type, unlock, true);
+        if (typeof document === "undefined")
+            return;
+        document.addEventListener("visibilitychange", () => {
+            const ctx = this._audioCtx;
+            if (!ctx)
+                return;
+            if (document.visibilityState === "hidden") {
+                if (ctx.state === "running") {
+                    this._suspendedByHiding = true;
+                    void ctx.suspend().catch(() => { });
+                }
+            }
+            else if (this._suspendedByHiding) {
+                this._suspendedByHiding = false;
+                void ctx.resume().catch(() => { });
+            }
+        });
+    }
 }

package/dist/minimo-format.d.ts

@@ -30,6 +30,27 @@ export interface ImageAsset {
     /** The image's URL or path, as `game.loadImage(key, src)` takes it. Non-empty. */
     src: string;
 }
+/**
+ * A sound declared in an asset file, loaded as
+ * `game.loadSound(key, src)` would load it, and played with
+ * `game.playSound(key)`.
+ *
+ * @example
+ * ```json
+ * { "key": "jump", "type": "sound", "src": "assets/jump.mp3" }
+ * ```
+ */
+export interface SoundAsset {
+    /**
+     * The key `game.playSound` uses for this sound. Non-empty, with no leading
+     * or trailing spaces, and unique in the whole game, images included.
+     */
+    key: string;
+    /** Always `"sound"`. */
+    type: "sound";
+    /** The audio file's URL or path, as `game.loadSound(key, src)` takes it. Non-empty. */
+    src: string;
+}
 /**
  * An entry whose `type` this engine does not support, such as one written for
  * a newer engine. It is kept as written, so a tool that saves the file does
@@ -58,7 +79,8 @@ export interface UnknownAsset {
  *   "version": 1,
  *   "assets": [
  *     { "key": "player", "type": "image", "src": "assets/player.png" },
- *     { "key": "bat", "type": "image", "src": "assets/bat.png" }
+ *     { "key": "bat", "type": "image", "src": "assets/bat.png" },
+ *     { "key": "jump", "type": "sound", "src": "assets/jump.mp3" }
  *   ]
  * }
  * ```
@@ -69,7 +91,7 @@ export interface AssetFile {
     /** The version of the file's shape. Version `1` is the only one so far. */
     version: 1;
     /** The declared assets, in file order. */
-    assets: (ImageAsset | UnknownAsset)[];
+    assets: (ImageAsset | SoundAsset | UnknownAsset)[];
 }
 /**
  * Validates the content of an asset file and returns a copy of it.
@@ -81,7 +103,7 @@ export interface AssetFile {
  * - an entry without a string `key` and `type`;
  * - an empty key, or one with leading or trailing spaces;
  * - a key repeated in the file, whatever the types of its entries;
- * - an `image` entry without a non-empty string `src`.
+ * - an `image` or `sound` entry without a non-empty string `src`.
  *
  * An entry of a type this engine does not support is kept unchanged, without
  * checking its other fields, so nothing is lost when a tool saves the file.

package/dist/minimo-format.js

@@ -13,7 +13,8 @@ const ASSET_FILE_FORMAT = "minimo-assets";
 /** The newest asset file `version` this engine reads. */
 const ASSET_FILE_VERSION = 1;
 const ASSET_FILE_FIELDS = new Set(["format", "version", "assets"]);
-const IMAGE_ASSET_FIELDS = new Set(["key", "type", "src"]);
+/** The fields of each supported entry type; `image` and `sound` share theirs. */
+const SRC_ASSET_FIELDS = new Set(["key", "type", "src"]);
 /**
  * Validates the content of an asset file and returns a copy of it.
  *
@@ -24,7 +25,7 @@ const IMAGE_ASSET_FIELDS = new Set(["key", "type", "src"]);
  * - an entry without a string `key` and `type`;
  * - an empty key, or one with leading or trailing spaces;
  * - a key repeated in the file, whatever the types of its entries;
- * - an `image` entry without a non-empty string `src`.
+ * - an `image` or `sound` entry without a non-empty string `src`.
  *
  * An entry of a type this engine does not support is kept unchanged, without
  * checking its other fields, so nothing is lost when a tool saves the file.
@@ -81,8 +82,8 @@ export function parseAssetFile(json) {
         if (typeof type !== "string" || type.length === 0) {
             throw assetError(`${where} ("${key}") must have a string "type", found ${describe(type)}.`);
         }
-        if (type === "image") {
-            rejectUnknownFields(entry, IMAGE_ASSET_FIELDS, `${where} ("${key}")`);
+        if (type === "image" || type === "sound") {
+            rejectUnknownFields(entry, SRC_ASSET_FIELDS, `${where} ("${key}")`);
             const src = entry.src;
             if (typeof src !== "string" || src.trim().length === 0) {
                 throw assetError(`${where} ("${key}") must have a non-empty string "src", found ${describe(src)}.`);

package/dist/minimo.d.ts

@@ -7,9 +7,13 @@
  * ALL ROTATIONS ARE IN DEGREES.
  * THE ENGINE LOOP USES requestAnimationFrame ONLY.
  */
+import { SoundPlayback } from "./internal/SoundSystem.js";
+import type { PlaySoundOptions } from "./internal/SoundSystem.js";
 import type { DesignObject } from "./minimo-format.js";
 export { Design, parseAssetFile } from "./minimo-format.js";
-export type { AssetFile, DesignBackground, DesignEmoji, DesignFile, DesignImage, DesignObject, DesignObjectBase, DesignObjectType, DesignSpriteBase, DesignText, ImageAsset, UnknownAsset, } from "./minimo-format.js";
+export { SoundPlayback } from "./internal/SoundSystem.js";
+export type { PlaySoundOptions, SoundPlaybackState } from "./internal/SoundSystem.js";
+export type { AssetFile, DesignBackground, DesignEmoji, DesignFile, DesignImage, DesignObject, DesignObjectBase, DesignObjectType, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, UnknownAsset, } from "./minimo-format.js";
 /**
  * Optional tuning values for {@link Game.animateExplode}.
  *
@@ -200,8 +204,8 @@ export interface IScene {
      *
      * Called whenever the scene is entered — by {@link Game.start},
      * {@link Game.reset}, or {@link Game.transitionTo} — before
-     * {@link IScene.onCreate}. Call {@link Game.loadAssets} or
-     * {@link Game.loadImage} inside it, as inside `game.onPreload`. Images that
+     * {@link IScene.onCreate}. Call {@link Game.loadAssets},
+     * {@link Game.loadImage}, or {@link Game.loadSound} inside it, as inside `game.onPreload`. Images that
      * are already loaded are skipped, so replaying a scene loads nothing.
      *
      * When images are pending, the scene being left freezes, dimmed, under a
@@ -1306,15 +1310,15 @@ export declare class Game {
     /**
      * Asset registration callback invoked once before the first scene is created.
      *
-     * This is the normal place to load a game's images. Use it to register them
-     * with {@link Game.loadAssets} or {@link Game.loadImage}. The callback is synchronous: it should only
+     * This is the normal place to load a game's images and sounds. Use it to register them
+     * with {@link Game.loadAssets}, {@link Game.loadImage}, or {@link Game.loadSound}. The callback is synchronous: it should only
      * queue assets, not await network work.
      *
-     * After `onPreload` returns, MinimoJS loads the queued images, together with
+     * After `onPreload` returns, MinimoJS loads the queued images and sounds, together with
      * those of the first scene's {@link IScene.onPreload} if it has one, and
-     * shows a loading line until they are ready. If any image fails, it asks the
+     * shows a loading line until they are ready. If any file fails, it asks the
      * player with `window.confirm` whether to retry them; declining leaves the
-     * game on the loading screen and reports the failed images on the console.
+     * game on the loading screen and reports the failed files on the console.
      *
      * @example
      * ```ts
@@ -1541,9 +1545,37 @@ export declare class Game {
      * ```
      */
     loadImage(key: string, src: string): void;
+    /**
+     * Queues an audio file to be loaded during {@link Game.onPreload}, to play
+     * later with {@link Game.playSound}.
+     *
+     * Like {@link Game.loadImage}, it only registers the sound, and may only be
+     * called from within {@link Game.onPreload} or a scene's
+     * {@link IScene.onPreload}. The file loads and decodes with the images,
+     * under the same loading line, and a file that fails is retried with them.
+     * Keys are unique in the whole game: a sound cannot share its key with an
+     * image. Prefer declaring sounds in an asset file, as `sound` entries
+     * loaded with {@link Game.loadAssets}.
+     *
+     * MP3 plays in every browser; WAV does too, but its files are large. OGG
+     * does not play in every Safari.
+     *
+     * @param key - Stable key used later by {@link Game.playSound}.
+     * @param src - Audio file URL or relative path.
+     *
+     * @example
+     * ```ts
+     * game.onPreload = () => {
+     *   game.loadSound("jump", "assets/jump.mp3");
+     *   game.loadSound("theme", "assets/theme.mp3");
+     * };
+     * ```
+     */
+    loadSound(key: string, src: string): void;
     /**
      * Queues every asset an asset file declares, as one {@link Game.loadImage}
-     * call per `image` entry would.
+     * call per `image` entry and one {@link Game.loadSound} call per `sound`
+     * entry would.
      *
      * Pass the content of a `*.assets.json` file, obtained by JSON import. The
      * file is checked with {@link parseAssetFile}, and an invalid one throws an
@@ -1552,11 +1584,11 @@ export declare class Game {
      * {@link IScene.onPreload}.
      *
      * - Keys are unique in the whole game. A key that another asset file
-     *   declares, or that {@link Game.loadImage} or {@link Game.createTexture}
-     *   registered, throws an error naming it, and so does a later
+     *   declares, or that {@link Game.loadImage}, {@link Game.loadSound}, or
+     *   {@link Game.createTexture} registered, throws an error naming it, and so does a later
      *   `loadImage` or `createTexture` of a key an asset file declares.
      * - Loading the same file again, as a scene's `onPreload()` does each time
-     *   the scene is entered, queues only its images that are not loaded.
+     *   the scene is entered, queues only its files that are not loaded.
      * - An entry of a type this engine does not support is skipped, with a
      *   console warning naming it, so the game still loads every asset it can.
      *
@@ -1989,11 +2021,56 @@ export declare class Game {
      * ```
      */
     isMobileDevice(): boolean;
+    /**
+     * Plays a sound loaded with {@link Game.loadSound} or an asset file's
+     * `sound` entry, and returns its {@link SoundPlayback}.
+     *
+     * Plays overlap: playing a sound that is already playing starts another
+     * play of it. Keep the returned playback to pause, resume, or stop it, such
+     * as the game's music. A one-shot play stops by itself when it ends; a
+     * looping one plays until stopped.
+     *
+     * - **Before the first tap.** Browsers keep a page silent until the player
+     *   taps, clicks, or presses a key. A looping sound started earlier, such as
+     *   music started in a scene's `onCreate()`, waits and begins with that
+     *   first gesture. A one-shot sound played earlier is dropped, and its
+     *   playback is returned already stopped.
+     * - **Scenes.** {@link Game.reset} and {@link Game.transitionTo} do not stop
+     *   sounds. Stop the music yourself when a scene should change it.
+     * - **Hidden page.** Every sound pauses while the page is hidden, and
+     *   continues when it is shown again.
+     *
+     * Throws an error naming the key when no sound is loaded under it.
+     *
+     * @param key - A key loaded with {@link Game.loadSound} or an asset file.
+     * @param options - `loop` to repeat until stopped, and `volume` from `0` to `1`.
+     *
+     * @example
+     * ```ts
+     * game.playSound("jump");
+     * const music = game.playSound("theme", { loop: true, volume: 0.6 });
+     * music.pause();
+     * music.resume();
+     * music.stop();
+     * ```
+     */
+    playSound(key: string, options?: PlaySoundOptions): SoundPlayback;
+    /**
+     * Stops every sound playing from a file, such as music and effects started
+     * with {@link Game.playSound}. Synthesized tones are not affected.
+     *
+     * @example
+     * ```ts
+     * game.stopAllSounds();
+     * ```
+     */
+    stopAllSounds(): void;
     /**
      * Plays a square-wave beep using the Web Audio API.
      *
-     * **Square wave only.** MinimoJS does not support audio files, samples,
-     * or other waveforms. Only procedural square-wave tones.
+     * **Square wave only.** This synthesizes a tone and needs no file. To play
+     * a recorded sound, load it with {@link Game.loadSound} and play it with
+     * {@link Game.playSound}.
      *
      * The AudioContext is created lazily on first call. Browsers require a user
      * gesture (click, keypress) before audio can play — always call `sound()` in

package/dist/minimo.js

@@ -24,6 +24,7 @@ import { TransitionSystem } from "./internal/TransitionSystem.js";
 import { TimerSystem } from "./internal/TimerSystem.js";
 import { Design, findFirst, parseAssetFile, parseDesignObject } from "./minimo-format.js";
 export { Design, parseAssetFile } from "./minimo-format.js";
+export { SoundPlayback } from "./internal/SoundSystem.js";
 /** How long a scene may load before it dims and its progress ring appears, so a fast load shows neither. */
 const SCENE_LOADING_INDICATOR_DELAY_MS = 250;
 /** How long the dimming and the ring take to fade in once they appear. */
@@ -1448,15 +1449,15 @@ export class Game {
         /**
          * Asset registration callback invoked once before the first scene is created.
          *
-         * This is the normal place to load a game's images. Use it to register them
-         * with {@link Game.loadAssets} or {@link Game.loadImage}. The callback is synchronous: it should only
+         * This is the normal place to load a game's images and sounds. Use it to register them
+         * with {@link Game.loadAssets}, {@link Game.loadImage}, or {@link Game.loadSound}. The callback is synchronous: it should only
          * queue assets, not await network work.
          *
-         * After `onPreload` returns, MinimoJS loads the queued images, together with
+         * After `onPreload` returns, MinimoJS loads the queued images and sounds, together with
          * those of the first scene's {@link IScene.onPreload} if it has one, and
-         * shows a loading line until they are ready. If any image fails, it asks the
+         * shows a loading line until they are ready. If any file fails, it asks the
          * player with `window.confirm` whether to retry them; declining leaves the
-         * game on the loading screen and reports the failed images on the console.
+         * game on the loading screen and reports the failed files on the console.
          *
          * @example
          * ```ts
@@ -1504,9 +1505,9 @@ export class Game {
         this._physicsSystem = new PhysicsSystem();
         this._spriteSystem = new SpriteSystem(this._animationSystem, this);
         this._backgroundSystem = new BackgroundSystem();
-        this._assetSystem = new AssetSystem();
-        this._inputSystem = new InputSystem(this, this._canvas);
         this._soundSystem = new SoundSystem();
+        this._assetSystem = new AssetSystem((src) => this._soundSystem.decode(src));
+        this._inputSystem = new InputSystem(this, this._canvas);
         this._textSystem = new TextSystem();
         this._renderSystem = new RenderSystem();
         this._explosionSystem = new ExplosionSystem();
@@ -1697,9 +1698,42 @@ export class Game {
         }
         this._assetSystem.queueImage(key, src);
     }
+    /**
+     * Queues an audio file to be loaded during {@link Game.onPreload}, to play
+     * later with {@link Game.playSound}.
+     *
+     * Like {@link Game.loadImage}, it only registers the sound, and may only be
+     * called from within {@link Game.onPreload} or a scene's
+     * {@link IScene.onPreload}. The file loads and decodes with the images,
+     * under the same loading line, and a file that fails is retried with them.
+     * Keys are unique in the whole game: a sound cannot share its key with an
+     * image. Prefer declaring sounds in an asset file, as `sound` entries
+     * loaded with {@link Game.loadAssets}.
+     *
+     * MP3 plays in every browser; WAV does too, but its files are large. OGG
+     * does not play in every Safari.
+     *
+     * @param key - Stable key used later by {@link Game.playSound}.
+     * @param src - Audio file URL or relative path.
+     *
+     * @example
+     * ```ts
+     * game.onPreload = () => {
+     *   game.loadSound("jump", "assets/jump.mp3");
+     *   game.loadSound("theme", "assets/theme.mp3");
+     * };
+     * ```
+     */
+    loadSound(key, src) {
+        if (!this._isRegisteringPreloadAssets) {
+            throw new Error("MinimoJS: loadSound() may only be called inside game.onPreload or a scene's onPreload().");
+        }
+        this._assetSystem.queueSound(key, src);
+    }
     /**
      * Queues every asset an asset file declares, as one {@link Game.loadImage}
-     * call per `image` entry would.
+     * call per `image` entry and one {@link Game.loadSound} call per `sound`
+     * entry would.
      *
      * Pass the content of a `*.assets.json` file, obtained by JSON import. The
      * file is checked with {@link parseAssetFile}, and an invalid one throws an
@@ -1708,11 +1742,11 @@ export class Game {
      * {@link IScene.onPreload}.
      *
      * - Keys are unique in the whole game. A key that another asset file
-     *   declares, or that {@link Game.loadImage} or {@link Game.createTexture}
-     *   registered, throws an error naming it, and so does a later
+     *   declares, or that {@link Game.loadImage}, {@link Game.loadSound}, or
+     *   {@link Game.createTexture} registered, throws an error naming it, and so does a later
      *   `loadImage` or `createTexture` of a key an asset file declares.
      * - Loading the same file again, as a scene's `onPreload()` does each time
-     *   the scene is entered, queues only its images that are not loaded.
+     *   the scene is entered, queues only its files that are not loaded.
      * - An entry of a type this engine does not support is skipped, with a
      *   console warning naming it, so the game still loads every asset it can.
      *
@@ -1734,7 +1768,7 @@ export class Game {
         if (!isFirstLoad)
             return;
         for (const entry of file.assets) {
-            if (entry.type !== "image") {
+            if (entry.type !== "image" && entry.type !== "sound") {
                 console.warn(`MinimoJS: Skipped the asset "${entry.key}", whose type "${entry.type}" this version of MinimoJS does not support.`);
             }
         }
@@ -2307,11 +2341,64 @@ export class Game {
     // -------------------------------------------------------------------------
     // Sound
     // -------------------------------------------------------------------------
+    /**
+     * Plays a sound loaded with {@link Game.loadSound} or an asset file's
+     * `sound` entry, and returns its {@link SoundPlayback}.
+     *
+     * Plays overlap: playing a sound that is already playing starts another
+     * play of it. Keep the returned playback to pause, resume, or stop it, such
+     * as the game's music. A one-shot play stops by itself when it ends; a
+     * looping one plays until stopped.
+     *
+     * - **Before the first tap.** Browsers keep a page silent until the player
+     *   taps, clicks, or presses a key. A looping sound started earlier, such as
+     *   music started in a scene's `onCreate()`, waits and begins with that
+     *   first gesture. A one-shot sound played earlier is dropped, and its
+     *   playback is returned already stopped.
+     * - **Scenes.** {@link Game.reset} and {@link Game.transitionTo} do not stop
+     *   sounds. Stop the music yourself when a scene should change it.
+     * - **Hidden page.** Every sound pauses while the page is hidden, and
+     *   continues when it is shown again.
+     *
+     * Throws an error naming the key when no sound is loaded under it.
+     *
+     * @param key - A key loaded with {@link Game.loadSound} or an asset file.
+     * @param options - `loop` to repeat until stopped, and `volume` from `0` to `1`.
+     *
+     * @example
+     * ```ts
+     * game.playSound("jump");
+     * const music = game.playSound("theme", { loop: true, volume: 0.6 });
+     * music.pause();
+     * music.resume();
+     * music.stop();
+     * ```
+     */
+    playSound(key, options) {
+        const buffer = this._assetSystem.getSound(key);
+        if (buffer === undefined) {
+            throw new Error(`MinimoJS: No sound is loaded under the key "${key}". Load it with game.loadSound() or an asset file's "sound" entry in an onPreload hook.`);
+        }
+        return this._soundSystem.play(key, buffer, options);
+    }
+    /**
+     * Stops every sound playing from a file, such as music and effects started
+     * with {@link Game.playSound}. Synthesized tones are not affected.
+     *
+     * @example
+     * ```ts
+     * game.stopAllSounds();
+     * ```
+     */
+    stopAllSounds() {
+        this._soundSystem.stopAll();
+    }
     /**
      * Plays a square-wave beep using the Web Audio API.
      *
-     * **Square wave only.** MinimoJS does not support audio files, samples,
-     * or other waveforms. Only procedural square-wave tones.
+     * **Square wave only.** This synthesizes a tone and needs no file. To play
+     * a recorded sound, load it with {@link Game.loadSound} and play it with
+     * {@link Game.playSound}.
      *
      * The AudioContext is created lazily on first call. Browsers require a user
      * gesture (click, keypress) before audio can play — always call `sound()` in
@@ -2982,7 +3069,7 @@ export class Game {
             return;
         }
         this._registerSceneAssets(scene ?? this._currentScene);
-        if (this._assetSystem.getQueuedImageCount() === 0) {
+        if (this._assetSystem.getQueuedAssetCount() === 0) {
             this._resetNow(scene);
             return;
         }
@@ -3045,7 +3132,7 @@ export class Game {
             return;
         }
         this._registerSceneAssets(scene);
-        if (this._assetSystem.getQueuedImageCount() === 0) {
+        if (this._assetSystem.getQueuedAssetCount() === 0) {
             this._transitionNow(scene, options, onComplete);
             return;
         }
@@ -3149,14 +3236,14 @@ export class Game {
                 registeredScene = this._currentScene;
                 this._registerSceneAssets(registeredScene);
             }
-            const failed = await this._assetSystem.loadQueuedImages((settled, total) => {
+            const failed = await this._assetSystem.loadQueuedAssets((settled, total) => {
                 if (total > 0)
                     this._renderLoadingScreen(settled / total);
             });
             if (failed.length > 0) {
-                this._reportFailedImages(failed);
-                if (!this._confirmImageRetry(failed.length)) {
-                    this._assetSystem.discardQueuedImages();
+                this._reportFailedAssets(failed);
+                if (!this._confirmAssetRetry(failed.length)) {
+                    this._assetSystem.discardQueuedAssets();
                     return false;
                 }
                 continue;
@@ -3291,14 +3378,14 @@ export class Game {
     /** @internal */
     async _loadSceneImages(load, finish) {
         for (;;) {
-            const failed = await this._assetSystem.loadQueuedImages((settled, total) => {
+            const failed = await this._assetSystem.loadQueuedAssets((settled, total) => {
                 load.progress = total === 0 ? 1 : settled / total;
             });
             if (failed.length === 0)
                 break;
-            this._reportFailedImages(failed);
-            if (!this._confirmImageRetry(failed.length)) {
-                this._assetSystem.discardQueuedImages();
+            this._reportFailedAssets(failed);
+            if (!this._confirmAssetRetry(failed.length)) {
+                this._assetSystem.discardQueuedAssets();
                 this._sceneLoad = null;
                 return;
             }
@@ -3308,23 +3395,23 @@ export class Game {
         finish();
     }
     /** @internal */
-    _reportFailedImages(keys) {
+    _reportFailedAssets(keys) {
         const list = keys
-            .map((key) => `"${key}" (${this._assetSystem.getImageSource(key) ?? "no source"})`)
+            .map((key) => `"${key}" (${this._assetSystem.getAssetSource(key) ?? "no source"})`)
             .join(", ");
-        console.error(`MinimoJS: ${keys.length} image${keys.length === 1 ? "" : "s"} failed to load: ${list}.`);
+        console.error(`MinimoJS: ${keys.length} file${keys.length === 1 ? "" : "s"} failed to load: ${list}.`);
     }
     /**
-     * Asks the player whether to retry failed images, with the browser's own
+     * Asks the player whether to retry failed images and sounds, with the browser's own
      * confirmation dialog. Returns `false` where no dialog can be shown.
      *
      * @internal
      */
-    _confirmImageRetry(failedCount) {
+    _confirmAssetRetry(failedCount) {
         if (typeof window === "undefined" || typeof window.confirm !== "function") {
             return false;
         }
-        const noun = failedCount === 1 ? "image" : "images";
+        const noun = failedCount === 1 ? "file" : "files";
         try {
             return window.confirm(`${failedCount} ${noun} could not be loaded. Try again?`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.30",
+  "version": "1.0.0-alpha.31",
   "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Image-first sprites with emoji as a zero-asset alternative, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",