minimojs 1.0.0-alpha.41 → 1.0.0-alpha.43

package/dist/internal/AssetSystem.d.ts

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

package/dist/internal/AssetSystem.js

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

package/dist/internal/DesignNamingCheck.js

@@ -2,6 +2,12 @@
 // object, except `id` and `type`, exists on its runtime class under the same
 // name and with a compatible type (X-002). Designs use the runtime's names so
 // agents learn one vocabulary for code and files. The build fails when a
-// property is misnamed; a property that must be named differently would be
+// property is misnamed; a property that must be named differently is
 // declared here as an explicit exception.
+//
+// The one exception is a decoration's properties, `DesignOutline`'s
+// `outlineWidth` and `outlineColor` (X-023). They belong to the optional
+// `outline` module, not to the sprite, which the core never gives an outline
+// of its own; in code they are `outlines.set(sprite, { width, color })`, and
+// the prefix says which module reads them in a file.
 export {};

package/dist/internal/RenderSystem.js

@@ -478,12 +478,26 @@ export class RenderSystem {
             return this.getDrawSurface(sprite);
         }
         const cacheKey = sprite.getRenderCacheKey();
-        const cached = this._surfaceCache.get(cacheKey);
-        if (cached) {
-            this._surfaceCache.delete(cacheKey);
-            this._surfaceCache.set(cacheKey, cached);
+        const effect = sprite._surfaceEffect;
+        if (effect === null)
+            return this.getBaseSurface(sprite, cacheKey);
+        // The effect's result shares the bounded cache with the base surfaces,
+        // under a key of its own, so the base stays as it was for every other
+        // sprite that looks the same.
+        const effectKey = `${cacheKey}\u0000effect:${effect.key}`;
+        const cached = this.takeCachedSurface(effectKey);
+        if (cached)
+            return cached;
+        const surface = effect.apply(this.getBaseSurface(sprite, cacheKey));
+        this._surfaceCache.set(effectKey, surface);
+        this.trimSurfaceCache();
+        return surface;
+    }
+    /** @internal The sprite's own surface, before any effect. */
+    getBaseSurface(sprite, cacheKey) {
+        const cached = this.takeCachedSurface(cacheKey);
+        if (cached)
             return cached;
-        }
         const surface = this.isTextSprite(sprite)
             ? this.createTextSurface(sprite)
             : this.isImageSprite(sprite)
@@ -493,6 +507,15 @@ export class RenderSystem {
         this.trimSurfaceCache();
         return surface;
     }
+    /** @internal A cached surface, marked as the most recently used. */
+    takeCachedSurface(key) {
+        const cached = this._surfaceCache.get(key);
+        if (cached) {
+            this._surfaceCache.delete(key);
+            this._surfaceCache.set(key, cached);
+        }
+        return cached;
+    }
     /** @internal */
     trimSurfaceCache() {
         while (this._surfaceCache.size > RenderSystem.MAX_SURFACE_CACHE_ENTRIES) {

package/dist/minimo-format.d.ts

@@ -51,6 +51,97 @@ export interface SoundAsset {
     /** The audio file's URL or path, as `game.loadSound(key, src)` takes it. Non-empty. */
     src: string;
 }
+/**
+ * A spritesheet declared in an asset file: one image cut into a grid of equal
+ * frames. The image loads under `key`, as an `image` entry's does, and each
+ * frame becomes an image of its own, keyed `<key>/<n>`, numbered from `0`
+ * left to right and top to bottom, such as `"frog/0"` and `"frog/1"`. A frame
+ * key works wherever an image key does: `ImageSprite`, backgrounds, designs,
+ * and `game.getImage`.
+ *
+ * The grid starts at the image's top-left corner, with no margin or spacing;
+ * pixels left over at the right or bottom edge belong to no frame.
+ *
+ * @example
+ * ```json
+ * { "key": "frog", "type": "spritesheet", "src": "assets/frog-frames.png", "frameWidth": 320, "frameHeight": 320 }
+ * ```
+ */
+export interface SpritesheetAsset {
+    /** The key of the whole image, and the prefix of its frames' keys. Unique in the whole game. */
+    key: string;
+    /** Always `"spritesheet"`. */
+    type: "spritesheet";
+    /** The image's URL or path, as `game.loadImage(key, src)` takes it. Non-empty. */
+    src: string;
+    /** Width of every frame in pixels. A positive integer. */
+    frameWidth: number;
+    /** Height of every frame in pixels. A positive integer. */
+    frameHeight: number;
+}
+/**
+ * A texture atlas declared in an asset file: one image holding named frames
+ * of any size, described by a JSON file in the JSON Hash format that
+ * TexturePacker (*JSON (Hash)*) and free-tex-packer (`JsonHash`) export; see
+ * {@link parseTextureAtlas} for what is read from it. The image loads under
+ * `key`, and each frame becomes an image of its own, keyed `<key>/<frame>`
+ * with the frame's name as the packer wrote it, such as `"pond/lotus"`.
+ *
+ * The image is the one `src` names; the JSON's own `meta.image`, the file
+ * name the packer gave the image, is ignored, so the image may be stored
+ * under any name.
+ *
+ * @example
+ * ```json
+ * { "key": "pond", "type": "atlas", "src": "assets/pond.png", "data": "assets/pond.json" }
+ * ```
+ */
+export interface AtlasAsset {
+    /** The key of the whole image, and the prefix of its frames' keys. Unique in the whole game. */
+    key: string;
+    /** Always `"atlas"`. */
+    type: "atlas";
+    /** The image's URL or path, as `game.loadImage(key, src)` takes it. Non-empty. */
+    src: string;
+    /** The URL or path of the atlas JSON, in the JSON Hash format. Non-empty. */
+    data: string;
+}
+/**
+ * One frame of a spritesheet or an atlas: where it is in the image, and the
+ * size of the picture it came from. A frame trimmed of its transparent border
+ * is drawn at `offsetX`, `offsetY` inside a texture of `sourceWidth` by
+ * `sourceHeight`, so a sprite of it is the size of the untrimmed picture and
+ * trimming never moves what it shows.
+ */
+export interface TextureFrame {
+    /** The frame's name, which follows the sheet's key in its image key: `<key>/<name>`. */
+    name: string;
+    /** Left edge of the frame in the image, in pixels. */
+    x: number;
+    /** Top edge of the frame in the image, in pixels. */
+    y: number;
+    /** Width of the frame in the image, in pixels. */
+    width: number;
+    /** Height of the frame in the image, in pixels. */
+    height: number;
+    /** Width of the picture before trimming, the texture's width. */
+    sourceWidth: number;
+    /** Height of the picture before trimming, the texture's height. */
+    sourceHeight: number;
+    /** Where the frame's left edge sits in the untrimmed picture. */
+    offsetX: number;
+    /** Where the frame's top edge sits in the untrimmed picture. */
+    offsetY: number;
+}
+/** A texture atlas, as {@link parseTextureAtlas} reads it from its JSON. */
+export interface TextureAtlas {
+    /** The atlas's frames, in the JSON's order. */
+    frames: TextureFrame[];
+    /** The image size the JSON's `meta.size` states, or `null` when it states none. */
+    imageWidth: number | null;
+    /** The image size the JSON's `meta.size` states, or `null` when it states none. */
+    imageHeight: number | null;
+}
 /**
  * An entry whose `type` this engine does not support, such as one written for
  * a newer engine. It is kept as written, so a tool that saves the file does
@@ -80,7 +171,9 @@ export interface UnknownAsset {
  *   "assets": [
  *     { "key": "player", "type": "image", "src": "assets/player.png" },
  *     { "key": "bat", "type": "image", "src": "assets/bat.png" },
- *     { "key": "jump", "type": "sound", "src": "assets/jump.mp3" }
+ *     { "key": "jump", "type": "sound", "src": "assets/jump.mp3" },
+ *     { "key": "frog", "type": "spritesheet", "src": "assets/frog.png", "frameWidth": 64, "frameHeight": 64 },
+ *     { "key": "pond", "type": "atlas", "src": "assets/pond.png", "data": "assets/pond.json" }
  *   ]
  * }
  * ```
@@ -91,8 +184,12 @@ export interface AssetFile {
     /** The version of the file's shape. Version `1` is the only one so far. */
     version: 1;
     /** The declared assets, in file order. */
-    assets: (ImageAsset | SoundAsset | UnknownAsset)[];
+    assets: AssetEntry[];
 }
+/** One entry of an asset file. */
+export type AssetEntry = ImageAsset | SoundAsset | SpritesheetAsset | AtlasAsset | UnknownAsset;
+/** The entry types this engine loads. */
+export declare const ASSET_TYPES: readonly string[];
 /**
  * Validates the content of an asset file and returns a copy of it.
  *
@@ -103,7 +200,9 @@ export interface AssetFile {
  * - an entry without a string `key` and `type`;
  * - an empty key, or one with leading or trailing spaces;
  * - a key repeated in the file, whatever the types of its entries;
- * - an `image` or `sound` entry without a non-empty string `src`.
+ * - an `image`, `sound`, `spritesheet`, or `atlas` entry without a non-empty string `src`;
+ * - a `spritesheet` whose `frameWidth` or `frameHeight` is not a positive integer;
+ * - an `atlas` without a non-empty string `data`.
  *
  * An entry of a type this engine does not support is kept unchanged, without
  * checking its other fields, so nothing is lost when a tool saves the file.
@@ -117,6 +216,48 @@ export interface AssetFile {
  * ```
  */
 export declare function parseAssetFile(json: unknown): AssetFile;
+/**
+ * The image key of a spritesheet's or an atlas's frame: the sheet's key, a
+ * slash, and the frame's name, such as `"frog/0"` or `"pond/lotus"`.
+ */
+export declare function frameKey(sheetKey: string, frameName: string): string;
+/**
+ * The frames of a spritesheet whose image is `imageWidth` by `imageHeight`
+ * pixels: every whole cell of the grid, numbered from `0` left to right and
+ * top to bottom. Throws when the image holds no whole frame.
+ */
+export declare function spritesheetFrames(sheet: Pick<SpritesheetAsset, "key" | "frameWidth" | "frameHeight">, imageWidth: number, imageHeight: number): TextureFrame[];
+/**
+ * Reads a texture atlas in the JSON Hash format, as TexturePacker
+ * (*JSON (Hash)*) and free-tex-packer (`JsonHash`) export it, and returns its
+ * frames.
+ *
+ * From each entry of `frames` it reads `frame`, the rectangle in the image;
+ * `sourceSize`, the picture's size before trimming; and `spriteSourceSize`,
+ * where the trimmed rectangle sat in it. The last two may be left out for an
+ * untrimmed frame. Other fields, such as `pivot`, `anchor`, `trimmed`, and
+ * the rest of `meta`, are ignored.
+ *
+ * It throws an error naming what is wrong, and which packer setting changes
+ * it, for:
+ * - a value that is not an object with a `frames` object, including the JSON
+ *   Array format, whose `frames` is a list, and multi-image atlases, which
+ *   list `textures`;
+ * - no frames, or a frame name that is empty or has leading or trailing spaces;
+ * - a rotated frame, `"rotated": true`;
+ * - a `meta.scale` other than 1;
+ * - a rectangle that is not made of whole, non-negative pixels, or a trimmed
+ *   rectangle that does not fit in its source size;
+ * - a frame outside the image size `meta.size` states.
+ *
+ * @param json - The parsed atlas JSON.
+ */
+export declare function parseTextureAtlas(json: unknown): TextureAtlas;
+/**
+ * Throws unless every frame lies inside an image of `imageWidth` by
+ * `imageHeight` pixels. `sheet` names the sheet in the error.
+ */
+export declare function checkFramesFitImage(sheet: string, frames: readonly TextureFrame[], imageWidth: number, imageHeight: number): void;
 /**
  * The type of a design object. Each built-in type maps to one runtime class:
  * `image` to `ImageSprite`, `emoji` to `EmojiSprite`, `text` to `TextSprite`,
@@ -191,6 +332,24 @@ export interface DesignSpriteBase extends DesignObjectBase {
     /** Vertical offset of the body's center from the sprite's center, in pixels, before scale. Default: `0`. */
     bodyOffsetY?: number;
 }
+/**
+ * The outline an `image`, `emoji`, or `text` object can have, drawn by the
+ * optional `outline` module around the object's visible shape (X-023). The
+ * scene creates the module, `new Outline(game)`, before creating a design
+ * object with an outline, and a design holding either property is version 3.
+ * See {@link designDecorations}.
+ */
+export interface DesignOutline {
+    /**
+     * Width of the outline in the object's own pixels, before scale, so it
+     * grows with the object; `0` draws none. At most `64`. The outline is drawn
+     * around the object and leaves its size, body, and hit area as they are.
+     * Default: `0`.
+     */
+    outlineWidth?: number;
+    /** CSS color of the outline, which may be translucent, such as `"rgba(0, 0, 0, 0.5)"`. Default: `"#ffffff"`. */
+    outlineColor?: string;
+}
 /**
  * An `ImageSprite` in a design file.
  *
@@ -199,7 +358,7 @@ export interface DesignSpriteBase extends DesignObjectBase {
  * { "id": "a93e51b4-6c0d-4f2a-8b17-3e5d9c2f0a61", "name": "play", "type": "image", "imageKey": "btn-play", "x": 360, "y": 700 }
  * ```
  */
-export interface DesignImage extends DesignSpriteBase {
+export interface DesignImage extends DesignSpriteBase, DesignOutline {
     /** Always `"image"`. */
     type: "image";
     /** Required. The key of an image declared in one of the game's asset files. */
@@ -213,7 +372,7 @@ export interface DesignImage extends DesignSpriteBase {
  * { "id": "0b9a7c3e-2d4f-4e61-a8c5-7f1e3d2b6a90", "type": "emoji", "sprite": "⭐", "size": 64, "x": 200, "y": 300 }
  * ```
  */
-export interface DesignEmoji extends DesignSpriteBase {
+export interface DesignEmoji extends DesignSpriteBase, DesignOutline {
     /** Always `"emoji"`. */
     type: "emoji";
     /** Required. The emoji to draw. */
@@ -229,7 +388,7 @@ export interface DesignEmoji extends DesignSpriteBase {
  * { "id": "5c2e8f1a-9b3d-4a7e-b6c0-1d4f8e2a7c35", "type": "text", "text": "GAME OVER", "fontSize": 64, "x": 360, "y": 400 }
  * ```
  */
-export interface DesignText extends DesignSpriteBase {
+export interface DesignText extends DesignSpriteBase, DesignOutline {
     /** Always `"text"`. */
     type: "text";
     /** Required. The text to draw. */
@@ -335,8 +494,9 @@ export type DesignObject = DesignImage | DesignEmoji | DesignText | DesignBackgr
  * {@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}; a design holding objects of an optional module, with
- * or without pages, is a {@link DesignFileV3}. All three are current: a
+ * {@link DesignFileV2}; a design holding objects of an optional module or
+ * properties of a decoration, such as an outline, 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.
  */
@@ -395,10 +555,11 @@ export interface DesignFileV2 {
     pages: DesignPage[];
 }
 /**
- * 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.
+ * A design file holding objects of an optional module, {@link DesignModule},
+ * or properties of a decoration, such as the {@link DesignOutline} the
+ * `outline` module draws. 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 either cannot read it.
  *
  * @example
  * ```json
@@ -415,7 +576,7 @@ export interface DesignFileV2 {
 export interface DesignFileV3 {
     /** Always `"minimo-design"`. */
     format: "minimo-design";
-    /** `3`: the design holds objects of an optional module. */
+    /** `3`: the design holds objects of an optional module or properties of a decoration. */
     version: 3;
     /** The objects of a design without pages, in file order. Present exactly when `pages` is not. */
     objects?: DesignObject[];
@@ -541,6 +702,55 @@ export interface DesignModuleSchema {
  * ```
  */
 export declare const designModules: Readonly<Record<string, DesignModuleSchema>>;
+/**
+ * What an optional module adds to the objects of a design that are not its
+ * own, such as an outline the `outline` module draws around an image, for the
+ * engine and for tools such as an editor. See {@link designDecorations}.
+ */
+export interface DesignDecorationSchema {
+    /** The module's id, such as `"outline"`. */
+    readonly module: string;
+    /** The module's file, next to `minimo.js`, such as `"minimo-outline.js"`. */
+    readonly file: string;
+    /**
+     * The class the module exports, which a scene creates with
+     * `new Class(game)` before creating a design object that uses it, such as
+     * `"Outline"`.
+     */
+    readonly className: string;
+    /** The types of design object that take the decoration's properties. */
+    readonly types: readonly DesignObjectType[];
+    /**
+     * The properties of those types that belong to the module, as
+     * {@link designObjectProperties} lists them with their types and defaults.
+     * A design holding any of them is version 3.
+     */
+    readonly properties: readonly string[];
+    /**
+     * The number property that turns the decoration on when it is above `0`,
+     * such as `"outlineWidth"`. Only then does creating the object need the
+     * module.
+     */
+    readonly enabledBy: string;
+}
+/**
+ * The optional modules that decorate design objects of the core's types,
+ * by id. Unlike a {@link DesignModule}, a decoration adds no object: it is a
+ * look of an `image`, `emoji`, or `text` object, held in properties of that
+ * object, which the module draws.
+ *
+ * A tool that draws a design creates the module, with `new Class(game)`,
+ * before creating an object whose `enabledBy` property is above `0`.
+ *
+ * @example
+ * ```ts
+ * for (const schema of Object.values(designDecorations)) {
+ *   const used = design.objects.some((object) => (object[schema.enabledBy] ?? 0) > 0);
+ *   if (used) console.log(`${schema.className} from ${schema.file}`);
+ * }
+ * ```
+ */
+export declare const designDecorations: Readonly<Record<string, DesignDecorationSchema>>;
 /**
  * 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
@@ -596,7 +806,8 @@ export declare class Design {
      * 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.
+     * {@link designModules} does not list, and a property of a decoration, such
+     * as `outlineWidth`, in a design older than version 3.
      *
      * @param json - The content of a `*.design.json` file. See {@link DesignFile}.
      */