minimojs 1.0.0-alpha.40 → 1.0.0-alpha.42

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

@@ -191,6 +191,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 +217,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 +231,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 +247,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 +353,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 +414,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 +435,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 +561,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 +665,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}.
      */

package/dist/minimo-format.js

@@ -142,14 +142,20 @@ const SPRITE_SPECS = {
     bodyOffsetY: spec("number", 0),
     ...DATA,
 };
+const OUTLINE_SPECS = {
+    outlineWidth: spec("number", 0),
+    outlineColor: spec("string", "#ffffff"),
+};
 const IMAGE_SPECS = {
     imageKey: requiredString(),
     ...SPRITE_SPECS,
+    ...OUTLINE_SPECS,
 };
 const EMOJI_SPECS = {
     sprite: requiredString(),
     size: spec("number", 32),
     ...SPRITE_SPECS,
+    ...OUTLINE_SPECS,
 };
 const TEXT_SPECS = {
     text: requiredString(),
@@ -173,6 +179,7 @@ const TEXT_SPECS = {
     strokeWidth: spec("number", 0),
     ...SPRITE_SPECS,
     color: spec("string", "#ffffff"),
+    ...OUTLINE_SPECS,
 };
 const BACKGROUND_SPECS = {
     imageKey: requiredString(),
@@ -283,6 +290,62 @@ export const designModules = Object.freeze({
         sizeOption: null,
     }),
 });
+/**
+ * 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 const designDecorations = Object.freeze({
+    outline: Object.freeze({
+        module: "outline",
+        file: "minimo-outline.js",
+        className: "Outline",
+        types: Object.freeze(["image", "emoji", "text"]),
+        properties: Object.freeze(Object.keys(OUTLINE_SPECS)),
+        enabledBy: "outlineWidth",
+    }),
+});
+/**
+ * The first property of `object` that belongs to a decoration, or `null`.
+ *
+ * @internal
+ */
+export function findDecorationProperty(object) {
+    const fields = object;
+    for (const schema of Object.values(designDecorations)) {
+        if (!schema.types.includes(object.type))
+            continue;
+        for (const name of schema.properties) {
+            if (name in fields)
+                return name;
+        }
+    }
+    return null;
+}
+/**
+ * The decorations whose `enabledBy` property is above `0` in `object`.
+ *
+ * @internal
+ */
+export function enabledDecorations(object) {
+    const fields = object;
+    return Object.values(designDecorations).filter((schema) => {
+        const value = fields[schema.enabledBy];
+        return schema.types.includes(object.type) && typeof value === "number" && value > 0;
+    });
+}
 /** 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. */
@@ -437,7 +500,7 @@ function parseDesignFile(json) {
     }
     // 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.
+    // holding objects of an optional module or properties of a decoration.
     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".` : "";
@@ -459,6 +522,12 @@ function parseDesignFile(json) {
             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.`);
             }
+            if (version < 3) {
+                const decorated = findDecorationProperty(object);
+                if (decorated !== null) {
+                    throw fail(`${at} sets "${decorated}", 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) {
@@ -573,7 +642,8 @@ export 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}.
      */

package/dist/minimo-multiplayer.d.ts

@@ -293,7 +293,8 @@ export declare class Room {
  *
  * {@link Multiplayer.lobby} shows the lobby over the game, in HTML: creating a
  * room, joining one by its code, sharing its link, and waiting for the others
- * until the host starts. A player who opens the room's link lands in it.
+ * until the host starts. A player who opened the room's link lands in it as
+ * soon as the game calls it.
  *
  * ```js
  * import { Multiplayer } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo-multiplayer.js";
@@ -309,15 +310,27 @@ export declare class Room {
  * const choice = await room.showResults(); // "rematch" or "leave"
  * ```
  *
- * A game with its own welcome screen asks {@link Multiplayer.pendingRoom}
- * first, so a player who opened a room's link, or reloaded the page in a
- * room, goes straight to it instead of to the welcome screen:
+ * A player who opens a room's link has already chosen to play online and
+ * which room to join. So a game asks {@link Multiplayer.pendingRoom} as soon
+ * as its assets are loaded, before showing anything. When a room is pending,
+ * it skips every screen that only leads to a room or that the host decides,
+ * such as a title screen, menus, playing alone or online, creating or joining,
+ * the mode, the difficulty, the rules, or the level, and shows only the
+ * choices that are the player's own, such as a character or a color, before
+ * {@link Multiplayer.lobby} or after it:
  *
  * ```js
  * const pending = await mp.pendingRoom();
- * if (pending) room = await mp.lobby(); // that room's lobby, or its game in progress
- * else showWelcome();                   // Play online, then mp.lobby() to create or join
+ * if (pending) {
+ *   await chooseCharacter();   // only the player's own choices
+ *   room = await mp.lobby();   // that room's lobby, or its game in progress
+ * } else showWelcome();        // Play online, then mp.lobby() to create or join
  * ```
+ *
+ * What every player must share is the host's choice and travels in the
+ * room's state. A player returning to a room after a reload (`invited` is
+ * false) is asked again only what the game could not keep. When the player
+ * closes the lobby, show the welcome screen.
  */
 export declare class Multiplayer {
     /**

package/dist/minimo-multiplayer.js

@@ -757,7 +757,8 @@ export class Room {
  *
  * {@link Multiplayer.lobby} shows the lobby over the game, in HTML: creating a
  * room, joining one by its code, sharing its link, and waiting for the others
- * until the host starts. A player who opens the room's link lands in it.
+ * until the host starts. A player who opened the room's link lands in it as
+ * soon as the game calls it.
  *
  * ```js
  * import { Multiplayer } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo-multiplayer.js";
@@ -773,15 +774,27 @@ export class Room {
  * const choice = await room.showResults(); // "rematch" or "leave"
  * ```
  *
- * A game with its own welcome screen asks {@link Multiplayer.pendingRoom}
- * first, so a player who opened a room's link, or reloaded the page in a
- * room, goes straight to it instead of to the welcome screen:
+ * A player who opens a room's link has already chosen to play online and
+ * which room to join. So a game asks {@link Multiplayer.pendingRoom} as soon
+ * as its assets are loaded, before showing anything. When a room is pending,
+ * it skips every screen that only leads to a room or that the host decides,
+ * such as a title screen, menus, playing alone or online, creating or joining,
+ * the mode, the difficulty, the rules, or the level, and shows only the
+ * choices that are the player's own, such as a character or a color, before
+ * {@link Multiplayer.lobby} or after it:
  *
  * ```js
  * const pending = await mp.pendingRoom();
- * if (pending) room = await mp.lobby(); // that room's lobby, or its game in progress
- * else showWelcome();                   // Play online, then mp.lobby() to create or join
+ * if (pending) {
+ *   await chooseCharacter();   // only the player's own choices
+ *   room = await mp.lobby();   // that room's lobby, or its game in progress
+ * } else showWelcome();        // Play online, then mp.lobby() to create or join
  * ```
+ *
+ * What every player must share is the host's choice and travels in the
+ * room's state. A player returning to a room after a reload (`invited` is
+ * false) is asked again only what the game could not keep. When the player
+ * closes the lobby, show the welcome screen.
  */
 export class Multiplayer {
     /**

package/dist/minimo-outline.d.ts

@@ -0,0 +1,106 @@
+import { Game, Sprite } from "./minimo.js";
+/** How {@link Outline.set} outlines a sprite. */
+export interface OutlineOptions {
+    /**
+     * Width of the outline in the sprite's own pixels, before
+     * {@link Sprite.scale}, so it grows and shrinks with the sprite. `0`
+     * removes the outline. A width above {@link Outline.MAX_WIDTH} draws that
+     * width.
+     */
+    width: number;
+    /**
+     * CSS color of the outline, such as `"#fff5df"`, which may be translucent,
+     * such as `"rgba(0, 0, 0, 0.5)"`. Default `"#ffffff"`.
+     */
+    color?: string;
+}
+/** The outline a sprite has, as {@link Outline.get} reports it. */
+export interface OutlineStyle {
+    /** Width in the sprite's own pixels, before scale. */
+    readonly width: number;
+    /** CSS color. */
+    readonly color: string;
+}
+/**
+ * Draws a solid outline around the visible shape of image, emoji, and text
+ * sprites, so a character or an answer stands out from what is behind it.
+ *
+ * The outline follows the shape's transparent edges, not its box, and is
+ * part of the sprite's own picture: it moves, turns, flips, scales, fades,
+ * and changes layer with the sprite, and it shows in trails, wipes, and
+ * explosions of it. Only what is drawn grows. The sprite's size, collision
+ * body, the area that takes taps, and its pivot stay as they were.
+ *
+ * Each outline is built once and kept, so moving or turning a sprite costs
+ * nothing more. A new texture, new text, or a new width or color builds it
+ * again. Sprites that look the same share one outline.
+ *
+ * {@link DrawSprite}s, and the sprites made from it such as a flame or a die,
+ * are not outlined: they are redrawn every frame, which would rebuild the
+ * outline every frame.
+ *
+ * Create the module in the scene's `onCreate()`. It needs no `update()`.
+ *
+ * @example
+ * ```ts
+ * import { Outline } from "./minimo-outline.js";
+ *
+ * onCreate() {
+ *   const outlines = new Outline(game);
+ *   const frog = game.add(new ImageSprite(game, "frog", 360, 640));
+ *   outlines.set(frog, { width: 4, color: "#fff5df" });
+ * }
+ * ```
+ *
+ * ## In a design
+ *
+ * An `image`, `emoji`, or `text` object in a design takes an outline through
+ * two properties, which Studio shows among the object's properties:
+ *
+ * - `outlineWidth`: the width in the object's own pixels. `0`, the default,
+ *   draws none.
+ * - `outlineColor`: its CSS color. Default `"#ffffff"`.
+ *
+ * ```json
+ * { "id": "…", "type": "image", "name": "frog", "imageKey": "frog",
+ *   "x": 360, "y": 640, "outlineWidth": 4, "outlineColor": "#fff5df" }
+ * ```
+ *
+ * A design holding either property has `"version": 3`. The outline is a look
+ * of the object, not an object of its own: there is no `module` object for it.
+ * Create the module before the design's objects, or creating an object whose
+ * `outlineWidth` is above `0` throws an error naming it:
+ *
+ * ```ts
+ * onCreate() {
+ *   this.outlines = new Outline(game);
+ *   const screen = game.createObjectList(menu.objects);
+ *   const frog = screen.findByName("frog");
+ *   // Change it while the game plays, such as on the chosen answer:
+ *   this.outlines.set(frog, { width: 6, color: "#ffd84a" });
+ * }
+ * ```
+ */
+export declare class Outline {
+    /** The widest outline drawn, in the sprite's own pixels. */
+    static readonly MAX_WIDTH = 64;
+    /** The game whose sprites it outlines. */
+    readonly game: Game;
+    constructor(game: Game);
+    /**
+     * Outlines `sprite`, or changes its outline. A width of `0` removes it.
+     * @param sprite - An {@link ImageSprite}, {@link EmojiSprite}, or {@link TextSprite}, or a subclass of one.
+     * @param options - The width, and the color, white by default.
+     */
+    set(sprite: Sprite, options: OutlineOptions): void;
+    /**
+     * The outline `sprite` has, or `null` when it has none.
+     * @param sprite - Any sprite.
+     */
+    get(sprite: Sprite): OutlineStyle | null;
+    /**
+     * Removes the outline of `sprite`. Nothing happens when it has none.
+     * @param sprite - Any sprite.
+     */
+    remove(sprite: Sprite): void;
+}

package/dist/minimo-outline.js

@@ -0,0 +1,299 @@
+import { DrawSprite, EmojiSprite, Game, ImageSprite, TextSprite } from "./minimo.js";
+/** The color of an outline whose options name none. */
+const DEFAULT_COLOR = "#ffffff";
+/** A pixel at least this opaque is inside the shape the outline goes around. */
+const INSIDE_ALPHA = 128;
+/**
+ * Draws a solid outline around the visible shape of image, emoji, and text
+ * sprites, so a character or an answer stands out from what is behind it.
+ *
+ * The outline follows the shape's transparent edges, not its box, and is
+ * part of the sprite's own picture: it moves, turns, flips, scales, fades,
+ * and changes layer with the sprite, and it shows in trails, wipes, and
+ * explosions of it. Only what is drawn grows. The sprite's size, collision
+ * body, the area that takes taps, and its pivot stay as they were.
+ *
+ * Each outline is built once and kept, so moving or turning a sprite costs
+ * nothing more. A new texture, new text, or a new width or color builds it
+ * again. Sprites that look the same share one outline.
+ *
+ * {@link DrawSprite}s, and the sprites made from it such as a flame or a die,
+ * are not outlined: they are redrawn every frame, which would rebuild the
+ * outline every frame.
+ *
+ * Create the module in the scene's `onCreate()`. It needs no `update()`.
+ *
+ * @example
+ * ```ts
+ * import { Outline } from "./minimo-outline.js";
+ *
+ * onCreate() {
+ *   const outlines = new Outline(game);
+ *   const frog = game.add(new ImageSprite(game, "frog", 360, 640));
+ *   outlines.set(frog, { width: 4, color: "#fff5df" });
+ * }
+ * ```
+ *
+ * ## In a design
+ *
+ * An `image`, `emoji`, or `text` object in a design takes an outline through
+ * two properties, which Studio shows among the object's properties:
+ *
+ * - `outlineWidth`: the width in the object's own pixels. `0`, the default,
+ *   draws none.
+ * - `outlineColor`: its CSS color. Default `"#ffffff"`.
+ *
+ * ```json
+ * { "id": "…", "type": "image", "name": "frog", "imageKey": "frog",
+ *   "x": 360, "y": 640, "outlineWidth": 4, "outlineColor": "#fff5df" }
+ * ```
+ *
+ * A design holding either property has `"version": 3`. The outline is a look
+ * of the object, not an object of its own: there is no `module` object for it.
+ * Create the module before the design's objects, or creating an object whose
+ * `outlineWidth` is above `0` throws an error naming it:
+ *
+ * ```ts
+ * onCreate() {
+ *   this.outlines = new Outline(game);
+ *   const screen = game.createObjectList(menu.objects);
+ *   const frog = screen.findByName("frog");
+ *   // Change it while the game plays, such as on the chosen answer:
+ *   this.outlines.set(frog, { width: 6, color: "#ffd84a" });
+ * }
+ * ```
+ */
+export class Outline {
+    constructor(game) {
+        if (!(game instanceof Game)) {
+            throw new Error("MinimoJS: new Outline(game) needs the game, such as new Outline(game) in a scene's onCreate().");
+        }
+        this.game = game;
+        game._registerDesignDecoration("outline", (sprite, obj) => this._fromDesign(sprite, obj));
+    }
+    /**
+     * Outlines `sprite`, or changes its outline. A width of `0` removes it.
+     * @param sprite - An {@link ImageSprite}, {@link EmojiSprite}, or {@link TextSprite}, or a subclass of one.
+     * @param options - The width, and the color, white by default.
+     */
+    set(sprite, options) {
+        checkSprite(sprite, "set");
+        if (options === null || typeof options !== "object") {
+            throw new Error("MinimoJS: Outline.set(sprite, options) needs options such as { width: 4, color: \"#ffffff\" }.");
+        }
+        const { width, color = DEFAULT_COLOR } = options;
+        if (typeof width !== "number" || !Number.isFinite(width) || width < 0) {
+            throw new Error(`MinimoJS: An outline's width is a number of pixels of at least 0, found ${String(width)}.`);
+        }
+        if (typeof color !== "string" || color.trim() === "") {
+            throw new Error(`MinimoJS: An outline's color is a CSS color, such as "#ffffff", found ${String(color)}.`);
+        }
+        if (width === 0) {
+            this.remove(sprite);
+            return;
+        }
+        const current = sprite._surfaceEffect;
+        if (current !== null && !(current instanceof OutlineEffect)) {
+            throw new Error("MinimoJS: This sprite already has another module's effect, and a sprite takes one at a time.");
+        }
+        sprite._surfaceEffect = new OutlineEffect(Math.min(width, Outline.MAX_WIDTH), color);
+    }
+    /**
+     * The outline `sprite` has, or `null` when it has none.
+     * @param sprite - Any sprite.
+     */
+    get(sprite) {
+        const effect = sprite?._surfaceEffect;
+        return effect instanceof OutlineEffect ? { width: effect.width, color: effect.color } : null;
+    }
+    /**
+     * Removes the outline of `sprite`. Nothing happens when it has none.
+     * @param sprite - Any sprite.
+     */
+    remove(sprite) {
+        if (sprite?._surfaceEffect instanceof OutlineEffect)
+            sprite._surfaceEffect = null;
+    }
+    /** @internal Applies a design object's outline to the sprite built for it. */
+    _fromDesign(sprite, obj) {
+        const outline = obj;
+        this.set(sprite, { width: outline.outlineWidth ?? 0, color: outline.outlineColor ?? DEFAULT_COLOR });
+    }
+}
+/** The widest outline drawn, in the sprite's own pixels. */
+Outline.MAX_WIDTH = 64;
+function checkSprite(sprite, method) {
+    if (sprite instanceof DrawSprite) {
+        throw new Error(`MinimoJS: Outline.${method}() does not outline a DrawSprite, or a sprite made from one such as a flame or a die: it is redrawn every frame, so its outline would be rebuilt every frame. Outline an ImageSprite, EmojiSprite, or TextSprite.`);
+    }
+    if (!(sprite instanceof ImageSprite || sprite instanceof EmojiSprite || sprite instanceof TextSprite)) {
+        throw new Error(`MinimoJS: Outline.${method}() outlines an ImageSprite, EmojiSprite, or TextSprite, found ${describe(sprite)}.`);
+    }
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "object")
+        return value.constructor?.name ?? "an object";
+    return typeof value;
+}
+/** The outline as the core applies it to a sprite's surface. */
+class OutlineEffect {
+    constructor(width, color) {
+        this.width = width;
+        this.color = color;
+        this.key = `outline:${width}:${color}`;
+    }
+    /**
+     * Returns a new canvas, larger than `base` by the outline's width rounded up
+     * on every side, holding the outline with `base` drawn over it.
+     */
+    apply(base) {
+        const pad = Math.ceil(this.width);
+        const width = base.width + pad * 2;
+        const height = base.height + pad * 2;
+        const mask = createCanvas(width, height);
+        const maskCtx = context(mask);
+        if (!drawDistanceMask(maskCtx, base, pad, this.width)) {
+            drawStampedMask(maskCtx, base, pad, this.width);
+        }
+        // Keep the mask's coverage, painted in the outline's color, so a
+        // translucent color stays as translucent where outlines overlap.
+        maskCtx.globalCompositeOperation = "source-in";
+        maskCtx.fillStyle = this.color;
+        maskCtx.fillRect(0, 0, width, height);
+        const result = createCanvas(width, height);
+        const ctx = context(result);
+        ctx.drawImage(mask, 0, 0);
+        ctx.drawImage(base, pad, pad);
+        return result;
+    }
+}
+function createCanvas(width, height) {
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, width);
+    canvas.height = Math.max(1, height);
+    return canvas;
+}
+function context(canvas) {
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        throw new Error("MinimoJS: Could not acquire an outline rendering context.");
+    return ctx;
+}
+/**
+ * Draws into `ctx` the coverage of an outline `width` pixels wide around the
+ * pixels of `base` at least half opaque, from each pixel's distance to the
+ * nearest of them, so the outline is round and smooth at its edge and faint
+ * haze around an image does not grow one. Returns `false`, having drawn
+ * nothing, when the pixels cannot be read.
+ */
+function drawDistanceMask(ctx, base, pad, width) {
+    const w = ctx.canvas.width;
+    const h = ctx.canvas.height;
+    let pixels;
+    try {
+        ctx.drawImage(base, pad, pad);
+        pixels = ctx.getImageData(0, 0, w, h);
+    }
+    catch {
+        ctx.clearRect(0, 0, w, h);
+        return false;
+    }
+    const source = pixels.data;
+    const distance = new Float64Array(w * h);
+    for (let i = 0; i < w * h; i++) {
+        distance[i] = source[i * 4 + 3] >= INSIDE_ALPHA ? 0 : Infinity;
+    }
+    squaredDistanceTransform(distance, w, h);
+    const out = ctx.createImageData(w, h);
+    const data = out.data;
+    for (let i = 0; i < w * h; i++) {
+        // A pixel next to the shape, one pixel away, is fully covered by a
+        // 1-pixel outline; one diagonal to it partly.
+        const coverage = Math.max(0, Math.min(1, width + 1 - Math.sqrt(distance[i])));
+        data[i * 4 + 3] = Math.round(coverage * 255);
+    }
+    ctx.clearRect(0, 0, w, h);
+    ctx.putImageData(out, 0, 0);
+    return true;
+}
+/**
+ * Turns `grid`, holding `0` inside the shape and `Infinity` outside, into the
+ * squared distance from each cell to the nearest cell inside, by columns and
+ * then by rows (Felzenszwalb and Huttenlocher's exact transform).
+ */
+function squaredDistanceTransform(grid, width, height) {
+    const size = Math.max(width, height);
+    const f = new Float64Array(size);
+    const d = new Float64Array(size);
+    const v = new Int32Array(size);
+    const z = new Float64Array(size + 1);
+    for (let x = 0; x < width; x++) {
+        for (let y = 0; y < height; y++)
+            f[y] = grid[y * width + x];
+        transform1D(f, height, d, v, z);
+        for (let y = 0; y < height; y++)
+            grid[y * width + x] = d[y];
+    }
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++)
+            f[x] = grid[y * width + x];
+        transform1D(f, width, d, v, z);
+        for (let x = 0; x < width; x++)
+            grid[y * width + x] = d[x];
+    }
+}
+function transform1D(f, n, d, v, z) {
+    let k = -1;
+    for (let q = 0; q < n; q++) {
+        if (f[q] === Infinity)
+            continue;
+        if (k < 0) {
+            k = 0;
+            v[0] = q;
+            z[0] = -Infinity;
+            z[1] = Infinity;
+            continue;
+        }
+        let s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+        while (s <= z[k]) {
+            k--;
+            if (k < 0)
+                break;
+            s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+        }
+        k++;
+        v[k] = q;
+        z[k] = k === 0 ? -Infinity : s;
+        z[k + 1] = Infinity;
+    }
+    if (k < 0) {
+        for (let q = 0; q < n; q++)
+            d[q] = Infinity;
+        return;
+    }
+    let j = 0;
+    for (let q = 0; q < n; q++) {
+        while (z[j + 1] < q)
+            j++;
+        const offset = q - v[j];
+        d[q] = offset * offset + f[v[j]];
+    }
+}
+/**
+ * Draws the outline's coverage by stamping `base` around rings of every radius
+ * up to `width`, for an image whose pixels cannot be read, such as one from
+ * another origin. It needs no pixels, but faint haze around an image adds up
+ * into a visible outline.
+ */
+function drawStampedMask(ctx, base, pad, width) {
+    for (let radius = width; radius > 0; radius -= 1) {
+        const steps = Math.max(8, Math.ceil(2 * Math.PI * radius));
+        for (let i = 0; i < steps; i++) {
+            const angle = (i / steps) * Math.PI * 2;
+            ctx.drawImage(base, pad + Math.cos(angle) * radius, pad + Math.sin(angle) * radius);
+        }
+    }
+    ctx.drawImage(base, pad, pad);
+}

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, DesignFileV3, DesignImage, DesignModule, 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, DesignOutline, DesignPage, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, UnknownAsset, } from "./minimo-format.js";
 /**
  * Optional tuning values for {@link Game.animateExplode}.
  *

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, designModules, findFirst, parseAssetFile, parseDesignObject } from "./minimo-format.js";
+import { Design, designDecorations, designModules, enabledDecorations, 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. */
@@ -60,6 +60,14 @@ export class Sprite {
         this.scale = 1;
         /** @internal */
         this._renderData = null;
+        /**
+         * A change an optional module makes to how this sprite looks, such as the
+         * `outline` module's outline, applied to its drawn surface. `null` draws
+         * the surface as it is. See {@link SpriteSurfaceEffect}.
+         *
+         * @internal
+         */
+        this._surfaceEffect = null;
         /**
          * Optional logical body width used by physics helpers and collision checks.
          *
@@ -946,6 +954,8 @@ const DESIGN_OBJECT_CLASSES = {
     text: TextSprite,
     background: BackgroundLayer,
 };
+/** Every property of a design object that belongs to a decoration's module. */
+const DECORATION_PROPERTIES = new Set(Object.values(designDecorations).flatMap((schema) => schema.properties));
 function describeDesignObject(obj) {
     return obj.name === undefined ? `the object ${obj.id}` : `the object "${obj.name}" (${obj.id})`;
 }
@@ -1388,6 +1398,7 @@ export class Game {
         /** @internal */ this._currentScene = null;
         /** @internal */ this._buildersByTag = new Map();
         /** @internal */ this._moduleBuilders = new Map();
+        /** @internal */ this._decorationBuilders = new Map();
         /**
          * Horizontal scroll offset of the world camera, in pixels.
          * The canvas viewport is shifted left by `scrollX` — sprites with higher `x`
@@ -1884,6 +1895,7 @@ export class Game {
         }
         const obj = parseDesignObject(data, "the object", "design object");
         this._assertDesignImageLoaded(obj);
+        this._assertDesignDecorationsReady(obj);
         const created = this._buildDesignObject(obj);
         if (options.add !== false)
             this._addDesignObject(created);
@@ -1922,8 +1934,10 @@ export class Game {
             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)
+        for (const obj of parsed) {
             this._assertDesignImageLoaded(obj);
+            this._assertDesignDecorationsReady(obj);
+        }
         const created = parsed.map((obj) => this._buildDesignObject(obj));
         if (options.add !== false) {
             for (const obj of created)
@@ -1997,6 +2011,31 @@ export class Game {
         if (!this._moduleBuilders.has(module))
             this._moduleBuilders.set(module, builder);
     }
+    /**
+     * Makes {@link Game.createObject} and {@link Game.createObjectList} hand
+     * the design objects that use the decoration `module`, such as an outline,
+     * to `builder` once built. A module calls it when it is created; the first
+     * module created for an id keeps it until {@link Game.reset} clears it.
+     *
+     * @internal
+     */
+    _registerDesignDecoration(module, builder) {
+        if (!this._decorationBuilders.has(module))
+            this._decorationBuilders.set(module, builder);
+    }
+    /**
+     * Checks that every decoration `obj` turns on has its module created, before
+     * anything is built, so a list with one such object creates nothing.
+     *
+     * @internal
+     */
+    _assertDesignDecorationsReady(obj) {
+        for (const schema of enabledDecorations(obj)) {
+            if (this._decorationBuilders.has(schema.module))
+                continue;
+            throw new Error(`MinimoJS: ${describeDesignObject(obj)} sets "${schema.enabledBy}", which the ${schema.module} module draws, but this scene has not created the ${schema.module} module. Create it in the scene's onCreate(), such as with new ${schema.className}(game), before creating the design's objects.`);
+        }
+    }
     /** @internal */
     _buildModuleObject(obj) {
         const builder = this._moduleBuilders.get(obj.module);
@@ -2062,8 +2101,17 @@ export class Game {
                 created.setTexture(value);
                 continue;
             }
+            // A decoration's properties, such as `outlineWidth`, are its module's,
+            // not the sprite's: the module applies them below.
+            if (DECORATION_PROPERTIES.has(field))
+                continue;
             target[field] = value;
         }
+        if (created instanceof Sprite) {
+            for (const schema of enabledDecorations(obj)) {
+                this._decorationBuilders.get(schema.module)?.(created, obj);
+            }
+        }
         return created;
     }
     /** @internal */
@@ -3167,6 +3215,7 @@ export class Game {
         this._inputSystem.resetPressedState();
         this._buildersByTag.clear();
         this._moduleBuilders.clear();
+        this._decorationBuilders.clear();
         this.scrollX = 0;
         this.scrollY = 0;
         this._loopSystem.invokeCreate();

package/package.json

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