minimojs 1.0.0-alpha.42 → 1.0.0-alpha.43

package/dist/internal/AssetSystem.d.ts

@@ -4,3 +4,5 @@
  * audio API of its own and runs in tests without a browser.
  */
 export type SoundLoader = (src: string) => Promise<unknown>;
+/** Fetches and parses one JSON file, such as an atlas's. */
+export type DataLoader = (src: string) => Promise<unknown>;

package/dist/internal/AssetSystem.js

@@ -1,3 +1,11 @@
+import { checkFramesFitImage, frameKey, parseTextureAtlas, spritesheetFrames, } from "../minimo-format.js";
+async function fetchJson(src) {
+    const response = await fetch(src);
+    if (!response.ok) {
+        throw new Error(`MinimoJS: Failed to load "${src}" (${response.status}).`);
+    }
+    return response.json();
+}
 /**
  * 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
@@ -6,8 +14,9 @@
  * @internal
  */
 export class AssetSystem {
-    constructor(_soundLoader = null) {
+    constructor(_soundLoader = null, _dataLoader = fetchJson) {
         this._soundLoader = _soundLoader;
+        this._dataLoader = _dataLoader;
         /** @internal */
         this._queuedImages = new Map();
         /** @internal */
@@ -32,6 +41,16 @@ export class AssetSystem {
         this._loadedSounds = new Map();
         /** @internal */
         this._soundSources = new Map();
+        /** Spritesheets and atlases, by key. @internal */
+        this._sheets = new Map();
+        /** Each atlas's JSON source, by the atlas's key. @internal */
+        this._atlasSources = new Map();
+        /** @internal */
+        this._queuedAtlases = new Map();
+        /** @internal */
+        this._loadedAtlases = new Map();
+        /** The sheet that made each frame key. @internal */
+        this._frameOwners = new Map();
     }
     queueImage(key, src) {
         const safeKey = key.trim();
@@ -73,6 +92,10 @@ export class AssetSystem {
     registerAssetFile(file, source) {
         for (const entry of file.assets) {
             const owner = this._assetFileByKey.get(entry.key);
+            const sheet = this._frameOwners.get(entry.key);
+            if (sheet !== undefined) {
+                throw new Error(`MinimoJS: Asset key "${entry.key}" is a frame of "${sheet}". Keys must be unique in the whole game.`);
+            }
             if (owner === undefined) {
                 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.`);
@@ -93,6 +116,25 @@ export class AssetSystem {
             else if (entry.type === "sound") {
                 this.enqueueSound(entry.key, entry.src.trim());
             }
+            else if (entry.type === "spritesheet" || entry.type === "atlas") {
+                const { src, frameWidth, frameHeight, data } = entry;
+                if (!this._sheets.has(entry.key)) {
+                    this._sheets.set(entry.key, {
+                        type: entry.type,
+                        frameWidth: frameWidth ?? 0,
+                        frameHeight: frameHeight ?? 0,
+                        built: false,
+                    });
+                }
+                this.enqueueImage(entry.key, src.trim());
+                if (data !== undefined) {
+                    const safeData = data.trim();
+                    this._atlasSources.set(entry.key, safeData);
+                    if (!this._loadedAtlases.has(entry.key)) {
+                        this._queuedAtlases.set(entry.key, safeData);
+                    }
+                }
+            }
         }
         const isFirstRegistration = !this._registeredAssetFiles.has(source);
         this._registeredAssetFiles.add(source);
@@ -159,9 +201,13 @@ export class AssetSystem {
     hasSound(key) {
         return this._loadedSounds.has(key);
     }
-    /** Counts the queued images and sounds that are not loaded yet. */
+    /** The key of the spritesheet or atlas whose frame `key` is, if it is one. */
+    getFrameOwner(key) {
+        return this._frameOwners.get(key);
+    }
+    /** Counts the queued images, sounds, and atlas files that are not loaded yet. */
     getQueuedAssetCount() {
-        let total = 0;
+        let total = this._queuedAtlases.size;
         for (const key of this._queuedImages.keys()) {
             if (!this._loadedImages.has(key)) {
                 total++;
@@ -184,13 +230,15 @@ export class AssetSystem {
     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;
+        const atlases = [...this._queuedAtlases.entries()];
+        const total = images.length + sounds.length + atlases.length;
         let settled = 0;
         const failed = [];
         onProgress?.(0, total, null);
         if (total === 0) {
             this._queuedImages.clear();
             this._queuedSounds.clear();
+            this.buildSheets(failed);
             return failed;
         }
         const settle = (key) => {
@@ -223,13 +271,94 @@ export class AssetSystem {
                 }
                 settle(key);
             }),
+            ...atlases.map(async ([key, src]) => {
+                try {
+                    this._loadedAtlases.set(key, parseTextureAtlas(await this._dataLoader(src)));
+                    this._queuedAtlases.delete(key);
+                }
+                catch (error) {
+                    console.error(`MinimoJS: The atlas "${key}" could not be read from "${src}".`, error);
+                    failed.push(key);
+                }
+                settle(key);
+            }),
         ]);
         for (const key of [...this._queuedImages.keys()]) {
             if (this._loadedImages.has(key)) {
                 this._queuedImages.delete(key);
             }
         }
-        return failed;
+        this.buildSheets(failed);
+        // An atlas whose image and JSON both failed is one failure, under its key.
+        return [...new Set(failed)];
+    }
+    /**
+     * Makes the frames of every spritesheet and atlas whose image, and atlas
+     * file, are loaded and whose frames are not made yet. A sheet whose frames
+     * cannot be made is added to `failed` once, with the reason on the console.
+     *
+     * @internal
+     */
+    buildSheets(failed) {
+        for (const [key, sheet] of this._sheets) {
+            if (sheet.built)
+                continue;
+            const image = this._loadedImages.get(key);
+            const atlas = this._loadedAtlases.get(key);
+            if (!image || (sheet.type === "atlas" && !atlas))
+                continue;
+            try {
+                const width = imageWidth(image);
+                const height = imageHeight(image);
+                const frames = sheet.type === "atlas"
+                    ? atlas.frames
+                    : spritesheetFrames({ key, frameWidth: sheet.frameWidth, frameHeight: sheet.frameHeight }, width, height);
+                checkFramesFitImage(key, frames, width, height);
+                for (const frame of frames) {
+                    const name = frameKey(key, frame.name);
+                    if (this.isKeyTaken(name)) {
+                        throw new Error(`MinimoJS: The frame "${frame.name}" of "${key}" would be the key "${name}", which is already in use. Keys must be unique in the whole game.`);
+                    }
+                }
+                for (const frame of frames) {
+                    const name = frameKey(key, frame.name);
+                    this._loadedImages.set(name, this.cutFrame(image, frame));
+                    this._frameOwners.set(name, key);
+                    this.bumpImageVersion(name);
+                }
+                sheet.built = true;
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : error);
+                if (!failed.includes(key))
+                    failed.push(key);
+            }
+        }
+    }
+    /** @internal */
+    isKeyTaken(key) {
+        return (this._loadedImages.has(key) ||
+            this._imageSources.has(key) ||
+            this._soundSources.has(key) ||
+            this._assetFileByKey.has(key) ||
+            this._frameOwners.has(key));
+    }
+    /**
+     * Copies one frame into a texture of its untrimmed size, at the place the
+     * trimmed rectangle had in it.
+     *
+     * @internal
+     */
+    cutFrame(image, frame) {
+        const canvas = document.createElement("canvas");
+        canvas.width = frame.sourceWidth;
+        canvas.height = frame.sourceHeight;
+        const ctx = canvas.getContext("2d");
+        if (!ctx) {
+            throw new Error("MinimoJS: Could not acquire a texture rendering context.");
+        }
+        ctx.drawImage(image, frame.x, frame.y, frame.width, frame.height, frame.offsetX, frame.offsetY, frame.width, frame.height);
+        return canvas;
     }
     /** Returns the source registered for an image or sound key, if any. */
     getAssetSource(key) {
@@ -242,6 +371,7 @@ export class AssetSystem {
     discardQueuedAssets() {
         this._queuedImages.clear();
         this._queuedSounds.clear();
+        this._queuedAtlases.clear();
     }
     /** @internal */
     refuseSoundKey(safeKey, caller) {
@@ -251,6 +381,10 @@ export class AssetSystem {
     }
     /** @internal */
     refuseAssetFileKey(safeKey, caller) {
+        const sheet = this._frameOwners.get(safeKey);
+        if (sheet !== undefined) {
+            throw new Error(`MinimoJS: ${caller} cannot use the key "${safeKey}", which is a frame of "${sheet}". Keys must be unique in the whole game.`);
+        }
         if (this._assetFileByKey.has(safeKey)) {
             throw new Error(`MinimoJS: ${caller} cannot use the key "${safeKey}", which an asset file declares. Keys must be unique in the whole game.`);
         }
@@ -279,3 +413,9 @@ export class AssetSystem {
         this._imageVersions.set(key, (this._imageVersions.get(key) ?? 0) + 1);
     }
 }
+function imageWidth(image) {
+    return image.naturalWidth || image.width;
+}
+function imageHeight(image) {
+    return image.naturalHeight || image.height;
+}

package/dist/minimo-format.d.ts

@@ -51,6 +51,97 @@ export interface SoundAsset {
     /** The audio file's URL or path, as `game.loadSound(key, src)` takes it. Non-empty. */
     src: string;
 }
+/**
+ * A spritesheet declared in an asset file: one image cut into a grid of equal
+ * frames. The image loads under `key`, as an `image` entry's does, and each
+ * frame becomes an image of its own, keyed `<key>/<n>`, numbered from `0`
+ * left to right and top to bottom, such as `"frog/0"` and `"frog/1"`. A frame
+ * key works wherever an image key does: `ImageSprite`, backgrounds, designs,
+ * and `game.getImage`.
+ *
+ * The grid starts at the image's top-left corner, with no margin or spacing;
+ * pixels left over at the right or bottom edge belong to no frame.
+ *
+ * @example
+ * ```json
+ * { "key": "frog", "type": "spritesheet", "src": "assets/frog-frames.png", "frameWidth": 320, "frameHeight": 320 }
+ * ```
+ */
+export interface SpritesheetAsset {
+    /** The key of the whole image, and the prefix of its frames' keys. Unique in the whole game. */
+    key: string;
+    /** Always `"spritesheet"`. */
+    type: "spritesheet";
+    /** The image's URL or path, as `game.loadImage(key, src)` takes it. Non-empty. */
+    src: string;
+    /** Width of every frame in pixels. A positive integer. */
+    frameWidth: number;
+    /** Height of every frame in pixels. A positive integer. */
+    frameHeight: number;
+}
+/**
+ * A texture atlas declared in an asset file: one image holding named frames
+ * of any size, described by a JSON file in the JSON Hash format that
+ * TexturePacker (*JSON (Hash)*) and free-tex-packer (`JsonHash`) export; see
+ * {@link parseTextureAtlas} for what is read from it. The image loads under
+ * `key`, and each frame becomes an image of its own, keyed `<key>/<frame>`
+ * with the frame's name as the packer wrote it, such as `"pond/lotus"`.
+ *
+ * The image is the one `src` names; the JSON's own `meta.image`, the file
+ * name the packer gave the image, is ignored, so the image may be stored
+ * under any name.
+ *
+ * @example
+ * ```json
+ * { "key": "pond", "type": "atlas", "src": "assets/pond.png", "data": "assets/pond.json" }
+ * ```
+ */
+export interface AtlasAsset {
+    /** The key of the whole image, and the prefix of its frames' keys. Unique in the whole game. */
+    key: string;
+    /** Always `"atlas"`. */
+    type: "atlas";
+    /** The image's URL or path, as `game.loadImage(key, src)` takes it. Non-empty. */
+    src: string;
+    /** The URL or path of the atlas JSON, in the JSON Hash format. Non-empty. */
+    data: string;
+}
+/**
+ * One frame of a spritesheet or an atlas: where it is in the image, and the
+ * size of the picture it came from. A frame trimmed of its transparent border
+ * is drawn at `offsetX`, `offsetY` inside a texture of `sourceWidth` by
+ * `sourceHeight`, so a sprite of it is the size of the untrimmed picture and
+ * trimming never moves what it shows.
+ */
+export interface TextureFrame {
+    /** The frame's name, which follows the sheet's key in its image key: `<key>/<name>`. */
+    name: string;
+    /** Left edge of the frame in the image, in pixels. */
+    x: number;
+    /** Top edge of the frame in the image, in pixels. */
+    y: number;
+    /** Width of the frame in the image, in pixels. */
+    width: number;
+    /** Height of the frame in the image, in pixels. */
+    height: number;
+    /** Width of the picture before trimming, the texture's width. */
+    sourceWidth: number;
+    /** Height of the picture before trimming, the texture's height. */
+    sourceHeight: number;
+    /** Where the frame's left edge sits in the untrimmed picture. */
+    offsetX: number;
+    /** Where the frame's top edge sits in the untrimmed picture. */
+    offsetY: number;
+}
+/** A texture atlas, as {@link parseTextureAtlas} reads it from its JSON. */
+export interface TextureAtlas {
+    /** The atlas's frames, in the JSON's order. */
+    frames: TextureFrame[];
+    /** The image size the JSON's `meta.size` states, or `null` when it states none. */
+    imageWidth: number | null;
+    /** The image size the JSON's `meta.size` states, or `null` when it states none. */
+    imageHeight: number | null;
+}
 /**
  * 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
@@ -80,7 +171,9 @@ export interface UnknownAsset {
  *   "assets": [
  *     { "key": "player", "type": "image", "src": "assets/player.png" },
  *     { "key": "bat", "type": "image", "src": "assets/bat.png" },
- *     { "key": "jump", "type": "sound", "src": "assets/jump.mp3" }
+ *     { "key": "jump", "type": "sound", "src": "assets/jump.mp3" },
+ *     { "key": "frog", "type": "spritesheet", "src": "assets/frog.png", "frameWidth": 64, "frameHeight": 64 },
+ *     { "key": "pond", "type": "atlas", "src": "assets/pond.png", "data": "assets/pond.json" }
  *   ]
  * }
  * ```
@@ -91,8 +184,12 @@ 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 | SoundAsset | UnknownAsset)[];
+    assets: AssetEntry[];
 }
+/** One entry of an asset file. */
+export type AssetEntry = ImageAsset | SoundAsset | SpritesheetAsset | AtlasAsset | UnknownAsset;
+/** The entry types this engine loads. */
+export declare const ASSET_TYPES: readonly string[];
 /**
  * Validates the content of an asset file and returns a copy of it.
  *
@@ -103,7 +200,9 @@ 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` or `sound` entry without a non-empty string `src`.
+ * - an `image`, `sound`, `spritesheet`, or `atlas` entry without a non-empty string `src`;
+ * - a `spritesheet` whose `frameWidth` or `frameHeight` is not a positive integer;
+ * - an `atlas` without a non-empty string `data`.
  *
  * 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.
@@ -117,6 +216,48 @@ export interface AssetFile {
  * ```
  */
 export declare function parseAssetFile(json: unknown): AssetFile;
+/**
+ * The image key of a spritesheet's or an atlas's frame: the sheet's key, a
+ * slash, and the frame's name, such as `"frog/0"` or `"pond/lotus"`.
+ */
+export declare function frameKey(sheetKey: string, frameName: string): string;
+/**
+ * The frames of a spritesheet whose image is `imageWidth` by `imageHeight`
+ * pixels: every whole cell of the grid, numbered from `0` left to right and
+ * top to bottom. Throws when the image holds no whole frame.
+ */
+export declare function spritesheetFrames(sheet: Pick<SpritesheetAsset, "key" | "frameWidth" | "frameHeight">, imageWidth: number, imageHeight: number): TextureFrame[];
+/**
+ * Reads a texture atlas in the JSON Hash format, as TexturePacker
+ * (*JSON (Hash)*) and free-tex-packer (`JsonHash`) export it, and returns its
+ * frames.
+ *
+ * From each entry of `frames` it reads `frame`, the rectangle in the image;
+ * `sourceSize`, the picture's size before trimming; and `spriteSourceSize`,
+ * where the trimmed rectangle sat in it. The last two may be left out for an
+ * untrimmed frame. Other fields, such as `pivot`, `anchor`, `trimmed`, and
+ * the rest of `meta`, are ignored.
+ *
+ * It throws an error naming what is wrong, and which packer setting changes
+ * it, for:
+ * - a value that is not an object with a `frames` object, including the JSON
+ *   Array format, whose `frames` is a list, and multi-image atlases, which
+ *   list `textures`;
+ * - no frames, or a frame name that is empty or has leading or trailing spaces;
+ * - a rotated frame, `"rotated": true`;
+ * - a `meta.scale` other than 1;
+ * - a rectangle that is not made of whole, non-negative pixels, or a trimmed
+ *   rectangle that does not fit in its source size;
+ * - a frame outside the image size `meta.size` states.
+ *
+ * @param json - The parsed atlas JSON.
+ */
+export declare function parseTextureAtlas(json: unknown): TextureAtlas;
+/**
+ * Throws unless every frame lies inside an image of `imageWidth` by
+ * `imageHeight` pixels. `sheet` names the sheet in the error.
+ */
+export declare function checkFramesFitImage(sheet: string, frames: readonly TextureFrame[], imageWidth: number, imageHeight: number): void;
 /**
  * The type of a design object. Each built-in type maps to one runtime class:
  * `image` to `ImageSprite`, `emoji` to `EmojiSprite`, `text` to `TextSprite`,

package/dist/minimo-format.js

@@ -12,9 +12,13 @@
 const ASSET_FILE_FORMAT = "minimo-assets";
 /** The newest asset file `version` this engine reads. */
 const ASSET_FILE_VERSION = 1;
+/** The entry types this engine loads. */
+export const ASSET_TYPES = Object.freeze(["image", "sound", "spritesheet", "atlas"]);
 const ASSET_FILE_FIELDS = new Set(["format", "version", "assets"]);
 /** The fields of each supported entry type; `image` and `sound` share theirs. */
 const SRC_ASSET_FIELDS = new Set(["key", "type", "src"]);
+const SPRITESHEET_ASSET_FIELDS = new Set(["key", "type", "src", "frameWidth", "frameHeight"]);
+const ATLAS_ASSET_FIELDS = new Set(["key", "type", "src", "data"]);
 /**
  * Validates the content of an asset file and returns a copy of it.
  *
@@ -25,7 +29,9 @@ const SRC_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` or `sound` entry without a non-empty string `src`.
+ * - an `image`, `sound`, `spritesheet`, or `atlas` entry without a non-empty string `src`;
+ * - a `spritesheet` whose `frameWidth` or `frameHeight` is not a positive integer;
+ * - an `atlas` without a non-empty string `data`.
  *
  * 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.
@@ -82,13 +88,25 @@ export function parseAssetFile(json) {
         if (typeof type !== "string" || type.length === 0) {
             throw assetError(`${where} ("${key}") must have a string "type", found ${describe(type)}.`);
         }
+        const named = `${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)}.`);
+            rejectUnknownFields(entry, SRC_ASSET_FIELDS, named);
+            assets.push({ key, type, src: requireText(entry, "src", named) });
+        }
+        else if (type === "spritesheet") {
+            rejectUnknownFields(entry, SPRITESHEET_ASSET_FIELDS, named);
+            const src = requireText(entry, "src", named);
+            for (const field of ["frameWidth", "frameHeight"]) {
+                const value = entry[field];
+                if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+                    throw assetError(`${named} must have a positive integer "${field}", found ${describe(value)}.`);
+                }
             }
-            assets.push({ key, type, src });
+            assets.push({ key, type, src, frameWidth: entry.frameWidth, frameHeight: entry.frameHeight });
+        }
+        else if (type === "atlas") {
+            rejectUnknownFields(entry, ATLAS_ASSET_FIELDS, named);
+            assets.push({ key, type, src: requireText(entry, "src", named), data: requireText(entry, "data", named) });
         }
         else {
             assets.push({ ...entry, key, type });
@@ -97,6 +115,164 @@ export function parseAssetFile(json) {
     return { format: ASSET_FILE_FORMAT, version: ASSET_FILE_VERSION, assets };
 }
 // ---------------------------------------------------------------------------
+// Spritesheets and texture atlases
+// ---------------------------------------------------------------------------
+/**
+ * The image key of a spritesheet's or an atlas's frame: the sheet's key, a
+ * slash, and the frame's name, such as `"frog/0"` or `"pond/lotus"`.
+ */
+export function frameKey(sheetKey, frameName) {
+    return `${sheetKey}/${frameName}`;
+}
+/**
+ * The frames of a spritesheet whose image is `imageWidth` by `imageHeight`
+ * pixels: every whole cell of the grid, numbered from `0` left to right and
+ * top to bottom. Throws when the image holds no whole frame.
+ */
+export function spritesheetFrames(sheet, imageWidth, imageHeight) {
+    const columns = Math.floor(imageWidth / sheet.frameWidth);
+    const rows = Math.floor(imageHeight / sheet.frameHeight);
+    if (columns < 1 || rows < 1) {
+        throw new Error(`MinimoJS: The spritesheet "${sheet.key}" is ${imageWidth} by ${imageHeight} pixels, smaller than one ${sheet.frameWidth} by ${sheet.frameHeight} frame.`);
+    }
+    const frames = [];
+    for (let row = 0; row < rows; row++) {
+        for (let column = 0; column < columns; column++) {
+            frames.push({
+                name: String(frames.length),
+                x: column * sheet.frameWidth,
+                y: row * sheet.frameHeight,
+                width: sheet.frameWidth,
+                height: sheet.frameHeight,
+                sourceWidth: sheet.frameWidth,
+                sourceHeight: sheet.frameHeight,
+                offsetX: 0,
+                offsetY: 0,
+            });
+        }
+    }
+    return frames;
+}
+/**
+ * Reads a texture atlas in the JSON Hash format, as TexturePacker
+ * (*JSON (Hash)*) and free-tex-packer (`JsonHash`) export it, and returns its
+ * frames.
+ *
+ * From each entry of `frames` it reads `frame`, the rectangle in the image;
+ * `sourceSize`, the picture's size before trimming; and `spriteSourceSize`,
+ * where the trimmed rectangle sat in it. The last two may be left out for an
+ * untrimmed frame. Other fields, such as `pivot`, `anchor`, `trimmed`, and
+ * the rest of `meta`, are ignored.
+ *
+ * It throws an error naming what is wrong, and which packer setting changes
+ * it, for:
+ * - a value that is not an object with a `frames` object, including the JSON
+ *   Array format, whose `frames` is a list, and multi-image atlases, which
+ *   list `textures`;
+ * - no frames, or a frame name that is empty or has leading or trailing spaces;
+ * - a rotated frame, `"rotated": true`;
+ * - a `meta.scale` other than 1;
+ * - a rectangle that is not made of whole, non-negative pixels, or a trimmed
+ *   rectangle that does not fit in its source size;
+ * - a frame outside the image size `meta.size` states.
+ *
+ * @param json - The parsed atlas JSON.
+ */
+export function parseTextureAtlas(json) {
+    if (!isPlainObject(json)) {
+        throw atlasError("an atlas must be a JSON object.");
+    }
+    if (Array.isArray(json.textures)) {
+        throw atlasError(`it holds several images ("textures"). Export one image per atlas, in the JSON Hash format, with TexturePacker's Multipack off.`);
+    }
+    if (Array.isArray(json.frames)) {
+        throw atlasError(`"frames" is a list, the JSON Array format. Export the JSON Hash format: TexturePacker's "JSON (Hash)", free-tex-packer's "JSON (hash)".`);
+    }
+    if (!isPlainObject(json.frames)) {
+        throw atlasError(`"frames" must be an object of frames by name, found ${describe(json.frames)}.`);
+    }
+    const meta = isPlainObject(json.meta) ? json.meta : {};
+    if (meta.scale !== undefined && Number(meta.scale) !== 1) {
+        throw atlasError(`"meta.scale" is ${describe(meta.scale)}. Export the atlas at scale 1.`);
+    }
+    let imageWidth = null;
+    let imageHeight = null;
+    if (isPlainObject(meta.size)) {
+        imageWidth = requirePixels(meta.size.w, `"meta.size.w"`, 1);
+        imageHeight = requirePixels(meta.size.h, `"meta.size.h"`, 1);
+    }
+    const frames = [];
+    for (const [name, entry] of Object.entries(json.frames)) {
+        const where = `the frame "${name}"`;
+        if (name.length === 0 || name.trim() !== name) {
+            throw atlasError(`the frame name "${name}" is empty or has leading or trailing spaces.`);
+        }
+        if (!isPlainObject(entry)) {
+            throw atlasError(`${where} must be an object, found ${describe(entry)}.`);
+        }
+        if (entry.rotated === true) {
+            throw atlasError(`${where} is rotated. Export the atlas without rotation: TexturePacker's "Allow rotation", free-tex-packer's "allowRotation".`);
+        }
+        if (!isPlainObject(entry.frame)) {
+            throw atlasError(`${where} must have a "frame" rectangle, found ${describe(entry.frame)}.`);
+        }
+        const x = requirePixels(entry.frame.x, `${where}'s "frame.x"`, 0);
+        const y = requirePixels(entry.frame.y, `${where}'s "frame.y"`, 0);
+        const width = requirePixels(entry.frame.w, `${where}'s "frame.w"`, 1);
+        const height = requirePixels(entry.frame.h, `${where}'s "frame.h"`, 1);
+        let sourceWidth = width;
+        let sourceHeight = height;
+        if (entry.sourceSize !== undefined) {
+            if (!isPlainObject(entry.sourceSize)) {
+                throw atlasError(`${where}'s "sourceSize" must be an object, found ${describe(entry.sourceSize)}.`);
+            }
+            sourceWidth = requirePixels(entry.sourceSize.w, `${where}'s "sourceSize.w"`, 1);
+            sourceHeight = requirePixels(entry.sourceSize.h, `${where}'s "sourceSize.h"`, 1);
+        }
+        let offsetX = 0;
+        let offsetY = 0;
+        if (entry.spriteSourceSize !== undefined) {
+            if (!isPlainObject(entry.spriteSourceSize)) {
+                throw atlasError(`${where}'s "spriteSourceSize" must be an object, found ${describe(entry.spriteSourceSize)}.`);
+            }
+            offsetX = requirePixels(entry.spriteSourceSize.x, `${where}'s "spriteSourceSize.x"`, 0);
+            offsetY = requirePixels(entry.spriteSourceSize.y, `${where}'s "spriteSourceSize.y"`, 0);
+        }
+        if (offsetX + width > sourceWidth || offsetY + height > sourceHeight) {
+            throw atlasError(`${where}, ${width} by ${height} pixels at ${offsetX}, ${offsetY}, does not fit in its ${sourceWidth} by ${sourceHeight} "sourceSize".`);
+        }
+        if (imageWidth !== null && imageHeight !== null && (x + width > imageWidth || y + height > imageHeight)) {
+            throw atlasError(`${where} reaches outside the ${imageWidth} by ${imageHeight} image "meta.size" states.`);
+        }
+        frames.push({ name, x, y, width, height, sourceWidth, sourceHeight, offsetX, offsetY });
+    }
+    if (frames.length === 0) {
+        throw atlasError(`it has no frames.`);
+    }
+    return { frames, imageWidth, imageHeight };
+}
+/**
+ * Throws unless every frame lies inside an image of `imageWidth` by
+ * `imageHeight` pixels. `sheet` names the sheet in the error.
+ */
+export function checkFramesFitImage(sheet, frames, imageWidth, imageHeight) {
+    for (const frame of frames) {
+        if (frame.x + frame.width > imageWidth || frame.y + frame.height > imageHeight) {
+            throw new Error(`MinimoJS: The frame "${frame.name}" of "${sheet}" reaches outside its ${imageWidth} by ${imageHeight} image. Check that the atlas JSON was packed for this image.`);
+        }
+    }
+}
+function requirePixels(value, where, minimum) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < minimum) {
+        const expected = minimum === 0 ? "a whole number of pixels, 0 or more" : "a whole number of pixels, 1 or more";
+        throw atlasError(`${where} must be ${expected}, found ${describe(value)}.`);
+    }
+    return value;
+}
+function atlasError(message) {
+    return new Error(`MinimoJS: Invalid atlas: ${message}`);
+}
+// ---------------------------------------------------------------------------
 // Design files
 // ---------------------------------------------------------------------------
 /** The `format` value of every design file. */
@@ -711,6 +887,13 @@ export class Design {
         return this.objects.filter((object) => object.tags?.includes(tag) === true);
     }
 }
+function requireText(entry, field, where) {
+    const value = entry[field];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw assetError(`${where} must have a non-empty string "${field}", found ${describe(value)}.`);
+    }
+    return value;
+}
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/minimo-leaderboard.d.ts

@@ -116,9 +116,9 @@ export interface LeaderboardShowOptions {
  * On Minimo Games, the creator sets up a game's leaderboards, up to 5, on the
  * game's Edit leaderboards page, or an AI agent with the `saveGameLeaderboard`
  * tool; the game names one by its key. Their settings come from there, and a
- * key that no leaderboard of the game has is unavailable. Leaderboards are part
- * of Minimo Games Pro: while the creator is not on it, the game shows its
- * tables but saves no new records.
+ * key that no leaderboard of the game has is unavailable. Leaderboards save
+ * new records only while the creator's plan includes them: otherwise the game
+ * shows its tables but saves no new records.
  *
  * Scores of a leaderboard that takes Minimo Games accounts go to one table
  * that every player sees. Minimo Games posts them for the signed-in player, and

package/dist/minimo-leaderboard.js

@@ -265,9 +265,9 @@ export function renderLeaderboardHtml(table, view) {
  * On Minimo Games, the creator sets up a game's leaderboards, up to 5, on the
  * game's Edit leaderboards page, or an AI agent with the `saveGameLeaderboard`
  * tool; the game names one by its key. Their settings come from there, and a
- * key that no leaderboard of the game has is unavailable. Leaderboards are part
- * of Minimo Games Pro: while the creator is not on it, the game shows its
- * tables but saves no new records.
+ * key that no leaderboard of the game has is unavailable. Leaderboards save
+ * new records only while the creator's plan includes them: otherwise the game
+ * shows its tables but saves no new records.
  *
  * Scores of a leaderboard that takes Minimo Games accounts go to one table
  * that every player sees. Minimo Games posts them for the signed-in player, and

package/dist/minimo-multiplayer.d.ts

@@ -122,7 +122,7 @@ export interface RoomResultsOptions {
 }
 /**
  * What a room promise is refused with. `reason` is one of:
- * `unavailable` (not on Minimo Games, or the game's creator is not on Pro),
+ * `unavailable` (not on Minimo Games, or the creator's plan lacks multiplayer),
  * `cancelled` (the player closed the lobby), `room_not_found`, `full`,
  * `in_progress`, `removed`, `not_your_turn`, `stale` (another change came
  * first; read the room again and retry), `not_host`, `wrong_phase`,
@@ -288,8 +288,8 @@ export declare class Room {
  * frame: it suits card games, board games, word games, and races against the
  * clock, not action games.
  *
- * It works only inside Minimo Games, and only while the game's creator is on
- * Minimo Games Pro. Players need no account: a guest types a name once.
+ * It works only inside Minimo Games, and only while the game's creator's plan
+ * includes it. Players need no account: a guest types a name once.
  *
  * {@link Multiplayer.lobby} shows the lobby over the game, in HTML: creating a
  * room, joining one by its code, sharing its link, and waiting for the others
@@ -341,8 +341,8 @@ export declare class Multiplayer {
     /** The room the player is in, or `null`. */
     get room(): Room | null;
     /**
-     * Whether multiplayer can be played here: inside Minimo Games, with the
-     * game's creator on Pro.
+     * Whether multiplayer can be played here: inside Minimo Games, on a game
+     * whose creator's plan includes it.
      */
     available(): Promise<boolean>;
     /** Creates a room, without the lobby. The player is its host. */
@@ -353,7 +353,7 @@ export declare class Multiplayer {
      * The room this player is expected in, before any screen is shown: the room
      * whose link they opened, an invitation, or the room they were in on this
      * device before the page reloaded. `null` on a normal visit, outside
-     * Minimo Games, and when the game's creator is not on Pro.
+     * Minimo Games, and when the game's creator's plan lacks multiplayer.
      *
      * It opens nothing, joins nothing, and can be asked again: the room stays
      * pending until the player is in it. {@link Multiplayer.lobby} then takes
@@ -375,8 +375,8 @@ export declare class Multiplayer {
      * game from a room's link goes straight into that room, and one who reloads
      * the page returns to theirs.
      *
-     * Refused with `unavailable` outside Minimo Games or when the game's creator
-     * is not on Pro, after the lobby says so, and with `cancelled` when the
+     * Refused with `unavailable` outside Minimo Games or when the game's creator's
+     * plan lacks multiplayer, after the lobby says so, and with `cancelled` when the
      * player closes it.
      */
     lobby(): Promise<Room>;

package/dist/minimo-multiplayer.js

@@ -1,6 +1,6 @@
 /**
  * What a room promise is refused with. `reason` is one of:
- * `unavailable` (not on Minimo Games, or the game's creator is not on Pro),
+ * `unavailable` (not on Minimo Games, or the creator's plan lacks multiplayer),
  * `cancelled` (the player closed the lobby), `room_not_found`, `full`,
  * `in_progress`, `removed`, `not_your_turn`, `stale` (another change came
  * first; read the room again and retry), `not_host`, `wrong_phase`,
@@ -752,8 +752,8 @@ export class Room {
  * frame: it suits card games, board games, word games, and races against the
  * clock, not action games.
  *
- * It works only inside Minimo Games, and only while the game's creator is on
- * Minimo Games Pro. Players need no account: a guest types a name once.
+ * It works only inside Minimo Games, and only while the game's creator's plan
+ * includes it. Players need no account: a guest types a name once.
  *
  * {@link Multiplayer.lobby} shows the lobby over the game, in HTML: creating a
  * room, joining one by its code, sharing its link, and waiting for the others
@@ -817,8 +817,8 @@ export class Multiplayer {
         return this._room;
     }
     /**
-     * Whether multiplayer can be played here: inside Minimo Games, with the
-     * game's creator on Pro.
+     * Whether multiplayer can be played here: inside Minimo Games, on a game
+     * whose creator's plan includes it.
      */
     async available() {
         const info = await connectHost();
@@ -859,7 +859,7 @@ export class Multiplayer {
         const info = await request("hello", {}, HOST_TIMEOUT_MS * 2);
         this._info = info;
         if (!info.available) {
-            throw new MultiplayerError(info.preview ? "Multiplayer is part of Minimo Games Pro: this preview opens rooms once the game's creator is on Pro" : "Multiplayer is not available for this game", "unavailable");
+            throw new MultiplayerError(info.preview ? "Multiplayer is not on this account's plan: this preview opens rooms once it is" : "Multiplayer is not available for this game", "unavailable");
         }
         if (!this._listening) {
             this._listening = true;
@@ -924,7 +924,7 @@ export class Multiplayer {
      * The room this player is expected in, before any screen is shown: the room
      * whose link they opened, an invitation, or the room they were in on this
      * device before the page reloaded. `null` on a normal visit, outside
-     * Minimo Games, and when the game's creator is not on Pro.
+     * Minimo Games, and when the game's creator's plan lacks multiplayer.
      *
      * It opens nothing, joins nothing, and can be asked again: the room stays
      * pending until the player is in it. {@link Multiplayer.lobby} then takes
@@ -976,8 +976,8 @@ export class Multiplayer {
      * game from a room's link goes straight into that room, and one who reloads
      * the page returns to theirs.
      *
-     * Refused with `unavailable` outside Minimo Games or when the game's creator
-     * is not on Pro, after the lobby says so, and with `cancelled` when the
+     * Refused with `unavailable` outside Minimo Games or when the game's creator's
+     * plan lacks multiplayer, after the lobby says so, and with `cancelled` when the
      * player closes it.
      */
     async lobby() {

package/dist/minimo.d.ts

@@ -10,10 +10,10 @@
 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 { Design, parseAssetFile, parseTextureAtlas, frameKey } from "./minimo-format.js";
 export { SoundPlayback } from "./internal/SoundSystem.js";
 export type { PlaySoundOptions, SoundPlaybackState } from "./internal/SoundSystem.js";
-export type { AssetFile, DesignBackground, DesignEmoji, DesignFile, DesignFileV1, DesignFileV2, DesignFileV3, DesignImage, DesignModule, DesignObject, DesignObjectBase, DesignObjectType, DesignOutline, DesignPage, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, UnknownAsset, } from "./minimo-format.js";
+export type { AssetEntry, AssetFile, AtlasAsset, DesignBackground, DesignEmoji, DesignFile, DesignFileV1, DesignFileV2, DesignFileV3, DesignImage, DesignModule, DesignObject, DesignObjectBase, DesignObjectType, DesignOutline, DesignPage, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, SpritesheetAsset, TextureAtlas, TextureFrame, UnknownAsset, } from "./minimo-format.js";
 /**
  * Optional tuning values for {@link Game.animateExplode}.
  *
@@ -1596,6 +1596,17 @@ export declare class Game {
      * - 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.
      *
+     * A `spritesheet` or `atlas` entry loads its image under its key, and its
+     * atlas JSON with it, and once both are in makes each frame an image of its
+     * own, keyed `<key>/<frame>`, such as `"frog/0"` or `"pond/lotus"`. A frame
+     * key works wherever an image key does: {@link ImageSprite}, backgrounds,
+     * designs, and {@link Game.getImage}. A trimmed atlas frame is restored to
+     * its untrimmed size, so it measures and sits as the picture it came from.
+     * A frame key cannot be used by any other image, sound, or texture. A sheet
+     * whose frames cannot be made, such as an atlas that names a rectangle
+     * outside its image, fails with its key, as a missing image does, and the
+     * console says why. See {@link SpritesheetAsset} and {@link AtlasAsset}.
+     *
      * @param assets - The content of a `*.assets.json` file. See {@link AssetFile}.
      *
      * @example

package/dist/minimo.js

@@ -22,8 +22,8 @@ import { TextSystem } from "./internal/TextSystem.js";
 import { TrailSystem } from "./internal/TrailSystem.js";
 import { TransitionSystem } from "./internal/TransitionSystem.js";
 import { TimerSystem } from "./internal/TimerSystem.js";
-import { Design, designDecorations, designModules, enabledDecorations, findFirst, parseAssetFile, parseDesignObject, } from "./minimo-format.js";
-export { Design, parseAssetFile } from "./minimo-format.js";
+import { ASSET_TYPES, Design, designDecorations, designModules, enabledDecorations, findFirst, parseAssetFile, parseDesignObject, } from "./minimo-format.js";
+export { Design, parseAssetFile, parseTextureAtlas, frameKey } 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;
@@ -1777,6 +1777,17 @@ export class Game {
      * - 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.
      *
+     * A `spritesheet` or `atlas` entry loads its image under its key, and its
+     * atlas JSON with it, and once both are in makes each frame an image of its
+     * own, keyed `<key>/<frame>`, such as `"frog/0"` or `"pond/lotus"`. A frame
+     * key works wherever an image key does: {@link ImageSprite}, backgrounds,
+     * designs, and {@link Game.getImage}. A trimmed atlas frame is restored to
+     * its untrimmed size, so it measures and sits as the picture it came from.
+     * A frame key cannot be used by any other image, sound, or texture. A sheet
+     * whose frames cannot be made, such as an atlas that names a rectangle
+     * outside its image, fails with its key, as a missing image does, and the
+     * console says why. See {@link SpritesheetAsset} and {@link AtlasAsset}.
+     *
      * @param assets - The content of a `*.assets.json` file. See {@link AssetFile}.
      *
      * @example
@@ -1795,7 +1806,7 @@ export class Game {
         if (!isFirstLoad)
             return;
         for (const entry of file.assets) {
-            if (entry.type !== "image" && entry.type !== "sound") {
+            if (!ASSET_TYPES.includes(entry.type)) {
                 console.warn(`MinimoJS: Skipped the asset "${entry.key}", whose type "${entry.type}" this version of MinimoJS does not support.`);
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.42",
+  "version": "1.0.0-alpha.43",
   "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",