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

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

@@ -10,10 +10,10 @@
 import { SoundPlayback } from "./internal/SoundSystem.js";
 import type { PlaySoundOptions } from "./internal/SoundSystem.js";
 import type { DesignObject } from "./minimo-format.js";
-export { Design, parseAssetFile } from "./minimo-format.js";
+export { Design, parseAssetFile, parseTextureAtlas, frameKey } 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 { AssetEntry, AssetFile, AtlasAsset, DesignBackground, DesignEmoji, DesignFile, DesignFileV1, DesignFileV2, DesignFileV3, DesignImage, DesignModule, DesignObject, DesignObjectBase, DesignObjectType, DesignOutline, DesignPage, DesignSpriteBase, DesignText, ImageAsset, SoundAsset, SpritesheetAsset, TextureAtlas, TextureFrame, UnknownAsset, } from "./minimo-format.js";
 /**
  * Optional tuning values for {@link Game.animateExplode}.
  *
@@ -1596,6 +1596,17 @@ export declare class Game {
      * - An entry of a type this engine does not support is skipped, with a
      *   console warning naming it, so the game still loads every asset it can.
      *
+     * A `spritesheet` or `atlas` entry loads its image under its key, and its
+     * atlas JSON with it, and once both are in makes each frame an image of its
+     * own, keyed `<key>/<frame>`, such as `"frog/0"` or `"pond/lotus"`. A frame
+     * key works wherever an image key does: {@link ImageSprite}, backgrounds,
+     * designs, and {@link Game.getImage}. A trimmed atlas frame is restored to
+     * its untrimmed size, so it measures and sits as the picture it came from.
+     * A frame key cannot be used by any other image, sound, or texture. A sheet
+     * whose frames cannot be made, such as an atlas that names a rectangle
+     * outside its image, fails with its key, as a missing image does, and the
+     * console says why. See {@link SpritesheetAsset} and {@link AtlasAsset}.
+     *
      * @param assets - The content of a `*.assets.json` file. See {@link AssetFile}.
      *
      * @example

package/dist/minimo.js

@@ -22,8 +22,8 @@ import { TextSystem } from "./internal/TextSystem.js";
 import { TrailSystem } from "./internal/TrailSystem.js";
 import { TransitionSystem } from "./internal/TransitionSystem.js";
 import { TimerSystem } from "./internal/TimerSystem.js";
-import { Design, designModules, findFirst, parseAssetFile, parseDesignObject } from "./minimo-format.js";
-export { Design, parseAssetFile } from "./minimo-format.js";
+import { ASSET_TYPES, Design, designDecorations, designModules, enabledDecorations, findFirst, parseAssetFile, parseDesignObject, } from "./minimo-format.js";
+export { Design, parseAssetFile, parseTextureAtlas, frameKey } 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. */
 const SCENE_LOADING_INDICATOR_DELAY_MS = 250;
@@ -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`
@@ -1766,6 +1777,17 @@ export class Game {
      * - An entry of a type this engine does not support is skipped, with a
      *   console warning naming it, so the game still loads every asset it can.
      *
+     * A `spritesheet` or `atlas` entry loads its image under its key, and its
+     * atlas JSON with it, and once both are in makes each frame an image of its
+     * own, keyed `<key>/<frame>`, such as `"frog/0"` or `"pond/lotus"`. A frame
+     * key works wherever an image key does: {@link ImageSprite}, backgrounds,
+     * designs, and {@link Game.getImage}. A trimmed atlas frame is restored to
+     * its untrimmed size, so it measures and sits as the picture it came from.
+     * A frame key cannot be used by any other image, sound, or texture. A sheet
+     * whose frames cannot be made, such as an atlas that names a rectangle
+     * outside its image, fails with its key, as a missing image does, and the
+     * console says why. See {@link SpritesheetAsset} and {@link AtlasAsset}.
+     *
      * @param assets - The content of a `*.assets.json` file. See {@link AssetFile}.
      *
      * @example
@@ -1784,7 +1806,7 @@ export class Game {
         if (!isFirstLoad)
             return;
         for (const entry of file.assets) {
-            if (entry.type !== "image" && entry.type !== "sound") {
+            if (!ASSET_TYPES.includes(entry.type)) {
                 console.warn(`MinimoJS: Skipped the asset "${entry.key}", whose type "${entry.type}" this version of MinimoJS does not support.`);
             }
         }
@@ -1884,6 +1906,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 +1945,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 +2022,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 +2112,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 +3226,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.41",
+  "version": "1.0.0-alpha.43",
   "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",