minimojs 1.0.0-alpha.28 → 1.0.0-alpha.29

package/dist/minimo.d.ts

@@ -7,6 +7,9 @@
  * ALL ROTATIONS ARE IN DEGREES.
  * THE ENGINE LOOP USES requestAnimationFrame ONLY.
  */
+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";
 /**
  * Optional tuning values for {@link Game.animateExplode}.
  *
@@ -197,9 +200,9 @@ 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.loadImage} inside it, as inside
-     * `game.onPreload`. Images that are already loaded are skipped, so replaying
-     * a scene loads nothing.
+     * {@link IScene.onCreate}. Call {@link Game.loadAssets} or
+     * {@link Game.loadImage} 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
      * progress ring until they load, and only then is this scene created.
@@ -419,6 +422,35 @@ export declare abstract class Sprite {
      * Values > 1 amplify gravity; negative values invert it.
      */
     gravityScale: number;
+    /**
+     * 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();
+     * ```
+     */
+    name: string | 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);
+     * ```
+     */
+    tags: string[];
+    /**
+     * 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`.
+     */
+    data: Record<string, unknown>;
     /**
      * Stable cache key describing the sprite's rendered appearance.
      *
@@ -728,6 +760,21 @@ export declare class BackgroundLayer {
      * Default: `"cover"`.
      */
     fit: BackgroundFit;
+    /**
+     * Optional name, so code can ask a layer what it is. Names may repeat. The
+     * engine never reads it. See {@link Sprite.name}.
+     */
+    name: string | undefined;
+    /**
+     * Tags for grouping. Empty by default. The engine never reads them. See
+     * {@link Sprite.tags}.
+     */
+    tags: string[];
+    /**
+     * The game's own values for this layer. An empty object by default. The
+     * engine never reads it. See {@link Sprite.data}.
+     */
+    data: Record<string, unknown>;
     /**
      * Creates a new background layer.
      *
@@ -739,6 +786,52 @@ export declare class BackgroundLayer {
      */
     constructor(imageKey: string, x?: number, y?: number, width?: number, height?: number);
 }
+/**
+ * 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 declare class ObjectList {
+    /** Every object created, in the order of the data. */
+    readonly objects: readonly (Sprite | BackgroundLayer)[];
+    /**
+     * 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<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(name: string): T;
+    /** Returns every object whose `name` is `name`, in order; an empty list when there is none. */
+    findAllByName<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(name: string): T[];
+    /**
+     * Returns the first object whose `tags` include `tag`, in order.
+     * Throws an error naming `tag` when there is none.
+     */
+    findByTag<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(tag: string): T;
+    /** Returns every object whose `tags` include `tag`, in order; an empty list when there is none. */
+    findAllByTag<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(tag: string): T[];
+}
+/**
+ * Builds the object for a design object whose tags include the tag it was
+ * registered for. See {@link Game.registerBuilderByTag}.
+ */
+export type ObjectBuilder = (obj: DesignObject, game: Game) => Sprite | BackgroundLayer;
 /**
  * Snapshot of an active pointer tracked by the engine.
  *
@@ -1214,7 +1307,7 @@ 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.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
@@ -1448,6 +1541,35 @@ export declare class Game {
      * ```
      */
     loadImage(key: string, src: string): void;
+    /**
+     * 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: unknown): void;
     /**
      * Creates a dynamic texture immediately and registers it under a stable key.
      *
@@ -1484,6 +1606,110 @@ export declare class Game {
      * Returns `true` if a texture key is available.
      */
     hasImage(key: string): boolean;
+    /**
+     * 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<T extends Sprite | BackgroundLayer = Sprite | BackgroundLayer>(data: DesignObject, options?: {
+        add?: boolean;
+    }): T;
+    /**
+     * 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: readonly DesignObject[], options?: {
+        add?: boolean;
+    }): ObjectList;
+    /**
+     * 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: string, builder: ObjectBuilder): void;
     /**
      * Tests whether two sprites overlap using **Axis-Aligned Bounding Box (AABB)**
      * collision detection.