minimojs 1.0.0-alpha.27 → 1.0.0-alpha.29

package/dist/minimo.js

@@ -22,6 +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, findFirst, parseAssetFile, parseDesignObject } from "./minimo-format.js";
+export { Design, parseAssetFile } from "./minimo-format.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. */
@@ -172,6 +174,35 @@ export class Sprite {
          * Values > 1 amplify gravity; negative values invert it.
          */
         this.gravityScale = 0;
+        /**
+         * Optional name, so code can ask an object what it is. Names may repeat,
+         * like a `name` attribute in the DOM. The engine never reads it.
+         * A sprite created from a design file takes the object's `name`.
+         *
+         * @example
+         * ```ts
+         * if (other.name === "door") openDoor();
+         * ```
+         */
+        this.name = undefined;
+        /**
+         * Tags for grouping, like CSS classes in the DOM. Empty by default. The
+         * engine never reads them. A sprite created from a design file takes the
+         * object's `tags`, which {@link Game.registerBuilderByTag} also matches.
+         *
+         * @example
+         * ```ts
+         * if (other.tags.includes("coin")) collect(other);
+         * ```
+         */
+        this.tags = [];
+        /**
+         * The game's own values for this object, such as a button's action or an
+         * enemy's speed. An empty object by default, so `sprite.data.hp = 3` needs
+         * no check. The engine never reads it. A sprite created from a design file
+         * takes a copy of the object's `data`.
+         */
+        this.data = {};
         // `abstract` and `protected` are erased by the TypeScript compiler, and games
         // are written in JavaScript, so nothing but this check stops old code from
         // calling `new Sprite(glyph, x, y, size)`. Without it the glyph would be
@@ -823,6 +854,21 @@ export class BackgroundLayer {
          * Default: `"cover"`.
          */
         this.fit = "cover";
+        /**
+         * Optional name, so code can ask a layer what it is. Names may repeat. The
+         * engine never reads it. See {@link Sprite.name}.
+         */
+        this.name = undefined;
+        /**
+         * Tags for grouping. Empty by default. The engine never reads them. See
+         * {@link Sprite.tags}.
+         */
+        this.tags = [];
+        /**
+         * The game's own values for this layer. An empty object by default. The
+         * engine never reads it. See {@link Sprite.data}.
+         */
+        this.data = {};
         this.imageKey = imageKey;
         this.x = x;
         this.y = y;
@@ -830,6 +876,67 @@ export class BackgroundLayer {
         this.height = height;
     }
 }
+/**
+ * The objects {@link Game.createObjectList} created, in the order of their
+ * data, and searches on them.
+ *
+ * An `ObjectList` only holds and finds its objects; it never changes them.
+ * Remove them through the game, as any other object:
+ *
+ * ```ts
+ * for (const obj of ui.objects) {
+ *   if (obj instanceof BackgroundLayer) game.destroyBackgroundLayer(obj);
+ *   else game.destroySprite(obj);
+ * }
+ * ```
+ *
+ * Searches read each object's current {@link Sprite.name} and
+ * {@link Sprite.tags}. In TypeScript, name the type you expect:
+ * `ui.findByName<ImageSprite>("play")`.
+ */
+export class ObjectList {
+    /** @internal */
+    constructor(objects) {
+        this.objects = Object.freeze([...objects]);
+    }
+    /**
+     * Returns the first object whose `name` is `name`, in order.
+     * Throws an error naming `name` when there is none.
+     *
+     * @example
+     * ```ts
+     * const play = ui.findByName("play");
+     * ```
+     */
+    findByName(name) {
+        return findFirst(this.objects, (obj) => obj.name === name, `named "${name}"`, "the object list");
+    }
+    /** Returns every object whose `name` is `name`, in order; an empty list when there is none. */
+    findAllByName(name) {
+        return this.objects.filter((obj) => obj.name === name);
+    }
+    /**
+     * Returns the first object whose `tags` include `tag`, in order.
+     * Throws an error naming `tag` when there is none.
+     */
+    findByTag(tag) {
+        return findFirst(this.objects, (obj) => obj.tags.includes(tag), `tagged "${tag}"`, "the object list");
+    }
+    /** Returns every object whose `tags` include `tag`, in order; an empty list when there is none. */
+    findAllByTag(tag) {
+        return this.objects.filter((obj) => obj.tags.includes(tag));
+    }
+}
+/** The runtime class of each type of design object. */
+const DESIGN_OBJECT_CLASSES = {
+    image: ImageSprite,
+    emoji: EmojiSprite,
+    text: TextSprite,
+    background: BackgroundLayer,
+};
+function describeDesignObject(obj) {
+    return obj.name === undefined ? `the object ${obj.id}` : `the object "${obj.name}" (${obj.id})`;
+}
 // ---------------------------------------------------------------------------
 // Internal types (not part of the public API declarations)
 // ---------------------------------------------------------------------------
@@ -1267,6 +1374,7 @@ export class Game {
         /** @internal */ this._sceneLoad = null;
         /** @internal */ this._onCreate = null;
         /** @internal */ this._currentScene = null;
+        /** @internal */ this._buildersByTag = new Map();
         /**
          * Horizontal scroll offset of the world camera, in pixels.
          * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
@@ -1341,7 +1449,7 @@ 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.loadImage}. The callback is synchronous: it should only
+         * with {@link Game.loadAssets} or {@link Game.loadImage}. The callback is synchronous: it should only
          * queue assets, not await network work.
          *
          * After `onPreload` returns, MinimoJS loads the queued images, together with
@@ -1429,6 +1537,11 @@ export class Game {
      * in pixels. Updated every `mousemove` / `touchmove` event.
      * `(0, 0)` is the top-left corner of the canvas.
      * To convert to world space: `worldX = game.pointerX + game.scrollX`.
+     *
+     * On a touch screen the pointer is one finger: the first to touch while no
+     * finger is followed. Other fingers never move it, and when the followed
+     * finger lifts, the pointer stays where it left the screen even if others
+     * are still down. Use {@link Game.getPointers} to follow several fingers.
      */
     get pointerX() {
         return this._inputSystem.pointerX;
@@ -1584,6 +1697,48 @@ export class Game {
         }
         this._assetSystem.queueImage(key, src);
     }
+    /**
+     * Queues every asset an asset file declares, as one {@link Game.loadImage}
+     * call per `image` 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
+     * error naming what is wrong. Like `loadImage`, `loadAssets` may only be
+     * called from within {@link Game.onPreload} or a scene's
+     * {@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
+     *   `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.
+     * - 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.
+     *
+     * @param assets - The content of a `*.assets.json` file. See {@link AssetFile}.
+     *
+     * @example
+     * ```ts
+     * import common from "./common.assets.json" with { type: "json" };
+     *
+     * game.onPreload = () => game.loadAssets(common);
+     * ```
+     */
+    loadAssets(assets) {
+        if (!this._isRegisteringPreloadAssets) {
+            throw new Error("MinimoJS: loadAssets() may only be called inside game.onPreload or a scene's onPreload().");
+        }
+        const file = parseAssetFile(assets);
+        const isFirstLoad = this._assetSystem.registerAssetFile(file, assets);
+        if (!isFirstLoad)
+            return;
+        for (const entry of file.assets) {
+            if (entry.type !== "image") {
+                console.warn(`MinimoJS: Skipped the asset "${entry.key}", whose type "${entry.type}" this version of MinimoJS does not support.`);
+            }
+        }
+    }
     /**
      * Creates a dynamic texture immediately and registers it under a stable key.
      *
@@ -1631,6 +1786,202 @@ export class Game {
         return this._assetSystem.hasImage(key);
     }
     // -------------------------------------------------------------------------
+    // Designs
+    // -------------------------------------------------------------------------
+    /**
+     * Creates one runtime object from object data, such as a template found in
+     * a {@link Design}, and adds it to the game.
+     *
+     * The object is built through the same public constructors and
+     * {@link Game.add} or {@link Game.addBackground} that code uses, so it
+     * behaves as the equivalent code. Its type picks its class: `image` builds
+     * an {@link ImageSprite}, `emoji` an {@link EmojiSprite}, `text` a
+     * {@link TextSprite}, and `background` a {@link BackgroundLayer}, unless a
+     * builder registered with {@link Game.registerBuilderByTag} matches one of
+     * its tags. Then every property the data holds is applied, including
+     * `name`, `tags`, and a copy of `data`.
+     *
+     * Each call creates a new object, so one template can be created any number
+     * of times. Set its position afterwards to place it; the object is never
+     * drawn at the template's position.
+     *
+     * Throws an error naming what is wrong when the data is not a valid design
+     * object, or naming the key when it uses an image key that is not loaded.
+     *
+     * @param data - One design object, such as `design.findByName("player")`. Not a `Design`.
+     * @param options - `add: false` creates the object without adding it to the game. Default: added.
+     * @returns The created object. In TypeScript, name its type: `game.createObject<ImageSprite>(data)`.
+     *
+     * @example
+     * ```ts
+     * import charactersJson from "./characters.design.json" with { type: "json" };
+     * const characters = new Design(charactersJson);
+     *
+     * const bat = game.createObject(characters.findByName("bat"));
+     * bat.x = spawn.x;
+     * bat.y = spawn.y;
+     * ```
+     */
+    createObject(data, options = {}) {
+        if (data instanceof Design) {
+            throw new Error("MinimoJS: createObject() takes one object's data, not a Design. Pass a search's result, such as design.findByName(\"player\"), or use createObjectList(design.objects).");
+        }
+        const obj = parseDesignObject(data, "the object", "design object");
+        this._assertDesignImageLoaded(obj);
+        const created = this._buildDesignObject(obj);
+        if (options.add !== false)
+            this._addDesignObject(created);
+        return created;
+    }
+    /**
+     * Creates a runtime object from each object data, in order, and adds them
+     * to the game, as {@link Game.createObject} does for one. Objects in the
+     * same layer draw in the order of the data.
+     *
+     * Every object is checked before any is created, so invalid data or an
+     * image key that is not loaded creates nothing.
+     *
+     * @param objects - Object data, such as `design.objects` or `design.findAllByTag("enemy")`. Not a `Design`.
+     * @param options - `add: false` creates the objects without adding them to the game. Default: added.
+     * @returns An {@link ObjectList} of the created objects, to find them by name or tag.
+     *
+     * @example
+     * ```ts
+     * import menuJson from "./menu.design.json" with { type: "json" };
+     * const menu = new Design(menuJson);
+     *
+     * class MenuScene {
+     *   onCreate() {
+     *     const ui = game.createObjectList(menu.objects);
+     *     this.play = ui.findByName("play");
+     *   }
+     *   onUpdate() {
+     *     if (game.isPointerPressedOverSprite(this.play)) start(this.play.data.action);
+     *   }
+     * }
+     * ```
+     */
+    createObjectList(objects, options = {}) {
+        if (!Array.isArray(objects)) {
+            throw new Error("MinimoJS: createObjectList() takes a list of object data, such as design.objects or design.findAllByTag(\"enemy\").");
+        }
+        const parsed = objects.map((data, index) => parseDesignObject(data, `objects[${index}]`, "design object"));
+        for (const obj of parsed)
+            this._assertDesignImageLoaded(obj);
+        const created = parsed.map((obj) => this._buildDesignObject(obj));
+        if (options.add !== false) {
+            for (const obj of created)
+                this._addDesignObject(obj);
+        }
+        return new ObjectList(created);
+    }
+    /**
+     * Makes {@link Game.createObject} and {@link Game.createObjectList} build
+     * the design objects tagged `tag` with `builder`, such as an `Enemy` class
+     * of the game's own.
+     *
+     * - The builder returns an instance of the object's type class or a
+     *   subclass of it: {@link ImageSprite} for `image`, {@link EmojiSprite} for
+     *   `emoji`, {@link TextSprite} for `text`, and {@link BackgroundLayer} for
+     *   `background`. Anything else throws an error naming the object.
+     * - The engine then applies every property the data holds, so the file wins
+     *   over the constructor. Properties the data omits keep what the builder set.
+     *   An `emoji` object's `size` cannot be changed after construction, so a
+     *   builder must pass it on, or the creation throws.
+     * - An object matching the builders of two of its tags throws an error
+     *   naming the object and both tags.
+     * - Builders are scene state: {@link Game.reset} clears them, as it clears
+     *   timers, so each scene registers its own in `onCreate()`.
+     *
+     * @param tag - The tag whose objects the builder builds.
+     * @param builder - Receives the object's data and the game, and returns the object, not yet added.
+     *
+     * @example
+     * ```ts
+     * class Enemy extends ImageSprite {
+     *   update(dt) { this.x += this.data.speed * dt; }
+     * }
+     *
+     * class Level1Scene {
+     *   onCreate() {
+     *     game.registerBuilderByTag("enemy", (obj, game) => new Enemy(game, obj.imageKey));
+     *     this.enemies = game.createObjectList(level1.findAllByTag("enemy")).objects;
+     *   }
+     * }
+     * ```
+     */
+    registerBuilderByTag(tag, builder) {
+        if (typeof tag !== "string" || tag.length === 0) {
+            throw new Error("MinimoJS: registerBuilderByTag() requires a non-empty tag.");
+        }
+        if (typeof builder !== "function") {
+            throw new Error(`MinimoJS: registerBuilderByTag("${tag}") requires a builder function.`);
+        }
+        if (this._buildersByTag.has(tag)) {
+            throw new Error(`MinimoJS: A builder is already registered for the tag "${tag}". game.reset() clears builders, so register each in a scene's onCreate().`);
+        }
+        this._buildersByTag.set(tag, builder);
+    }
+    /** @internal */
+    _assertDesignImageLoaded(obj) {
+        if ((obj.type === "image" || obj.type === "background") && !this.hasImage(obj.imageKey)) {
+            throw new Error(`MinimoJS: ${describeDesignObject(obj)} uses the image key "${obj.imageKey}", which is not loaded. Declare it in an asset file and load that file with game.loadAssets() in an onPreload hook.`);
+        }
+    }
+    /** @internal */
+    _buildDesignObject(obj) {
+        const matchingTags = [...new Set(obj.tags ?? [])].filter((tag) => this._buildersByTag.has(tag));
+        if (matchingTags.length > 1) {
+            throw new Error(`MinimoJS: ${describeDesignObject(obj)} matches the builders of two of its tags, "${matchingTags[0]}" and "${matchingTags[1]}". An object may match at most one builder.`);
+        }
+        const tag = matchingTags[0];
+        const builder = tag === undefined ? undefined : this._buildersByTag.get(tag);
+        let created;
+        if (builder === undefined) {
+            created =
+                obj.type === "image"
+                    ? new ImageSprite(this, obj.imageKey)
+                    : obj.type === "emoji"
+                        ? new EmojiSprite(obj.sprite, 0, 0, obj.size)
+                        : obj.type === "text"
+                            ? new TextSprite(obj.text, 0, 0, obj.fontSize)
+                            : new BackgroundLayer(obj.imageKey);
+        }
+        else {
+            created = builder(obj, this);
+            const expected = DESIGN_OBJECT_CLASSES[obj.type];
+            if (!(created instanceof expected)) {
+                throw new Error(`MinimoJS: The builder for the tag "${tag}" did not return an instance of ${expected.name} or of a subclass of it for ${describeDesignObject(obj)}, whose type is "${obj.type}".`);
+            }
+            if (obj.type === "emoji" && obj.size !== undefined && created.size !== obj.size) {
+                throw new Error(`MinimoJS: The builder for the tag "${tag}" built ${describeDesignObject(obj)} with the size ${created.size}, but its data says ${obj.size}. An EmojiSprite's size is set only by its constructor, so pass obj.size to it.`);
+            }
+        }
+        const target = created;
+        for (const [field, value] of Object.entries(obj)) {
+            if (field === "id" || field === "type")
+                continue;
+            if (field === "size" && created instanceof EmojiSprite)
+                continue;
+            if (field === "imageKey" && created instanceof ImageSprite) {
+                created.setTexture(value);
+                continue;
+            }
+            target[field] = value;
+        }
+        return created;
+    }
+    /** @internal */
+    _addDesignObject(obj) {
+        if (obj instanceof BackgroundLayer) {
+            if (!this._backgroundSystem.getMutableLayers().includes(obj))
+                this.addBackground(obj);
+        }
+        else if (!this._spriteSystem.getMutableSprites().includes(obj)) {
+            this.add(obj);
+        }
+    }
+    // -------------------------------------------------------------------------
     // Collision
     // -------------------------------------------------------------------------
     /**
@@ -1788,6 +2139,8 @@ export class Game {
      * Use this for continuous pointer actions.
      *
      * **Hold behavior:** returns `true` every frame from press until release.
+     * On a touch screen it follows one finger, as {@link Game.pointerX} does,
+     * so it turns `false` when that finger lifts, even if another is down.
      *
      * @returns `true` if the pointer is currently pressed.
      *
@@ -2649,6 +3002,7 @@ export class Game {
         this._trailSystem.clearAll();
         this._textSystem.clear();
         this._inputSystem.resetPressedState();
+        this._buildersByTag.clear();
         this.scrollX = 0;
         this.scrollY = 0;
         this._loopSystem.invokeCreate();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.27",
+  "version": "1.0.0-alpha.29",
   "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",
@@ -9,6 +9,10 @@
     ".": {
       "import": "./dist/minimo.js",
       "types": "./dist/minimo.d.ts"
+    },
+    "./format": {
+      "import": "./dist/minimo-format.js",
+      "types": "./dist/minimo-format.d.ts"
     }
   },
   "files": [
@@ -21,7 +25,8 @@
     "clean": "rm -rf dist",
     "rebuild": "npm run clean && npm run build",
     "prepack": "npm run build",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "test": "npm run build && node --test \"test/*.test.mjs\""
   },
   "keywords": [
     "game",