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

package/dist/internal/AssetSystem.js

@@ -9,6 +9,16 @@ export class AssetSystem {
         this._imageSources = new Map();
         /** @internal */
         this._imageVersions = new Map();
+        /**
+         * The asset file that declared each key, as the object passed to
+         * `loadAssets`. Keys are unique in the whole game, so a key belongs to
+         * exactly one asset file, or to `loadImage` and `createTexture`.
+         *
+         * @internal
+         */
+        this._assetFileByKey = new Map();
+        /** @internal */
+        this._registeredAssetFiles = new WeakSet();
     }
     queueImage(key, src) {
         const safeKey = key.trim();
@@ -19,6 +29,42 @@ export class AssetSystem {
         if (safeSrc.length === 0) {
             throw new Error("MinimoJS: Image sources must be non-empty strings.");
         }
+        this.refuseAssetFileKey(safeKey, "loadImage()");
+        this.enqueueImage(safeKey, safeSrc);
+    }
+    /**
+     * Registers a parsed asset file and queues its images. `source` is the
+     * object the game passed, which identifies the file, so loading the same
+     * file again, as a scene's `onPreload()` does on every entry, only queues
+     * images that are not loaded.
+     *
+     * Every key is checked before anything is queued, so a refused file
+     * registers nothing. Returns `true` the first time a file is registered.
+     */
+    registerAssetFile(file, source) {
+        for (const entry of file.assets) {
+            const owner = this._assetFileByKey.get(entry.key);
+            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.`);
+                }
+            }
+            else if (owner !== source) {
+                throw new Error(`MinimoJS: Asset key "${entry.key}" is declared by two asset files. Keys must be unique in the whole game.`);
+            }
+        }
+        for (const entry of file.assets) {
+            this._assetFileByKey.set(entry.key, source);
+            if (entry.type === "image") {
+                this.enqueueImage(entry.key, entry.src.trim());
+            }
+        }
+        const isFirstRegistration = !this._registeredAssetFiles.has(source);
+        this._registeredAssetFiles.add(source);
+        return isFirstRegistration;
+    }
+    /** @internal */
+    enqueueImage(safeKey, safeSrc) {
         const existingSrc = this._imageSources.get(safeKey);
         if (existingSrc !== undefined && existingSrc !== safeSrc) {
             throw new Error(`MinimoJS: Image key "${safeKey}" is already registered with a different source.`);
@@ -34,6 +80,7 @@ export class AssetSystem {
         if (typeof painter !== "function") {
             throw new Error("MinimoJS: createTexture() requires a painter function.");
         }
+        this.refuseAssetFileKey(safeKey, "createTexture()");
         const canvas = document.createElement("canvas");
         canvas.width = Math.max(1, Math.round(Number.isFinite(width) ? width : 1));
         canvas.height = Math.max(1, Math.round(Number.isFinite(height) ? height : 1));
@@ -116,6 +163,12 @@ export class AssetSystem {
         this._queuedImages.clear();
     }
     /** @internal */
+    refuseAssetFileKey(safeKey, caller) {
+        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.`);
+        }
+    }
+    /** @internal */
     loadImage(src) {
         return new Promise((resolve, reject) => {
             const image = new Image();

package/dist/internal/DesignNamingCheck.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/DesignNamingCheck.js

@@ -0,0 +1,7 @@
+// A compile-time check, with no runtime code, that every property of a design
+// 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
+// declared here as an explicit exception.
+export {};

package/dist/minimo-format.d.ts

@@ -0,0 +1,407 @@
+/**
+ * @module minimojs/format
+ *
+ * The file formats MinimoJS reads: asset files, `*.assets.json`, and design
+ * files, `*.design.json`.
+ *
+ * This module uses no DOM, so tools such as an editor or a validating server
+ * import the same code a game runs: `import { parseAssetFile, Design } from
+ * "minimojs/format"`. Games reach it through `minimo.js`, which re-exports it.
+ */
+/**
+ * An image declared in an asset file, loaded as
+ * `game.loadImage(key, src)` would load it.
+ *
+ * @example
+ * ```json
+ * { "key": "player", "type": "image", "src": "assets/player.png" }
+ * ```
+ */
+export interface ImageAsset {
+    /**
+     * The key sprites and backgrounds use for this image, as in
+     * `new ImageSprite("player")`. Non-empty, with no leading or trailing
+     * spaces, and unique in the whole game: no other entry of any asset file,
+     * of any type, and no `loadImage` or `createTexture` call may use it.
+     */
+    key: string;
+    /** Always `"image"`. */
+    type: "image";
+    /** The image's URL or path, as `game.loadImage(key, src)` takes it. Non-empty. */
+    src: string;
+}
+/**
+ * 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
+ * not drop it, and `game.loadAssets` warns about it and skips it. Its key
+ * still counts toward the game's unique keys.
+ */
+export interface UnknownAsset {
+    /** The entry's key, unique in the whole game like every other. */
+    key: string;
+    /** A type this engine does not support. */
+    type: string;
+    /** The fields of that type, kept unchecked. */
+    [field: string]: unknown;
+}
+/**
+ * The content of an asset file, `*.assets.json`, which declares assets once,
+ * by key, for {@link parseAssetFile} and `game.loadAssets`.
+ *
+ * A game may have any number of asset files, such as `common.assets.json`
+ * and `level3.assets.json`.
+ *
+ * @example
+ * ```json
+ * {
+ *   "format": "minimo-assets",
+ *   "version": 1,
+ *   "assets": [
+ *     { "key": "player", "type": "image", "src": "assets/player.png" },
+ *     { "key": "bat", "type": "image", "src": "assets/bat.png" }
+ *   ]
+ * }
+ * ```
+ */
+export interface AssetFile {
+    /** Always `"minimo-assets"`. */
+    format: "minimo-assets";
+    /** 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 | UnknownAsset)[];
+}
+/**
+ * Validates the content of an asset file and returns a copy of it.
+ *
+ * Parsing is strict. It throws an error naming what is wrong for:
+ * - a value that is not an asset file object, or an unknown field anywhere;
+ * - a `format` other than `"minimo-assets"`;
+ * - a `version` newer than this engine reads, or one that is not a positive integer;
+ * - 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` entry without a non-empty string `src`.
+ *
+ * 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.
+ *
+ * @param json - The parsed JSON of a `*.assets.json` file.
+ *
+ * @example
+ * ```ts
+ * import common from "./common.assets.json" with { type: "json" };
+ * const file = parseAssetFile(common);
+ * ```
+ */
+export declare function parseAssetFile(json: unknown): AssetFile;
+/**
+ * The built-in type of a design object. Each maps to one runtime class:
+ * `image` to `ImageSprite`, `emoji` to `EmojiSprite`, `text` to `TextSprite`,
+ * and `background` to `BackgroundLayer`.
+ */
+export type DesignObjectType = "image" | "emoji" | "text" | "background";
+/**
+ * The properties every design object has, whatever its type.
+ *
+ * Every property of a design object is named as its runtime class names it,
+ * so the same names work in code and in files. A property the file omits
+ * keeps the runtime object's default.
+ */
+export interface DesignObjectBase {
+    /**
+     * Required. A UUID unique in the file, such as
+     * `"6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27"`. Tools use it to select, undo,
+     * and compare objects, and it survives renames. It is the only property
+     * with no runtime counterpart.
+     */
+    id: string;
+    /** Optional name, which may repeat. Becomes `Sprite.name`. */
+    name?: string;
+    /** Tags for grouping and for builders. Becomes `Sprite.tags`. Default: `[]`. */
+    tags?: string[];
+    /**
+     * The game's own values, such as a button's action or an enemy's speed.
+     * Always a JSON object, never a bare number or string. Becomes a copy in
+     * `Sprite.data`. Default: `{}`.
+     */
+    data?: Record<string, unknown>;
+}
+/** The properties of every sprite type: `image`, `emoji`, and `text`. */
+export interface DesignSpriteBase extends DesignObjectBase {
+    /** Horizontal center in world space, in pixels. Default: `0`. */
+    x?: number;
+    /** Vertical center in world space, in pixels. Positive is down. Default: `0`. */
+    y?: number;
+    /** Uniform visual scale. Default: `1`. */
+    scale?: number;
+    /** Rotation in degrees, clockwise. Default: `0`. */
+    rotation?: number;
+    /** Mirrors the sprite left to right. Default: `false`. */
+    flipX?: boolean;
+    /** Mirrors the sprite top to bottom. Default: `false`. */
+    flipY?: boolean;
+    /** Opacity, from `0` to `1`. Default: `1`. */
+    alpha?: number;
+    /** Whether the sprite is drawn. Default: `true`. */
+    visible?: boolean;
+    /** Render order; higher layers draw on top. Default: `0`. */
+    layer?: number;
+    /** CSS color, used by monochrome glyphs and by text. Default: `"#000000"`, and `"#ffffff"` for `text`. */
+    color?: string;
+    /** Draws the sprite in screen space, unaffected by scrolling. Default: `false`. */
+    ignoreScroll?: boolean;
+    /** Whether the engine leaves the sprite where it is, as a static obstacle. Default: `false`. */
+    isStatic?: boolean;
+    /** Horizontal velocity in pixels per second. Default: `0`. */
+    vx?: number;
+    /** Vertical velocity in pixels per second. Default: `0`. */
+    vy?: number;
+    /** Gravity multiplier. Default: `0`, immune to gravity. */
+    gravityScale?: number;
+    /** Width of the collision body in pixels, before scale; `null` uses the sprite's width. Default: `null`. */
+    bodyWidth?: number | null;
+    /** Height of the collision body in pixels, before scale; `null` uses the sprite's height. Default: `null`. */
+    bodyHeight?: number | null;
+    /** Horizontal offset of the body's center from the sprite's center, in pixels, before scale. Default: `0`. */
+    bodyOffsetX?: number;
+    /** Vertical offset of the body's center from the sprite's center, in pixels, before scale. Default: `0`. */
+    bodyOffsetY?: number;
+}
+/**
+ * An `ImageSprite` in a design file.
+ *
+ * @example
+ * ```json
+ * { "id": "a93e51b4-6c0d-4f2a-8b17-3e5d9c2f0a61", "name": "play", "type": "image", "imageKey": "btn-play", "x": 360, "y": 700 }
+ * ```
+ */
+export interface DesignImage extends DesignSpriteBase {
+    /** Always `"image"`. */
+    type: "image";
+    /** Required. The key of an image declared in one of the game's asset files. */
+    imageKey: string;
+}
+/**
+ * An `EmojiSprite` in a design file.
+ *
+ * @example
+ * ```json
+ * { "id": "0b9a7c3e-2d4f-4e61-a8c5-7f1e3d2b6a90", "type": "emoji", "sprite": "⭐", "size": 64, "x": 200, "y": 300 }
+ * ```
+ */
+export interface DesignEmoji extends DesignSpriteBase {
+    /** Always `"emoji"`. */
+    type: "emoji";
+    /** Required. The emoji to draw. */
+    sprite: string;
+    /** Base size in pixels. Default: `32`. */
+    size?: number;
+}
+/**
+ * A `TextSprite` in a design file.
+ *
+ * @example
+ * ```json
+ * { "id": "5c2e8f1a-9b3d-4a7e-b6c0-1d4f8e2a7c35", "type": "text", "text": "GAME OVER", "fontSize": 64, "x": 360, "y": 400 }
+ * ```
+ */
+export interface DesignText extends DesignSpriteBase {
+    /** Always `"text"`. */
+    type: "text";
+    /** Required. The text to draw. */
+    text: string;
+    /** Font size in pixels. Default: `16`. */
+    fontSize?: number;
+    /** CSS font family. Default: `"monospace"`. */
+    fontFamily?: string;
+    /** CSS font weight. Default: `"400"`. */
+    fontWeight?: string;
+    /** Line height as a multiple of the font size. Default: `1.2`. */
+    lineHeight?: number;
+    /** Which edge of the text `x` names. Default: `"center"`. */
+    anchorX?: "left" | "center" | "right";
+    /** Which edge of the text `y` names. Default: `"middle"`. */
+    anchorY?: "top" | "middle" | "bottom";
+    /** Alignment of the lines. Default: `"center"`. */
+    textAlign?: "left" | "right" | "center" | "start" | "end";
+    /** Width at which lines wrap, in pixels; `0` never wraps. Default: `0`. */
+    maxWidth?: number;
+    /** Fixed box width in pixels; `0` fits the text. Default: `0`. */
+    fixedWidth?: number;
+    /** Fixed box height in pixels; `0` fits the text. Default: `0`. */
+    fixedHeight?: number;
+    /** Horizontal padding inside the box, in pixels. Default: `2`. */
+    paddingX?: number;
+    /** Vertical padding inside the box, in pixels. Default: `2`. */
+    paddingY?: number;
+    /** CSS color of the box; `null` draws none. Default: `null`. */
+    backgroundColor?: string | null;
+    /** CSS color of the box's border; `null` draws none. Default: `null`. */
+    borderColor?: string | null;
+    /** Width of the box's border in pixels. Default: `0`. */
+    borderWidth?: number;
+    /** Corner radius of the box in pixels. Default: `0`. */
+    cornerRadius?: number;
+    /** CSS color of the text's outline; `null` draws none. Default: `null`. */
+    strokeColor?: string | null;
+    /** Width of the text's outline in pixels. Default: `0`. */
+    strokeWidth?: number;
+}
+/**
+ * A `BackgroundLayer` in a design file. Unlike sprites, its `x` and `y` are
+ * the top-left corner in screen space.
+ *
+ * @example
+ * ```json
+ * { "id": "6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27", "type": "background", "imageKey": "sky" }
+ * ```
+ */
+export interface DesignBackground extends DesignObjectBase {
+    /** Always `"background"`. */
+    type: "background";
+    /** Required. The key of an image declared in one of the game's asset files. */
+    imageKey: string;
+    /** Left edge in screen space, in pixels. Default: `0`. */
+    x?: number;
+    /** Top edge in screen space, in pixels. Default: `0`. */
+    y?: number;
+    /** Width in pixels; `0` uses the canvas width. Default: `0`. */
+    width?: number;
+    /** Height in pixels; `0` uses the canvas height. Default: `0`. */
+    height?: number;
+    /** Opacity, from `0` to `1`. Default: `1`. */
+    alpha?: number;
+    /** Whether the layer is drawn. Default: `true`. */
+    visible?: boolean;
+    /** Order among background layers; all of them draw behind sprites. Default: `0`. */
+    layer?: number;
+    /** How the image fits its rectangle. Default: `"cover"`. */
+    fit?: "none" | "stretch" | "contain" | "cover";
+}
+/** Any object of a design file. Its `type` says which. */
+export type DesignObject = DesignImage | DesignEmoji | DesignText | DesignBackground;
+/**
+ * The content of a design file, `*.design.json`: a flat list of objects that
+ * a game creates with `game.createObject` and `game.createObjectList`, read
+ * through {@link Design}.
+ *
+ * @example
+ * ```json
+ * {
+ *   "format": "minimo-design",
+ *   "version": 1,
+ *   "objects": [
+ *     { "id": "6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27", "type": "background", "imageKey": "sky" },
+ *     { "id": "a93e51b4-6c0d-4f2a-8b17-3e5d9c2f0a61", "name": "play", "tags": ["button"], "type": "image", "imageKey": "btn-play", "x": 360, "y": 700, "data": { "action": "start" } }
+ *   ]
+ * }
+ * ```
+ */
+export interface DesignFile {
+    /** Always `"minimo-design"`. */
+    format: "minimo-design";
+    /** The version of the file's shape. Version `1` is the only one so far. */
+    version: 1;
+    /** The objects, in file order, which is the order they are created and drawn in. */
+    objects: DesignObject[];
+}
+/**
+ * How one property of a design object is written, for tools that read or edit
+ * designs without the TypeScript types, such as a property panel. See
+ * {@link designObjectProperties}.
+ */
+export interface DesignProperty {
+    /** The property's name, in the file and on the runtime object. */
+    readonly name: string;
+    /**
+     * The JSON type of its value. `"string-list"` is a list of strings, as
+     * `tags`; `"object"` is a JSON object, as `data`.
+     */
+    readonly type: "number" | "string" | "boolean" | "string-list" | "object";
+    /** Whether `null` is accepted besides values of its type, as for `bodyWidth`. */
+    readonly nullable: boolean;
+    /** The only strings accepted, as for `fit`; `null` when any value of its type is. */
+    readonly values: readonly string[] | null;
+    /** Whether every object of its type must have it. A required property has no default. */
+    readonly required: boolean;
+    /**
+     * The runtime object's value when the file omits the property.
+     * `undefined` for a required property and for `name`.
+     */
+    readonly default: unknown;
+}
+/**
+ * Every property each type of design object accepts besides `id` and `type`,
+ * with its JSON type, whether it is required, and its default.
+ *
+ * It is the runtime form of {@link DesignImage}, {@link DesignEmoji},
+ * {@link DesignText}, and {@link DesignBackground}, which the compiler checks
+ * it against, for tools that cannot read TypeScript types, such as an
+ * editor's property panel. `new Design(json)` validates objects with it.
+ *
+ * @example
+ * ```ts
+ * for (const property of designObjectProperties.image) {
+ *   console.log(property.name, property.type, property.default);
+ * }
+ * ```
+ */
+export declare const designObjectProperties: Readonly<Record<DesignObjectType, readonly DesignProperty[]>>;
+/**
+ * The data of a design file, `*.design.json`, validated: its objects and
+ * searches on them. A `Design` needs no game and creates nothing; pass its
+ * objects, or the results of its searches, to `game.createObject` or
+ * `game.createObjectList`. Data alone also serves markers, such as spawn
+ * points, which code reads without creating anything.
+ *
+ * Obtain the file by JSON import. One `Design` can be created any number of
+ * times.
+ *
+ * @example
+ * ```ts
+ * import menuJson from "./menu.design.json" with { type: "json" };
+ *
+ * const menu = new Design(menuJson);
+ *
+ * class MenuScene {
+ *   onCreate() {
+ *     const ui = game.createObjectList(menu.objects);
+ *     this.play = ui.findByName("play");
+ *   }
+ * }
+ * ```
+ */
+export declare class Design {
+    /**
+     * Every object of the design, as object data, in file order.
+     */
+    readonly objects: readonly DesignObject[];
+    /**
+     * Validates a design file's content and keeps a copy of it.
+     *
+     * Parsing is strict. It throws an error naming what is wrong for a value
+     * that is not a design, an unknown field, a `format` other than
+     * `"minimo-design"`, a `version` newer than this engine reads, an object
+     * whose `type` is not one of the built-in types, an `id` that is not a UUID
+     * or is used twice, a value of the wrong type, a missing required property,
+     * and a `data` that is not a JSON object.
+     *
+     * @param json - The content of a `*.design.json` file. See {@link DesignFile}.
+     */
+    constructor(json: unknown);
+    /**
+     * Returns the first object whose `name` is `name`, in file order.
+     * Throws an error naming `name` when there is none.
+     */
+    findByName(name: string): DesignObject;
+    /** Returns every object whose `name` is `name`, in file order; an empty list when there is none. */
+    findAllByName(name: string): DesignObject[];
+    /**
+     * Returns the first object whose `tags` include `tag`, in file order.
+     * Throws an error naming `tag` when there is none.
+     */
+    findByTag(tag: string): DesignObject;
+    /** Returns every object whose `tags` include `tag`, in file order; an empty list when there is none. */
+    findAllByTag(tag: string): DesignObject[];
+}