minimojs 1.0.0-alpha.32 → 1.0.0-alpha.34

package/dist/minimo-format.d.ts

@@ -304,9 +304,17 @@ export interface DesignBackground extends DesignObjectBase {
 /** Any object of a design file. Its `type` says which. */
 export type DesignObject = DesignImage | DesignEmoji | DesignText | DesignBackground;
 /**
- * The content of a design file, `*.design.json`: a flat list of objects that
- * a game creates with `game.createObject` and `game.createObjectList`, read
- * through {@link Design}.
+ * The content of a design file, `*.design.json`, which a game reads through
+ * {@link Design} and creates with `game.createObject` and
+ * `game.createObjectList`. A design without pages is a {@link DesignFileV1},
+ * one flat list of objects; a design divided into pages is a
+ * {@link DesignFileV2}. Both are current: a design is written as version 2
+ * only when it has pages, so a design without them also loads in an older
+ * MinimoJS.
+ */
+export type DesignFile = DesignFileV1 | DesignFileV2;
+/**
+ * A design file without pages: one flat list of objects.
  *
  * @example
  * ```json
@@ -320,14 +328,62 @@ export type DesignObject = DesignImage | DesignEmoji | DesignText | DesignBackgr
  * }
  * ```
  */
-export interface DesignFile {
+export interface DesignFileV1 {
     /** Always `"minimo-design"`. */
     format: "minimo-design";
-    /** The version of the file's shape. Version `1` is the only one so far. */
+    /** `1`: the design has no pages. */
     version: 1;
     /** The objects, in file order, which is the order they are created and drawn in. */
     objects: DesignObject[];
 }
+/**
+ * A design file divided into pages. Pages only organize a design, such as
+ * one page per template, or a menu on one page and its button templates on
+ * another; they do not change how an object is created. Read one page's
+ * objects with {@link Design.findAllByPage}.
+ *
+ * @example
+ * ```json
+ * {
+ *   "format": "minimo-design",
+ *   "version": 2,
+ *   "pages": [
+ *     { "id": "0b1d5e7a-3c2f-4d8e-9a61-7f4b2c8e1d05", "name": "Hero", "objects": [
+ *       { "id": "a93e51b4-6c0d-4f2a-8b17-3e5d9c2f0a61", "name": "hero", "type": "image", "imageKey": "hero" }
+ *     ] },
+ *     { "id": "7c4a2e9f-1b3d-4f6a-8c05-2e9d7b1f4a36", "name": "Enemies", "objects": [
+ *       { "id": "c07d9e3f-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "name": "bat", "tags": ["enemy"], "type": "image", "imageKey": "bat" }
+ *     ] }
+ *   ]
+ * }
+ * ```
+ */
+export interface DesignFileV2 {
+    /** Always `"minimo-design"`. */
+    format: "minimo-design";
+    /** `2`: the design is divided into pages. */
+    version: 2;
+    /** The pages, at least one, in file order. */
+    pages: DesignPage[];
+}
+/** One page of a {@link DesignFileV2}: a named group of the design's objects. */
+export interface DesignPage {
+    /**
+     * Required. A UUID unique among the file's pages. Tools use it to keep a
+     * page through a rename; code finds a page by its `name`.
+     */
+    id: string;
+    /**
+     * Required. Unique in the file, not empty, and with no leading or trailing
+     * spaces, such as `"Enemies"`. Code finds a page by it.
+     */
+    name: string;
+    /**
+     * The page's objects, in file order. An object's `id` is unique in the whole
+     * file, across pages.
+     */
+    objects: DesignObject[];
+}
 /**
  * How one property of a design object is written, for tools that read or edit
  * designs without the TypeScript types, such as a property panel. See
@@ -371,8 +427,8 @@ export interface DesignProperty {
  */
 export declare const designObjectProperties: Readonly<Record<DesignObjectType, readonly DesignProperty[]>>;
 /**
- * The data of a design file, `*.design.json`, validated: its objects and
- * searches on them. A `Design` needs no game and creates nothing; pass its
+ * The data of a design file, `*.design.json`, validated: its objects, its
+ * pages, and searches on them. A `Design` needs no game and creates nothing; pass its
  * objects, or the results of its searches, to `game.createObject` or
  * `game.createObjectList`. Data alone also serves markers, such as spawn
  * points, which code reads without creating anything.
@@ -393,12 +449,27 @@ export declare const designObjectProperties: Readonly<Record<DesignObjectType, r
  *   }
  * }
  * ```
+ *
+ * A design divided into pages, such as a screen on one page and templates on
+ * another, is created one page at a time:
+ *
+ * ```ts
+ * const ui = game.createObjectList(menu.findAllByPage("Menu"));
+ * const bat = game.createObject(menu.findByPage("Bat"));
+ * ```
  */
 export declare class Design {
     /**
-     * Every object of the design, as object data, in file order.
+     * Every object of the design, as object data, in file order: for a design
+     * with pages, every page's objects, page after page. Passing them to
+     * `game.createObjectList` creates every page at once.
      */
     readonly objects: readonly DesignObject[];
+    /**
+     * The design's pages, in file order, each with its objects as object data.
+     * Empty for a design without pages, a version 1 file.
+     */
+    readonly pages: readonly Readonly<DesignPage>[];
     /**
      * Validates a design file's content and keeps a copy of it.
      *
@@ -407,11 +478,26 @@ export declare class Design {
      * `"minimo-design"`, a `version` newer than this engine reads, an object
      * whose `type` is not one of the built-in types, an `id` that is not a UUID
      * or is used twice, a value of the wrong type, a missing required property,
-     * and a `data` that is not a JSON object.
+     * a `data` that is not a JSON object, and a page without a UUID `id` or with
+     * a missing, padded, or repeated `name`.
      *
      * @param json - The content of a `*.design.json` file. See {@link DesignFile}.
      */
     constructor(json: unknown);
+    /**
+     * Returns the first object of the page named `name`, in file order, such
+     * as a page holding one template. Throws an error naming the page when the
+     * design has no page with that name, or the page has no objects.
+     */
+    findByPage(name: string): DesignObject;
+    /**
+     * Returns every object of the page named `name`, in file order; an empty
+     * list for an empty page. Throws an error naming the page when the design
+     * has no page with that name, because a page name that matches nothing is
+     * almost always a typo.
+     */
+    findAllByPage(name: string): DesignObject[];
+    private pageNamed;
     /**
      * Returns the first object whose `name` is `name`, in file order.
      * Throws an error naming `name` when there is none.

package/dist/minimo-format.js

@@ -102,7 +102,7 @@ export function parseAssetFile(json) {
 /** The `format` value of every design file. */
 const DESIGN_FILE_FORMAT = "minimo-design";
 /** The newest design file `version` this engine reads. */
-const DESIGN_FILE_VERSION = 1;
+const DESIGN_FILE_VERSION = 2;
 function spec(type, defaultValue) {
     return { type, nullable: false, values: null, required: false, default: defaultValue };
 }
@@ -214,7 +214,11 @@ export const designObjectProperties = Object.freeze({
     text: describeProperties(TEXT_SPECS),
     background: describeProperties(BACKGROUND_SPECS),
 });
-const DESIGN_FILE_FIELDS = new Set(["format", "version", "objects"]);
+const DESIGN_FILE_FIELDS = {
+    1: new Set(["format", "version", "objects"]),
+    2: new Set(["format", "version", "pages"]),
+};
+const DESIGN_PAGE_FIELDS = new Set(["id", "name", "objects"]);
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const PROPERTIES_BY_TYPE = new Map(Object.entries(designObjectProperties).map(([type, properties]) => [
     type,
@@ -308,11 +312,6 @@ function parseDesignFile(json) {
     if (!isPlainObject(json)) {
         throw fail("a design must be a JSON object.");
     }
-    for (const field of Object.keys(json)) {
-        if (!DESIGN_FILE_FIELDS.has(field)) {
-            throw fail(`the design has an unknown field "${field}".`);
-        }
-    }
     if (json.format !== DESIGN_FILE_FORMAT) {
         throw fail(`"format" must be "${DESIGN_FILE_FORMAT}", found ${describe(json.format)}.`);
     }
@@ -323,24 +322,75 @@ function parseDesignFile(json) {
     if (version > DESIGN_FILE_VERSION) {
         throw fail(`"version" ${version} is newer than this engine reads (${DESIGN_FILE_VERSION}). Use a newer MinimoJS.`);
     }
-    // Version 1 is the only version. When the shape changes, an older file is
-    // migrated here, before its objects are checked against the newest shape.
-    if (!Array.isArray(json.objects)) {
-        throw fail(`"objects" must be a list, found ${describe(json.objects)}.`);
+    // Both versions are current, so neither is migrated: version 1 is a design
+    // without pages, and version 2 one divided into pages.
+    for (const field of Object.keys(json)) {
+        if (!DESIGN_FILE_FIELDS[version].has(field)) {
+            const hint = field === "pages" ? ` A design with pages has "version" 2.` : field === "objects" ? ` In version 2, objects belong to "pages".` : "";
+            throw fail(`the design has an unknown field "${field}".${hint}`);
+        }
     }
-    const indexById = new Map();
-    const objects = json.objects.map((entry, index) => {
-        const where = `objects[${index}]`;
-        const object = parseDesignObject(entry, where, "design");
-        const id = object.id.toLowerCase();
-        const firstIndex = indexById.get(id);
-        if (firstIndex !== undefined) {
-            throw fail(`the id "${object.id}" is used twice, by objects[${firstIndex}] and ${where}.`);
+    // An object's id is unique in the whole file, across pages.
+    const whereById = new Map();
+    const parseObjects = (entries, where) => {
+        if (!Array.isArray(entries)) {
+            throw fail(`${where === "" ? "" : `${where}.`}"objects" must be a list, found ${describe(entries)}.`);
+        }
+        return entries.map((entry, index) => {
+            const at = `${where === "" ? "" : `${where}.`}objects[${index}]`;
+            const object = parseDesignObject(entry, at, "design");
+            const id = object.id.toLowerCase();
+            const first = whereById.get(id);
+            if (first !== undefined) {
+                throw fail(`the id "${object.id}" is used twice, by ${first} and ${at}.`);
+            }
+            whereById.set(id, at);
+            return object;
+        });
+    };
+    if (version === 1) {
+        return { format: DESIGN_FILE_FORMAT, version: 1, objects: parseObjects(json.objects, "") };
+    }
+    if (!Array.isArray(json.pages)) {
+        throw fail(`"pages" must be a list, found ${describe(json.pages)}.`);
+    }
+    if (json.pages.length === 0) {
+        throw fail(`"pages" must hold at least one page. A design without pages has "version" 1 and a top-level "objects".`);
+    }
+    const pageIndexById = new Map();
+    const pageIndexByName = new Map();
+    const pages = json.pages.map((entry, index) => {
+        const where = `pages[${index}]`;
+        if (!isPlainObject(entry)) {
+            throw fail(`${where} must be an object, found ${describe(entry)}.`);
+        }
+        const name = entry.name;
+        const label = typeof name === "string" ? `${where} ("${name}")` : where;
+        for (const field of Object.keys(entry)) {
+            if (!DESIGN_PAGE_FIELDS.has(field)) {
+                throw fail(`${label} has an unknown field "${field}".`);
+            }
+        }
+        const id = entry.id;
+        if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+            throw fail(`${label} must have an "id" that is a UUID, such as "0b1d5e7a-3c2f-4d8e-9a61-7f4b2c8e1d05", found ${describe(id)}.`);
+        }
+        const firstWithId = pageIndexById.get(id.toLowerCase());
+        if (firstWithId !== undefined) {
+            throw fail(`the page id "${id}" is used twice, by pages[${firstWithId}] and ${where}.`);
+        }
+        pageIndexById.set(id.toLowerCase(), index);
+        if (typeof name !== "string" || name.length === 0 || name.trim() !== name) {
+            throw fail(`${where} must have a "name" that is a non-empty string with no leading or trailing spaces, found ${describe(name)}.`);
         }
-        indexById.set(id, index);
-        return object;
+        const firstWithName = pageIndexByName.get(name);
+        if (firstWithName !== undefined) {
+            throw fail(`the page name "${name}" is used twice, by pages[${firstWithName}] and ${where}.`);
+        }
+        pageIndexByName.set(name, index);
+        return { id, name, objects: parseObjects(entry.objects, where) };
     });
-    return { format: DESIGN_FILE_FORMAT, version: DESIGN_FILE_VERSION, objects };
+    return { format: DESIGN_FILE_FORMAT, version: 2, pages };
 }
 /**
  * Returns the first item `match` accepts, in order, or throws an error saying
@@ -357,8 +407,8 @@ export function findFirst(items, match, searched, where) {
     return found;
 }
 /**
- * The data of a design file, `*.design.json`, validated: its objects and
- * searches on them. A `Design` needs no game and creates nothing; pass its
+ * The data of a design file, `*.design.json`, validated: its objects, its
+ * pages, and searches on them. A `Design` needs no game and creates nothing; pass its
  * objects, or the results of its searches, to `game.createObject` or
  * `game.createObjectList`. Data alone also serves markers, such as spawn
  * points, which code reads without creating anything.
@@ -379,6 +429,14 @@ export function findFirst(items, match, searched, where) {
  *   }
  * }
  * ```
+ *
+ * A design divided into pages, such as a screen on one page and templates on
+ * another, is created one page at a time:
+ *
+ * ```ts
+ * const ui = game.createObjectList(menu.findAllByPage("Menu"));
+ * const bat = game.createObject(menu.findByPage("Bat"));
+ * ```
  */
 export class Design {
     /**
@@ -389,12 +447,50 @@ export class Design {
      * `"minimo-design"`, a `version` newer than this engine reads, an object
      * whose `type` is not one of the built-in types, an `id` that is not a UUID
      * or is used twice, a value of the wrong type, a missing required property,
-     * and a `data` that is not a JSON object.
+     * a `data` that is not a JSON object, and a page without a UUID `id` or with
+     * a missing, padded, or repeated `name`.
      *
      * @param json - The content of a `*.design.json` file. See {@link DesignFile}.
      */
     constructor(json) {
-        this.objects = Object.freeze(parseDesignFile(json).objects);
+        const file = parseDesignFile(json);
+        if (file.version === 1) {
+            this.pages = Object.freeze([]);
+            this.objects = Object.freeze(file.objects);
+        }
+        else {
+            this.pages = Object.freeze(file.pages.map((page) => Object.freeze({ ...page, objects: Object.freeze(page.objects) })));
+            this.objects = Object.freeze(file.pages.flatMap((page) => page.objects));
+        }
+    }
+    /**
+     * Returns the first object of the page named `name`, in file order, such
+     * as a page holding one template. Throws an error naming the page when the
+     * design has no page with that name, or the page has no objects.
+     */
+    findByPage(name) {
+        const page = this.pageNamed(name);
+        if (page.objects.length === 0) {
+            throw new Error(`MinimoJS: The page "${name}" of the design has no objects.`);
+        }
+        return page.objects[0];
+    }
+    /**
+     * Returns every object of the page named `name`, in file order; an empty
+     * list for an empty page. Throws an error naming the page when the design
+     * has no page with that name, because a page name that matches nothing is
+     * almost always a typo.
+     */
+    findAllByPage(name) {
+        return [...this.pageNamed(name).objects];
+    }
+    pageNamed(name) {
+        const page = this.pages.find((candidate) => candidate.name === name);
+        if (page === undefined) {
+            const known = this.pages.length === 0 ? "it has no pages" : `its pages are ${this.pages.map((p) => `"${p.name}"`).join(", ")}`;
+            throw new Error(`MinimoJS: No page named "${name}" in the design; ${known}.`);
+        }
+        return page;
     }
     /**
      * Returns the first object whose `name` is `name`, in file order.

package/dist/minimo.d.ts

@@ -13,7 +13,7 @@ import type { DesignObject } from "./minimo-format.js";
 export { Design, parseAssetFile } 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";
+export type { AssetFile, DesignBackground, DesignEmoji, DesignFile, DesignFileV1, DesignFileV2, DesignImage, DesignObject, DesignObjectBase, DesignObjectType, DesignPage, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, UnknownAsset, } from "./minimo-format.js";
 /**
  * Optional tuning values for {@link Game.animateExplode}.
  *
@@ -2072,9 +2072,12 @@ export declare class Game {
     /**
      * Plays a square-wave beep using the Web Audio API.
      *
-     * **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}.
+     * **Retro tone, not a game's sound.** This synthesizes a square-wave tone and
+     * needs no file, so it sounds like an old arcade machine. A game's music and
+     * sound effects are audio files: declare them as `sound` entries in an asset
+     * file, or load them with {@link Game.loadSound}, and play them with
+     * {@link Game.playSound}. Use tones only for a deliberately retro game, or
+     * when no audio file can be obtained.
      *
      * The AudioContext is created lazily on first call. Browsers require a user
      * gesture (click, keypress) before audio can play — always call `sound()` in
@@ -2092,13 +2095,16 @@ export declare class Game {
      * ```ts
      * game.sound(440, 100);   // 440 Hz beep for 100ms
      * game.sound(261, 500);   // middle C for 500ms
-     * game.sound(880, 50);    // high beep for 50ms (jump sound)
+     * game.sound(880, 50);    // high beep for 50ms
      * ```
      */
     sound(freq: number, durationMs: number): void;
     /**
      * Plays multiple square-wave tones in strict sequence.
      *
+     * Like {@link Game.sound}, this is a retro tone, not a game's sound: for
+     * music and sound effects, play audio files with {@link Game.playSound}.
+     *
      * Each tuple is `[frequencyHz, durationMs]`. The next tone starts when the
      * previous one ends.
      *

package/dist/minimo.js

@@ -2400,9 +2400,12 @@ export class Game {
     /**
      * Plays a square-wave beep using the Web Audio API.
      *
-     * **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}.
+     * **Retro tone, not a game's sound.** This synthesizes a square-wave tone and
+     * needs no file, so it sounds like an old arcade machine. A game's music and
+     * sound effects are audio files: declare them as `sound` entries in an asset
+     * file, or load them with {@link Game.loadSound}, and play them with
+     * {@link Game.playSound}. Use tones only for a deliberately retro game, or
+     * when no audio file can be obtained.
      *
      * The AudioContext is created lazily on first call. Browsers require a user
      * gesture (click, keypress) before audio can play — always call `sound()` in
@@ -2420,7 +2423,7 @@ export class Game {
      * ```ts
      * game.sound(440, 100);   // 440 Hz beep for 100ms
      * game.sound(261, 500);   // middle C for 500ms
-     * game.sound(880, 50);    // high beep for 50ms (jump sound)
+     * game.sound(880, 50);    // high beep for 50ms
      * ```
      */
     sound(freq, durationMs) {
@@ -2429,6 +2432,9 @@ export class Game {
     /**
      * Plays multiple square-wave tones in strict sequence.
      *
+     * Like {@link Game.sound}, this is a retro tone, not a game's sound: for
+     * music and sound effects, play audio files with {@link Game.playSound}.
+     *
      * Each tuple is `[frequencyHz, durationMs]`. The next tone starts when the
      * previous one ends.
      *

package/package.json

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