minimojs 1.0.0-alpha.3 → 1.0.0-alpha.31

package/dist/minimo-format.d.ts

@@ -0,0 +1,429 @@
+/**
+ * @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;
+}
+/**
+ * A sound declared in an asset file, loaded as
+ * `game.loadSound(key, src)` would load it, and played with
+ * `game.playSound(key)`.
+ *
+ * @example
+ * ```json
+ * { "key": "jump", "type": "sound", "src": "assets/jump.mp3" }
+ * ```
+ */
+export interface SoundAsset {
+    /**
+     * The key `game.playSound` uses for this sound. Non-empty, with no leading
+     * or trailing spaces, and unique in the whole game, images included.
+     */
+    key: string;
+    /** Always `"sound"`. */
+    type: "sound";
+    /** The audio file's URL or path, as `game.loadSound(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" },
+ *     { "key": "jump", "type": "sound", "src": "assets/jump.mp3" }
+ *   ]
+ * }
+ * ```
+ */
+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 | SoundAsset | 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` or `sound` 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[];
+}