minimojs 1.0.0-alpha.39 → 1.0.0-alpha.40

package/dist/minimo-dice.d.ts

@@ -93,6 +93,28 @@ export interface DieRollOptions {
  * const value = 1 + Math.floor(game.random() * 20);
  * await d20.roll(value, { spin: { x: 540, y: -360, z: 90 }, ms: 1200 });
  * ```
+ *
+ * ## In a design
+ *
+ * A design can place dice, so the creator moves them in the design editor. A
+ * die is a `module` object of a version 3 design whose `kind` is `"d4"`,
+ * `"d6"`, `"d8"`, `"d10"`, `"d12"`, or `"d20"`, and a design sets only its
+ * `x` and `y`. Its look and size are the set's, as for {@link Dice.create}
+ * without options, and it shows its 1 until the game rolls it.
+ *
+ * ```json
+ * { "id": "9a2c4e6f-1b3d-4f5a-8c7e-0d2f4b6a8c1e", "name": "d20", "type": "module", "module": "dice", "kind": "d20", "x": 360, "y": 640 }
+ * ```
+ *
+ * Create the set in the scene's `onCreate()` before the design's objects,
+ * then find the die by its name:
+ *
+ * ```ts
+ * onCreate() {
+ *   this.dice = new Dice(game, { color: "#f4f1ea" });
+ *   this.d20 = game.createObjectList(board.objects).findByName("d20");
+ * }
+ * ```
  */
 export declare class Dice {
     /** The game the dice are added to. */
@@ -111,7 +133,10 @@ export declare class Dice {
     create(sides: DieSides, options?: DieOptions): Die;
     /** Removes a die from the game and from this set. */
     remove(die: Die): void;
-    /** Advances every die of the set. Call it once per frame from `onUpdate`. */
+    /**
+     * Advances every die of the set. Call it once per frame from `onUpdate`.
+     * A die the game destroyed, such as by `game.reset()`, leaves the set.
+     */
     update(dt: number): void;
 }
 /**

package/dist/minimo-dice.js

@@ -31,6 +31,28 @@ const HIGHLIGHT = normalize(add(LIGHT, [0, 0, 1]));
  * const value = 1 + Math.floor(game.random() * 20);
  * await d20.roll(value, { spin: { x: 540, y: -360, z: 90 }, ms: 1200 });
  * ```
+ *
+ * ## In a design
+ *
+ * A design can place dice, so the creator moves them in the design editor. A
+ * die is a `module` object of a version 3 design whose `kind` is `"d4"`,
+ * `"d6"`, `"d8"`, `"d10"`, `"d12"`, or `"d20"`, and a design sets only its
+ * `x` and `y`. Its look and size are the set's, as for {@link Dice.create}
+ * without options, and it shows its 1 until the game rolls it.
+ *
+ * ```json
+ * { "id": "9a2c4e6f-1b3d-4f5a-8c7e-0d2f4b6a8c1e", "name": "d20", "type": "module", "module": "dice", "kind": "d20", "x": 360, "y": 640 }
+ * ```
+ *
+ * Create the set in the scene's `onCreate()` before the design's objects,
+ * then find the die by its name:
+ *
+ * ```ts
+ * onCreate() {
+ *   this.dice = new Dice(game, { color: "#f4f1ea" });
+ *   this.d20 = game.createObjectList(board.objects).findByName("d20");
+ * }
+ * ```
  */
 export class Dice {
     constructor(game, look = {}) {
@@ -38,6 +60,7 @@ export class Dice {
         this._dice = [];
         this.game = game;
         this.look = { ...look };
+        game._registerDesignModule("dice", (obj) => this._fromDesign(obj));
     }
     /** The dice of this set, in the order they were made. */
     get dice() {
@@ -62,10 +85,34 @@ export class Dice {
             this._dice.splice(index, 1);
         this.game.destroySprite(die);
     }
-    /** Advances every die of the set. Call it once per frame from `onUpdate`. */
+    /**
+     * Builds a die placed in a design, with the set's look. The game adds it.
+     *
+     * @internal
+     */
+    _fromDesign(obj) {
+        const die = new Die(Number(obj.kind.slice(1)), { ...this.look });
+        die._pending = true;
+        this._dice.push(die);
+        return die;
+    }
+    /**
+     * Advances every die of the set. Call it once per frame from `onUpdate`.
+     * A die the game destroyed, such as by `game.reset()`, leaves the set.
+     */
     update(dt) {
-        for (const die of this._dice)
+        const alive = new Set(this.game.getSprites());
+        for (const die of [...this._dice]) {
+            if (!alive.has(die)) {
+                // A die a design built waits to be added, as with createObject's
+                // `add: false`; one that was in the game and left it is dropped.
+                if (!die._pending)
+                    this._dice.splice(this._dice.indexOf(die), 1);
+                continue;
+            }
+            die._pending = false;
             die.update(dt);
+        }
     }
 }
 /**
@@ -99,6 +146,8 @@ export class Die extends DrawSprite {
         this._landing = null;
         /** @internal */
         this._waiting = [];
+        /** @internal Built from a design and not yet seen in the game. */
+        this._pending = false;
         this.sides = sides;
         this.size = size;
         this.bodyWidth = size;
@@ -109,6 +158,11 @@ export class Die extends DrawSprite {
         this._look = look;
         this._orientation = restOrientation(solid, this._checkValue(options.value ?? 1));
     }
+    /** @internal A design editor selects the die itself, not the room its surface keeps for turning. */
+    _editorBox() {
+        const scale = Number.isFinite(this.scale) ? Math.max(0, this.scale) : 1;
+        return { cx: this.renderX, cy: this.renderY, w: this.size * scale, h: this.size * scale };
+    }
     /** The look of this die. Change it with {@link Die.setLook}. */
     get look() {
         return this._look;

package/dist/minimo-fire.d.ts

@@ -131,6 +131,39 @@ type InternalKind = FlameKind | "burst" | "explosion";
  * fire.attach(fireball, { kind: "trail", palette: "blue" });
  * torch.extinguish(600);
  * ```
+ *
+ * ## In a design
+ *
+ * A design can place `torch`, `campfire`, `burning`, and `trail` flames, so
+ * the creator moves and resizes them in the design editor. Each is a
+ * `module` object of a version 3 design. It takes `x`, `y`, `alpha`,
+ * `visible`, `layer`, `ignoreScroll`, and the collision body's properties,
+ * never `scale` or `rotation`: its `size` option resizes it. Its `options`
+ * are `size`, `intensity`, `palette` (a palette's name), `style`, `smoke`,
+ * `sparks`, `smokeColor`, and `light`, each as in {@link FlameOptions}.
+ *
+ * ```json
+ * { "id": "3e7b1c9a-5d2f-4a8e-b0c6-9f1d2e4a7b35", "name": "left-torch", "type": "module", "module": "fire", "kind": "torch", "x": 120, "y": 200, "layer": 2, "options": { "size": 28, "palette": "blue" } }
+ * ```
+ *
+ * A placed flame looks as its options say and the module's defaults, never
+ * as the look given to `new Fire(game, …)`, so the game shows what the editor
+ * showed, and it is already burning when its screen opens. `burst` and
+ * `explosion` are moments, made in code. Create the fire in the scene's
+ * `onCreate()` before the design's objects, then find a flame by its name
+ * to change it while the game plays, and advance the fire every frame:
+ *
+ * ```ts
+ * onCreate() {
+ *   this.fire = new Fire(game);
+ *   const room = game.createObjectList(dungeon.objects);
+ *   this.torch = room.findByName("left-torch"); // later: this.torch.extinguish()
+ *   room.findByName("barrel-fire").follow(room.findByName("barrel"));
+ * }
+ * onUpdate(dt) {
+ *   this.fire.update(dt);
+ * }
+ * ```
  */
 export declare class Fire {
     /** The game the flames are added to. */
@@ -225,6 +258,13 @@ export declare class Flame extends DrawSprite {
     get out(): boolean;
     /** The sprite this flame follows, or `null`. */
     get target(): Sprite | null;
+    /**
+     * Makes the flame follow `sprite` every frame, keeping the offset it has
+     * from it now, as a flame placed over a sprite in a design keeps where the
+     * creator put it. It hides with the sprite and goes out when the sprite is
+     * destroyed. `null` stops following and leaves the flame where it is.
+     */
+    follow(sprite: Sprite | null): void;
     /**
      * Changes the intensity over `ms` milliseconds.
      * @returns A promise that resolves when it gets there, or when another change replaces it.

package/dist/minimo-fire.js

@@ -1,12 +1,15 @@
 import { DrawSprite } from "./minimo.js";
 const KINDS = {
-    torch: { spread: 0.16, spreadY: 0.04, rise: 4.2, life: 0.62, radius: 0.42, rate: 46, smoke: 0.15, sparks: 0.25, light: true, width: 3.6, up: 3.8, down: 1.6, bodyWidth: 0.6, bodyHeight: 1.1, bodyRise: 0.5 },
-    campfire: { spread: 0.4, spreadY: 0.05, rise: 3.4, life: 0.72, radius: 0.34, rate: 80, smoke: 0.4, sparks: 0.5, light: true, width: 3.8, up: 3.8, down: 1.5, bodyWidth: 0.85, bodyHeight: 1, bodyRise: 0.45 },
-    burning: { spread: 0.45, spreadY: 0.35, rise: 2.1, life: 0.5, radius: 0.24, rate: 90, smoke: 0.3, sparks: 0.25, light: false, width: 2.4, up: 2.6, down: 1, bodyWidth: 0.9, bodyHeight: 0.9, bodyRise: 0.1 },
-    trail: { spread: 0.12, spreadY: 0.12, rise: 0.35, life: 0.45, radius: 0.55, rate: 160, smoke: 0.35, sparks: 0.3, light: false, width: 14, up: 7, down: 7, bodyWidth: 0.8, bodyHeight: 0.8, bodyRise: 0 },
-    burst: { spread: 0.42, spreadY: 0.06, rise: 3.2, life: 0.7, radius: 0.34, rate: 80, smoke: 0.5, sparks: 0.5, light: true, width: 4, up: 4, down: 1.8, bodyWidth: 0.85, bodyHeight: 1, bodyRise: 0.45 },
-    explosion: { spread: 0, spreadY: 0, rise: 0, life: 0.5, radius: 0.34, rate: 0, smoke: 0.7, sparks: 0.7, light: true, width: 3.2, up: 2.8, down: 1.7, bodyWidth: 0.8, bodyHeight: 0.8, bodyRise: 0 },
+    torch: { spread: 0.16, spreadY: 0.04, rise: 4.2, life: 0.62, radius: 0.42, rate: 46, smoke: 0.15, sparks: 0.25, light: true, width: 3.6, up: 3.8, down: 1.6, bodyWidth: 0.6, bodyHeight: 1.1, bodyRise: 0.5, boxWidth: 0.7, boxHeight: 1.9, boxRise: 0.8 },
+    campfire: { spread: 0.4, spreadY: 0.05, rise: 3.4, life: 0.72, radius: 0.34, rate: 80, smoke: 0.4, sparks: 0.5, light: true, width: 3.8, up: 3.8, down: 1.5, bodyWidth: 0.85, bodyHeight: 1, bodyRise: 0.45, boxWidth: 1.2, boxHeight: 1.8, boxRise: 0.75 },
+    burning: { spread: 0.45, spreadY: 0.35, rise: 2.1, life: 0.5, radius: 0.24, rate: 90, smoke: 0.3, sparks: 0.25, light: false, width: 2.4, up: 2.6, down: 1, bodyWidth: 0.9, bodyHeight: 0.9, bodyRise: 0.1, boxWidth: 1.3, boxHeight: 1.6, boxRise: 0.5 },
+    trail: { spread: 0.12, spreadY: 0.12, rise: 0.35, life: 0.45, radius: 0.55, rate: 160, smoke: 0.35, sparks: 0.3, light: false, width: 14, up: 7, down: 7, bodyWidth: 0.8, bodyHeight: 0.8, bodyRise: 0, boxWidth: 1.2, boxHeight: 1.2, boxRise: 0 },
+    burst: { spread: 0.42, spreadY: 0.06, rise: 3.2, life: 0.7, radius: 0.34, rate: 80, smoke: 0.5, sparks: 0.5, light: true, width: 4, up: 4, down: 1.8, bodyWidth: 0.85, bodyHeight: 1, bodyRise: 0.45, boxWidth: 1.2, boxHeight: 1.8, boxRise: 0.75 },
+    explosion: { spread: 0, spreadY: 0, rise: 0, life: 0.5, radius: 0.34, rate: 0, smoke: 0.7, sparks: 0.7, light: true, width: 3.2, up: 2.8, down: 1.7, bodyWidth: 0.8, bodyHeight: 0.8, bodyRise: 0, boxWidth: 2, boxHeight: 2, boxRise: 0 },
 };
+/** How long of burning a flame placed in a design has behind it when it first appears, in seconds. */
+const PREWARM_SECONDS = 1.5;
+const PREWARM_STEP = 1 / 30;
 const PALETTES = {
     fire: ["#fff4b8", "#ffab2e", "#e8401c"],
     blue: ["#eef9ff", "#5cc8ff", "#2c4fff"],
@@ -39,6 +42,39 @@ const SPARK = 2;
  * fire.attach(fireball, { kind: "trail", palette: "blue" });
  * torch.extinguish(600);
  * ```
+ *
+ * ## In a design
+ *
+ * A design can place `torch`, `campfire`, `burning`, and `trail` flames, so
+ * the creator moves and resizes them in the design editor. Each is a
+ * `module` object of a version 3 design. It takes `x`, `y`, `alpha`,
+ * `visible`, `layer`, `ignoreScroll`, and the collision body's properties,
+ * never `scale` or `rotation`: its `size` option resizes it. Its `options`
+ * are `size`, `intensity`, `palette` (a palette's name), `style`, `smoke`,
+ * `sparks`, `smokeColor`, and `light`, each as in {@link FlameOptions}.
+ *
+ * ```json
+ * { "id": "3e7b1c9a-5d2f-4a8e-b0c6-9f1d2e4a7b35", "name": "left-torch", "type": "module", "module": "fire", "kind": "torch", "x": 120, "y": 200, "layer": 2, "options": { "size": 28, "palette": "blue" } }
+ * ```
+ *
+ * A placed flame looks as its options say and the module's defaults, never
+ * as the look given to `new Fire(game, …)`, so the game shows what the editor
+ * showed, and it is already burning when its screen opens. `burst` and
+ * `explosion` are moments, made in code. Create the fire in the scene's
+ * `onCreate()` before the design's objects, then find a flame by its name
+ * to change it while the game plays, and advance the fire every frame:
+ *
+ * ```ts
+ * onCreate() {
+ *   this.fire = new Fire(game);
+ *   const room = game.createObjectList(dungeon.objects);
+ *   this.torch = room.findByName("left-torch"); // later: this.torch.extinguish()
+ *   room.findByName("barrel-fire").follow(room.findByName("barrel"));
+ * }
+ * onUpdate(dt) {
+ *   this.fire.update(dt);
+ * }
+ * ```
  */
 export class Fire {
     constructor(game, options = {}) {
@@ -61,6 +97,7 @@ export class Fire {
         if (maxParticles === undefined && game.isMobileDevice() && cores <= 4)
             max = Math.round(max * 0.6);
         this._maxParticles = max;
+        game._registerDesignModule("fire", (obj) => this._fromDesign(obj));
     }
     /** The flames burning now, in the order they were made. */
     get flames() {
@@ -147,9 +184,13 @@ export class Fire {
         const alive = new Set(this.game.getSprites());
         for (const flame of [...this._flames]) {
             if (!alive.has(flame)) {
-                this._drop(flame);
+                // A flame a design built waits to be added, as with createObject's
+                // `add: false`; one that was in the game and left it is dropped.
+                if (!flame._pending)
+                    this._drop(flame);
                 continue;
             }
+            flame._pending = false;
             if (flame._target && !alive.has(flame._target)) {
                 flame._target = null;
                 void flame.extinguish(250);
@@ -159,6 +200,32 @@ export class Fire {
                 this.remove(flame);
         }
     }
+    /**
+     * Builds a flame placed in a design, with the look its options give it over
+     * the module's defaults, never the fire's own look. The game adds it.
+     *
+     * @internal
+     */
+    _fromDesign(obj) {
+        const kind = obj.kind;
+        checkKind(kind);
+        const options = (obj.options ?? {});
+        const spec = KINDS[kind];
+        const flame = new Flame(this, kind, {
+            size: options.size,
+            intensity: options.intensity,
+            light: options.light,
+            palette: options.palette ?? "fire",
+            style: options.style ?? "soft",
+            smoke: options.smoke ?? spec.smoke,
+            sparks: options.sparks ?? spec.sparks,
+            smokeColor: options.smokeColor ?? DEFAULT_SMOKE,
+        });
+        flame._pending = true;
+        flame._prewarm = true;
+        this._flames.push(flame);
+        return flame;
+    }
     /** @internal */
     _add(flame) {
         this._flames.push(flame);
@@ -210,6 +277,10 @@ export class Flame extends DrawSprite {
         this._expiresIn = Infinity;
         /** @internal No more particles are emitted; the flame is removed once the last one is gone. */
         this._out = false;
+        /** @internal Built from a design and not yet seen in the game. */
+        this._pending = false;
+        /** @internal Burns for a moment before its first frame, as a flame placed in a design does. */
+        this._prewarm = false;
         /** @internal */
         this._tween = null;
         /** @internal */
@@ -276,6 +347,22 @@ export class Flame extends DrawSprite {
     get target() {
         return this._target;
     }
+    /**
+     * Makes the flame follow `sprite` every frame, keeping the offset it has
+     * from it now, as a flame placed over a sprite in a design keeps where the
+     * creator put it. It hides with the sprite and goes out when the sprite is
+     * destroyed. `null` stops following and leaves the flame where it is.
+     */
+    follow(sprite) {
+        if (sprite === null) {
+            this._target = null;
+            return;
+        }
+        this._target = sprite;
+        this._offsetX = this.x - sprite.x;
+        this._offsetY = this.y - sprite.y;
+        this._expiresIn = Infinity;
+    }
     /**
      * Changes the intensity over `ms` milliseconds.
      * @returns A promise that resolves when it gets there, or when another change replaces it.
@@ -312,8 +399,20 @@ export class Flame extends DrawSprite {
         // the surface's center is above it.
         return this.height / 2 - this._baseY;
     }
+    /** @internal */
+    _editorBox() {
+        const spec = this._spec;
+        return { cx: this.x, cy: this.y - spec.boxRise * this.size, w: spec.boxWidth * this.size, h: spec.boxHeight * this.size };
+    }
     /** @internal Called by the fire once per frame. */
     _advance(dt) {
+        if (this._prewarm) {
+            // Placed where the design says only once the game has applied its
+            // position, so its burning is caught up on its first frame.
+            this._prewarm = false;
+            for (let t = 0; t < PREWARM_SECONDS; t += PREWARM_STEP)
+                this._advance(PREWARM_STEP);
+        }
         this._time += dt;
         this._advanceTween(dt);
         this._goOutWhenDown();

package/dist/minimo-format.d.ts

@@ -118,11 +118,12 @@ export interface AssetFile {
  */
 export declare function parseAssetFile(json: unknown): AssetFile;
 /**
- * The built-in type of a design object. Each maps to one runtime class:
+ * The type of a design object. Each built-in type maps to one runtime class:
  * `image` to `ImageSprite`, `emoji` to `EmojiSprite`, `text` to `TextSprite`,
- * and `background` to `BackgroundLayer`.
+ * and `background` to `BackgroundLayer`. A `module` object is built by the
+ * optional module it names, such as a `Flame` by the `fire` module.
  */
-export type DesignObjectType = "image" | "emoji" | "text" | "background";
+export type DesignObjectType = "image" | "emoji" | "text" | "background" | "module";
 /**
  * The properties every design object has, whatever its type.
  *
@@ -301,18 +302,45 @@ export interface DesignBackground extends DesignObjectBase {
     /** How the image fits its rectangle. Default: `"cover"`. */
     fit?: "none" | "stretch" | "contain" | "cover";
 }
+/**
+ * An object of an optional module in a design file, such as a torch of the
+ * `fire` module. It names its module and its kind, and the module builds it,
+ * so the scene creates the module, such as `new Fire(game)`, before creating
+ * the design's objects. A design holding one is version 3.
+ *
+ * Each module takes only some of the sprite properties and its own
+ * `options`, both listed in {@link designModules}; anything else about the
+ * object, such as what it does while the game plays, is set in code. The
+ * kinds a module places and its options are documented in that module's API.
+ *
+ * @example
+ * ```json
+ * { "id": "3e7b1c9a-5d2f-4a8e-b0c6-9f1d2e4a7b35", "name": "left-torch", "type": "module", "module": "fire", "kind": "torch", "x": 120, "y": 200, "options": { "size": 28 } }
+ * ```
+ */
+export interface DesignModule extends DesignSpriteBase {
+    /** Always `"module"`. */
+    type: "module";
+    /** Required. The module that builds the object, such as `"fire"`: a key of {@link designModules}. */
+    module: string;
+    /** Required. What the module builds, such as `"torch"`: one of its `kinds` in {@link designModules}. */
+    kind: string;
+    /** The module's own settings for the object, such as `{ "size": 28 }`. Default: `{}`. */
+    options?: Record<string, unknown>;
+}
 /** Any object of a design file. Its `type` says which. */
-export type DesignObject = DesignImage | DesignEmoji | DesignText | DesignBackground;
+export type DesignObject = DesignImage | DesignEmoji | DesignText | DesignBackground | DesignModule;
 /**
  * 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.
+ * {@link DesignFileV2}; a design holding objects of an optional module, with
+ * or without pages, is a {@link DesignFileV3}. All three are current: a
+ * design is written in the lowest version that holds it, so it also loads in
+ * an older MinimoJS whenever it can.
  */
-export type DesignFile = DesignFileV1 | DesignFileV2;
+export type DesignFile = DesignFileV1 | DesignFileV2 | DesignFileV3;
 /**
  * A design file without pages: one flat list of objects.
  *
@@ -366,7 +394,35 @@ export interface DesignFileV2 {
     /** The pages, at least one, in file order. */
     pages: DesignPage[];
 }
-/** One page of a {@link DesignFileV2}: a named group of the design's objects. */
+/**
+ * A design file holding objects of an optional module, {@link DesignModule}.
+ * Like the earlier versions, it has either a flat list of `objects` or
+ * `pages`, never both; it is version 3 only because an engine older than
+ * module objects cannot read it.
+ *
+ * @example
+ * ```json
+ * {
+ *   "format": "minimo-design",
+ *   "version": 3,
+ *   "objects": [
+ *     { "id": "6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27", "type": "background", "imageKey": "dungeon" },
+ *     { "id": "3e7b1c9a-5d2f-4a8e-b0c6-9f1d2e4a7b35", "name": "left-torch", "type": "module", "module": "fire", "kind": "torch", "x": 120, "y": 200 }
+ *   ]
+ * }
+ * ```
+ */
+export interface DesignFileV3 {
+    /** Always `"minimo-design"`. */
+    format: "minimo-design";
+    /** `3`: the design holds objects of an optional module. */
+    version: 3;
+    /** The objects of a design without pages, in file order. Present exactly when `pages` is not. */
+    objects?: DesignObject[];
+    /** The pages of a design divided into pages, in file order. Present exactly when `objects` is not. */
+    pages?: DesignPage[];
+}
+/** One page of a design file with pages: 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
@@ -405,7 +461,8 @@ export interface DesignProperty {
     readonly required: boolean;
     /**
      * The runtime object's value when the file omits the property.
-     * `undefined` for a required property and for `name`.
+     * `undefined` for a required property, for `name`, and for a module option
+     * whose default depends on the object's kind.
      */
     readonly default: unknown;
 }
@@ -414,9 +471,11 @@ export interface DesignProperty {
  * with its JSON type, whether it is required, and its default.
  *
  * It is the runtime form of {@link DesignImage}, {@link DesignEmoji},
- * {@link DesignText}, and {@link DesignBackground}, which the compiler checks
- * it against, for tools that cannot read TypeScript types, such as an
- * editor's property panel. `new Design(json)` validates objects with it.
+ * {@link DesignText}, {@link DesignBackground}, and {@link DesignModule},
+ * which the compiler checks it against, for tools that cannot read TypeScript
+ * types, such as an editor's property panel. `new Design(json)` validates
+ * objects with it. A `module` object takes only the properties its module
+ * lists in {@link designModules}.
  *
  * @example
  * ```ts
@@ -426,6 +485,62 @@ export interface DesignProperty {
  * ```
  */
 export declare const designObjectProperties: Readonly<Record<DesignObjectType, readonly DesignProperty[]>>;
+/** One of a module's own options, as a {@link DesignModule}'s `options` holds it. */
+export interface DesignModuleOption extends DesignProperty {
+    /** The smallest number accepted; `null` when there is no lower bound or the option is not a number. */
+    readonly min: number | null;
+    /** The largest number accepted; `null` when there is no upper bound or the option is not a number. */
+    readonly max: number | null;
+}
+/**
+ * What a design may hold of one optional module, for the engine that
+ * validates designs and for tools such as an editor. See {@link designModules}.
+ */
+export interface DesignModuleSchema {
+    /** The module's id, as a {@link DesignModule}'s `module` names it, such as `"fire"`. */
+    readonly module: string;
+    /** The module's file, next to `minimo.js`, such as `"minimo-fire.js"`. */
+    readonly file: string;
+    /**
+     * The class the module exports, which a scene creates with
+     * `new Class(game)` before creating the design's objects, and whose
+     * `update(dt)` advances them, such as `"Fire"`.
+     */
+    readonly className: string;
+    /** The kinds a design can place, such as `"torch"`. The module makes any other kind in code only. */
+    readonly kinds: readonly string[];
+    /**
+     * The sprite properties of {@link DesignSpriteBase} a design may set on the
+     * module's objects, besides `name`, `tags`, and `data`, which every object takes.
+     */
+    readonly properties: readonly string[];
+    /** The module's own options, which `options` may hold. */
+    readonly options: readonly DesignModuleOption[];
+    /**
+     * The number option that sets how big an object is, which an editor's
+     * scale handle changes, such as `"size"`; `null` when a design does not
+     * size the module's objects.
+     */
+    readonly sizeOption: string | null;
+}
+/**
+ * The optional modules whose objects a design can hold, by id, with the kinds
+ * each places, the sprite properties and options it takes, and how a tool
+ * loads it. A design object of any other module, kind, property, or option is
+ * refused: what a design does not hold is set in code.
+ *
+ * A design holds how an object looks when its screen opens. What the game
+ * changes while it plays, such as a flame going out or a die's roll, is the
+ * module's API, used in code on the object the design created.
+ *
+ * @example
+ * ```ts
+ * for (const [id, schema] of Object.entries(designModules)) {
+ *   console.log(id, schema.kinds, schema.options.map((option) => option.name));
+ * }
+ * ```
+ */
+export declare const designModules: Readonly<Record<string, DesignModuleSchema>>;
 /**
  * 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
@@ -478,8 +593,10 @@ 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,
-     * a `data` that is not a JSON object, and a page without a UUID `id` or with
-     * a missing, padded, or repeated `name`.
+     * a `data` that is not a JSON object, a page without a UUID `id` or with
+     * a missing, padded, or repeated `name`, and a `module` object in a design
+     * older than version 3 or with a module, kind, property, or option that
+     * {@link designModules} does not list.
      *
      * @param json - The content of a `*.design.json` file. See {@link DesignFile}.
      */

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 = 2;
+const DESIGN_FILE_VERSION = 3;
 function spec(type, defaultValue) {
     return { type, nullable: false, values: null, required: false, default: defaultValue };
 }
@@ -188,6 +188,12 @@ const BACKGROUND_SPECS = {
     fit: oneOf(["none", "stretch", "contain", "cover"], "cover"),
     ...DATA,
 };
+const MODULE_SPECS = {
+    module: requiredString(),
+    kind: requiredString(),
+    options: spec("object", {}),
+    ...SPRITE_SPECS,
+};
 // `any`: each spec has its own value type, which no longer matters once checked.
 function describeProperties(specs) {
     return Object.freeze(Object.entries(specs).map(([name, { type, nullable, values, required, default: defaultValue }]) => Object.freeze({ name, type, nullable, values, required, default: defaultValue })));
@@ -197,9 +203,11 @@ function describeProperties(specs) {
  * with its JSON type, whether it is required, and its default.
  *
  * It is the runtime form of {@link DesignImage}, {@link DesignEmoji},
- * {@link DesignText}, and {@link DesignBackground}, which the compiler checks
- * it against, for tools that cannot read TypeScript types, such as an
- * editor's property panel. `new Design(json)` validates objects with it.
+ * {@link DesignText}, {@link DesignBackground}, and {@link DesignModule},
+ * which the compiler checks it against, for tools that cannot read TypeScript
+ * types, such as an editor's property panel. `new Design(json)` validates
+ * objects with it. A `module` object takes only the properties its module
+ * lists in {@link designModules}.
  *
  * @example
  * ```ts
@@ -213,10 +221,113 @@ export const designObjectProperties = Object.freeze({
     emoji: describeProperties(EMOJI_SPECS),
     text: describeProperties(TEXT_SPECS),
     background: describeProperties(BACKGROUND_SPECS),
+    module: describeProperties(MODULE_SPECS),
+});
+function option(name, type, defaultValue, { values = null, min = null, max = null } = {}) {
+    return Object.freeze({ name, type, nullable: false, values, required: false, default: defaultValue, min, max });
+}
+function moduleSchema(schema) {
+    return Object.freeze({
+        ...schema,
+        kinds: Object.freeze([...schema.kinds]),
+        properties: Object.freeze([...schema.properties]),
+        options: Object.freeze([...schema.options]),
+    });
+}
+/**
+ * The optional modules whose objects a design can hold, by id, with the kinds
+ * each places, the sprite properties and options it takes, and how a tool
+ * loads it. A design object of any other module, kind, property, or option is
+ * refused: what a design does not hold is set in code.
+ *
+ * A design holds how an object looks when its screen opens. What the game
+ * changes while it plays, such as a flame going out or a die's roll, is the
+ * module's API, used in code on the object the design created.
+ *
+ * @example
+ * ```ts
+ * for (const [id, schema] of Object.entries(designModules)) {
+ *   console.log(id, schema.kinds, schema.options.map((option) => option.name));
+ * }
+ * ```
+ */
+export const designModules = Object.freeze({
+    fire: moduleSchema({
+        module: "fire",
+        file: "minimo-fire.js",
+        className: "Fire",
+        kinds: ["torch", "campfire", "burning", "trail"],
+        // A flame is neither rotated nor scaled, since its particles are placed in
+        // the world: its `size` resizes it.
+        properties: ["x", "y", "alpha", "visible", "layer", "ignoreScroll", "bodyWidth", "bodyHeight", "bodyOffsetX", "bodyOffsetY"],
+        options: [
+            option("size", "number", 32, { min: 4 }),
+            option("intensity", "number", 1, { min: 0, max: 1 }),
+            option("palette", "string", "fire", { values: ["fire", "blue", "green", "purple"] }),
+            option("style", "string", "soft", { values: ["soft", "pixel"] }),
+            option("smoke", "number", undefined, { min: 0, max: 1 }),
+            option("sparks", "number", undefined, { min: 0, max: 1 }),
+            option("smokeColor", "string", "#4a4440"),
+            option("light", "boolean", undefined),
+        ],
+        sizeOption: "size",
+    }),
+    dice: moduleSchema({
+        module: "dice",
+        file: "minimo-dice.js",
+        className: "Dice",
+        kinds: ["d4", "d6", "d8", "d10", "d12", "d20"],
+        // A design places a die; its look, its size, and its value are the game's.
+        properties: ["x", "y"],
+        options: [],
+        sizeOption: null,
+    }),
 });
+/** The properties every module object takes, whatever its module. */
+const MODULE_OBJECT_FIELDS = new Set(["id", "type", "module", "kind", "options", "name", "tags", "data"]);
+/** Checks a module object, already checked as a `module`, against its module's schema. */
+function checkModuleObject(object, label, fail) {
+    const quoted = (names) => names.map((name) => `"${name}"`).join(", ");
+    const moduleId = object.module;
+    const schema = Object.prototype.hasOwnProperty.call(designModules, moduleId) ? designModules[moduleId] : undefined;
+    if (schema === undefined) {
+        throw fail(`${label} belongs to the module "${moduleId}", whose objects a design cannot hold. The modules a design can hold objects of are ${quoted(Object.keys(designModules))}.`);
+    }
+    const kind = object.kind;
+    if (!schema.kinds.includes(kind)) {
+        throw fail(`${label} has the kind "${kind}", which a design cannot place. A "${moduleId}" object is one of ${quoted(schema.kinds)}; anything else the module makes is made in code.`);
+    }
+    for (const field of Object.keys(object)) {
+        if (MODULE_OBJECT_FIELDS.has(field) || schema.properties.includes(field))
+            continue;
+        throw fail(`${label} sets "${field}", which a "${moduleId}" object in a design does not take. It takes ${quoted(schema.properties)}; set anything else in code.`);
+    }
+    const options = (object.options ?? {});
+    for (const [name, value] of Object.entries(options)) {
+        const spec = schema.options.find((candidate) => candidate.name === name);
+        if (spec === undefined) {
+            const known = schema.options.length === 0 ? "takes no options" : `takes the options ${quoted(schema.options.map((candidate) => candidate.name))}`;
+            throw fail(`${label} has the option "${name}", which a "${moduleId}" object in a design does not take. It ${known}; set anything else in code.`);
+        }
+        const inRange = typeof value !== "number" || ((spec.min === null || value >= spec.min) && (spec.max === null || value <= spec.max));
+        if (!isValidValue(value, spec) || !inRange) {
+            throw fail(`${label} has the option "${name}" set to ${describe(value)}, but it must be ${describeExpected(spec)}${describeRange(spec)}.`);
+        }
+    }
+}
+function describeRange(option) {
+    if (option.min !== null && option.max !== null)
+        return ` from ${option.min} to ${option.max}`;
+    if (option.min !== null)
+        return ` of at least ${option.min}`;
+    if (option.max !== null)
+        return ` of at most ${option.max}`;
+    return "";
+}
 const DESIGN_FILE_FIELDS = {
     1: new Set(["format", "version", "objects"]),
     2: new Set(["format", "version", "pages"]),
+    3: new Set(["format", "version", "objects", "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;
@@ -265,6 +376,8 @@ export function parseDesignObject(json, where, kind = "design object") {
             throw fail(`${label} must have "${property.name}", which every "${type}" object requires.`);
         }
     }
+    if (type === "module")
+        checkModuleObject(copy, label, fail);
     return copy;
 }
 function isValidValue(value, property) {
@@ -322,14 +435,18 @@ 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.`);
     }
-    // Both versions are current, so neither is migrated: version 1 is a design
-    // without pages, and version 2 one divided into pages.
+    // Every version is current, so none is migrated: version 1 is a design
+    // without pages, version 2 one divided into pages, and version 3 either,
+    // holding objects of an optional module.
     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}`);
         }
     }
+    if (version === 3 && "objects" in json === "pages" in json) {
+        throw fail(`a version 3 design has either "objects" or "pages", and this one has ${"objects" in json ? "both" : "neither"}.`);
+    }
     // An object's id is unique in the whole file, across pages.
     const whereById = new Map();
     const parseObjects = (entries, where) => {
@@ -339,6 +456,9 @@ function parseDesignFile(json) {
         return entries.map((entry, index) => {
             const at = `${where === "" ? "" : `${where}.`}objects[${index}]`;
             const object = parseDesignObject(entry, at, "design");
+            if (object.type === "module" && version < 3) {
+                throw fail(`${at} is a "module" object, which only a design with "version" 3 holds, so that an older MinimoJS refuses the design by its version.`);
+            }
             const id = object.id.toLowerCase();
             const first = whereById.get(id);
             if (first !== undefined) {
@@ -351,6 +471,9 @@ function parseDesignFile(json) {
     if (version === 1) {
         return { format: DESIGN_FILE_FORMAT, version: 1, objects: parseObjects(json.objects, "") };
     }
+    if (version === 3 && "objects" in json) {
+        return { format: DESIGN_FILE_FORMAT, version: 3, objects: parseObjects(json.objects, "") };
+    }
     if (!Array.isArray(json.pages)) {
         throw fail(`"pages" must be a list, found ${describe(json.pages)}.`);
     }
@@ -390,7 +513,7 @@ function parseDesignFile(json) {
         pageIndexByName.set(name, index);
         return { id, name, objects: parseObjects(entry.objects, where) };
     });
-    return { format: DESIGN_FILE_FORMAT, version: 2, pages };
+    return version === 3 ? { format: DESIGN_FILE_FORMAT, version: 3, pages } : { format: DESIGN_FILE_FORMAT, version: 2, pages };
 }
 /**
  * Returns the first item `match` accepts, in order, or throws an error saying
@@ -447,20 +570,23 @@ 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,
-     * a `data` that is not a JSON object, and a page without a UUID `id` or with
-     * a missing, padded, or repeated `name`.
+     * a `data` that is not a JSON object, a page without a UUID `id` or with
+     * a missing, padded, or repeated `name`, and a `module` object in a design
+     * older than version 3 or with a module, kind, property, or option that
+     * {@link designModules} does not list.
      *
      * @param json - The content of a `*.design.json` file. See {@link DesignFile}.
      */
     constructor(json) {
         const file = parseDesignFile(json);
-        if (file.version === 1) {
+        const pages = "pages" in file ? file.pages : undefined;
+        if (pages === undefined) {
             this.pages = Object.freeze([]);
-            this.objects = Object.freeze(file.objects);
+            this.objects = Object.freeze(("objects" in file ? file.objects : undefined) ?? []);
         }
         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));
+            this.pages = Object.freeze(pages.map((page) => Object.freeze({ ...page, objects: Object.freeze(page.objects) })));
+            this.objects = Object.freeze(pages.flatMap((page) => page.objects));
         }
     }
     /**

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, DesignFileV1, DesignFileV2, DesignImage, DesignObject, DesignObjectBase, DesignObjectType, DesignPage, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, UnknownAsset, } from "./minimo-format.js";
+export type { AssetFile, DesignBackground, DesignEmoji, DesignFile, DesignFileV1, DesignFileV2, DesignFileV3, DesignImage, DesignModule, DesignObject, DesignObjectBase, DesignObjectType, DesignPage, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, UnknownAsset, } from "./minimo-format.js";
 /**
  * Optional tuning values for {@link Game.animateExplode}.
  *
@@ -1655,6 +1655,12 @@ export declare class Game {
      * its tags. Then every property the data holds is applied, including
      * `name`, `tags`, and a copy of `data`.
      *
+     * A `module` object is built by its module, such as a `Flame` by the
+     * `fire` module, which the scene must have created first, such as with
+     * `new Fire(game)` in `onCreate()`; otherwise the creation throws an error
+     * naming the module. Tag builders do not apply to it, and its tags are added
+     * to those the module gives it.
+     *
      * 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.
@@ -1727,6 +1733,7 @@ export declare class Game {
      *   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()`.
+     * - A `module` object is always built by its module, never by a builder.
      *
      * @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.

package/dist/minimo.js

@@ -22,7 +22,7 @@ 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";
+import { Design, designModules, findFirst, parseAssetFile, parseDesignObject } from "./minimo-format.js";
 export { Design, parseAssetFile } from "./minimo-format.js";
 export { SoundPlayback } from "./internal/SoundSystem.js";
 /** How long a scene may load before it dims and its progress ring appears, so a fast load shows neither. */
@@ -294,6 +294,17 @@ export class Sprite {
         const safeScale = Number.isFinite(this.scale) ? this.scale : 1;
         return this.renderY + this.bodyOffsetY * Math.max(0, safeScale);
     }
+    /**
+     * The box, in world space, that a design editor selects and aligns this
+     * sprite by, when it is not the sprite's own: a module's object whose
+     * surface is larger than what the player sees, such as a flame with room
+     * for its glow, reports the visible part. `null` uses the sprite's bounds.
+     *
+     * @internal
+     */
+    _editorBox() {
+        return null;
+    }
     getAnchorOffsetX() {
         return 0;
     }
@@ -1376,6 +1387,7 @@ export class Game {
         /** @internal */ this._onCreate = null;
         /** @internal */ this._currentScene = null;
         /** @internal */ this._buildersByTag = new Map();
+        /** @internal */ this._moduleBuilders = new Map();
         /**
          * Horizontal scroll offset of the world camera, in pixels.
          * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
@@ -1839,6 +1851,12 @@ export class Game {
      * its tags. Then every property the data holds is applied, including
      * `name`, `tags`, and a copy of `data`.
      *
+     * A `module` object is built by its module, such as a `Flame` by the
+     * `fire` module, which the scene must have created first, such as with
+     * `new Fire(game)` in `onCreate()`; otherwise the creation throws an error
+     * naming the module. Tag builders do not apply to it, and its tags are added
+     * to those the module gives it.
+     *
      * 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.
@@ -1930,6 +1948,7 @@ export class Game {
      *   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()`.
+     * - A `module` object is always built by its module, never by a builder.
      *
      * @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.
@@ -1966,8 +1985,46 @@ export class Game {
             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.`);
         }
     }
+    /**
+     * Makes {@link Game.createObject} and {@link Game.createObjectList} build
+     * the design's objects of `module` with `builder`. A module calls it when
+     * it is created; the first module created for an id keeps it until
+     * {@link Game.reset} clears it, as it clears builders.
+     *
+     * @internal
+     */
+    _registerDesignModule(module, builder) {
+        if (!this._moduleBuilders.has(module))
+            this._moduleBuilders.set(module, builder);
+    }
+    /** @internal */
+    _buildModuleObject(obj) {
+        const builder = this._moduleBuilders.get(obj.module);
+        if (builder === undefined) {
+            const className = designModules[obj.module]?.className ?? "the module";
+            throw new Error(`MinimoJS: ${describeDesignObject(obj)} is a "${obj.module}" object, but this scene has not created the ${obj.module} module. Create it in the scene's onCreate(), such as with new ${className}(game), before creating the design's objects.`);
+        }
+        const created = builder(obj, this);
+        if (!(created instanceof Sprite)) {
+            throw new Error(`MinimoJS: The ${obj.module} module did not build a sprite for ${describeDesignObject(obj)}.`);
+        }
+        const target = created;
+        for (const [field, value] of Object.entries(obj)) {
+            if (field === "id" || field === "type" || field === "module" || field === "kind" || field === "options")
+                continue;
+            // The module's own tags, such as "fire", stay beside the design's.
+            if (field === "tags") {
+                created.tags = [...new Set([...created.tags, ...value])];
+                continue;
+            }
+            target[field] = value;
+        }
+        return created;
+    }
     /** @internal */
     _buildDesignObject(obj) {
+        if (obj.type === "module")
+            return this._buildModuleObject(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.`);
@@ -3109,6 +3166,7 @@ export class Game {
         this._textSystem.clear();
         this._inputSystem.resetPressedState();
         this._buildersByTag.clear();
+        this._moduleBuilders.clear();
         this.scrollX = 0;
         this.scrollY = 0;
         this._loopSystem.invokeCreate();

package/package.json

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