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

package/dist/minimo-format.js

@@ -0,0 +1,446 @@
+/**
+ * @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.
+ */
+/** The `format` value of every asset file. */
+const ASSET_FILE_FORMAT = "minimo-assets";
+/** The newest asset file `version` this engine reads. */
+const ASSET_FILE_VERSION = 1;
+const ASSET_FILE_FIELDS = new Set(["format", "version", "assets"]);
+const IMAGE_ASSET_FIELDS = new Set(["key", "type", "src"]);
+/**
+ * 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 function parseAssetFile(json) {
+    if (!isPlainObject(json)) {
+        throw assetError("an asset file must be a JSON object.");
+    }
+    rejectUnknownFields(json, ASSET_FILE_FIELDS, "the asset file");
+    if (json.format !== ASSET_FILE_FORMAT) {
+        throw assetError(`"format" must be "${ASSET_FILE_FORMAT}", found ${describe(json.format)}.`);
+    }
+    const version = json.version;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        throw assetError(`"version" must be a positive integer, found ${describe(version)}.`);
+    }
+    if (version > ASSET_FILE_VERSION) {
+        throw assetError(`"version" ${version} is newer than this engine reads (${ASSET_FILE_VERSION}). Use a newer MinimoJS.`);
+    }
+    if (!Array.isArray(json.assets)) {
+        throw assetError(`"assets" must be a list, found ${describe(json.assets)}.`);
+    }
+    const assets = [];
+    const indexByKey = new Map();
+    json.assets.forEach((entry, index) => {
+        const where = `assets[${index}]`;
+        if (!isPlainObject(entry)) {
+            throw assetError(`${where} must be an object, found ${describe(entry)}.`);
+        }
+        const key = entry.key;
+        if (typeof key !== "string") {
+            throw assetError(`${where} must have a string "key", found ${describe(key)}.`);
+        }
+        if (key.length === 0) {
+            throw assetError(`${where} has an empty "key".`);
+        }
+        if (key.trim() !== key) {
+            throw assetError(`${where} has the key "${key}", with leading or trailing spaces.`);
+        }
+        const firstIndex = indexByKey.get(key);
+        if (firstIndex !== undefined) {
+            throw assetError(`the key "${key}" is declared twice, in assets[${firstIndex}] and ${where}.`);
+        }
+        indexByKey.set(key, index);
+        const type = entry.type;
+        if (typeof type !== "string" || type.length === 0) {
+            throw assetError(`${where} ("${key}") must have a string "type", found ${describe(type)}.`);
+        }
+        if (type === "image") {
+            rejectUnknownFields(entry, IMAGE_ASSET_FIELDS, `${where} ("${key}")`);
+            const src = entry.src;
+            if (typeof src !== "string" || src.trim().length === 0) {
+                throw assetError(`${where} ("${key}") must have a non-empty string "src", found ${describe(src)}.`);
+            }
+            assets.push({ key, type, src });
+        }
+        else {
+            assets.push({ ...entry, key, type });
+        }
+    });
+    return { format: ASSET_FILE_FORMAT, version: ASSET_FILE_VERSION, assets };
+}
+// ---------------------------------------------------------------------------
+// Design files
+// ---------------------------------------------------------------------------
+/** The `format` value of every design file. */
+const DESIGN_FILE_FORMAT = "minimo-design";
+/** The newest design file `version` this engine reads. */
+const DESIGN_FILE_VERSION = 1;
+function spec(type, defaultValue) {
+    return { type, nullable: false, values: null, required: false, default: defaultValue };
+}
+function requiredString() {
+    return { type: "string", nullable: false, values: null, required: true, default: undefined };
+}
+function nullable(type, defaultValue) {
+    return { type, nullable: true, values: null, required: false, default: defaultValue };
+}
+function oneOf(values, defaultValue) {
+    return { type: "string", nullable: false, values, required: false, default: defaultValue };
+}
+const NAME = { name: spec("string", undefined) };
+const TAGS = { tags: spec("string-list", []) };
+const DATA = { data: spec("object", {}) };
+const SPRITE_SPECS = {
+    ...NAME,
+    ...TAGS,
+    x: spec("number", 0),
+    y: spec("number", 0),
+    scale: spec("number", 1),
+    rotation: spec("number", 0),
+    flipX: spec("boolean", false),
+    flipY: spec("boolean", false),
+    alpha: spec("number", 1),
+    visible: spec("boolean", true),
+    layer: spec("number", 0),
+    color: spec("string", "#000000"),
+    ignoreScroll: spec("boolean", false),
+    isStatic: spec("boolean", false),
+    vx: spec("number", 0),
+    vy: spec("number", 0),
+    gravityScale: spec("number", 0),
+    bodyWidth: nullable("number", null),
+    bodyHeight: nullable("number", null),
+    bodyOffsetX: spec("number", 0),
+    bodyOffsetY: spec("number", 0),
+    ...DATA,
+};
+const IMAGE_SPECS = {
+    imageKey: requiredString(),
+    ...SPRITE_SPECS,
+};
+const EMOJI_SPECS = {
+    sprite: requiredString(),
+    size: spec("number", 32),
+    ...SPRITE_SPECS,
+};
+const TEXT_SPECS = {
+    text: requiredString(),
+    fontSize: spec("number", 16),
+    fontFamily: spec("string", "monospace"),
+    fontWeight: spec("string", "400"),
+    lineHeight: spec("number", 1.2),
+    anchorX: oneOf(["left", "center", "right"], "center"),
+    anchorY: oneOf(["top", "middle", "bottom"], "middle"),
+    textAlign: oneOf(["left", "right", "center", "start", "end"], "center"),
+    maxWidth: spec("number", 0),
+    fixedWidth: spec("number", 0),
+    fixedHeight: spec("number", 0),
+    paddingX: spec("number", 2),
+    paddingY: spec("number", 2),
+    backgroundColor: nullable("string", null),
+    borderColor: nullable("string", null),
+    borderWidth: spec("number", 0),
+    cornerRadius: spec("number", 0),
+    strokeColor: nullable("string", null),
+    strokeWidth: spec("number", 0),
+    ...SPRITE_SPECS,
+    color: spec("string", "#ffffff"),
+};
+const BACKGROUND_SPECS = {
+    imageKey: requiredString(),
+    ...NAME,
+    ...TAGS,
+    x: spec("number", 0),
+    y: spec("number", 0),
+    width: spec("number", 0),
+    height: spec("number", 0),
+    alpha: spec("number", 1),
+    visible: spec("boolean", true),
+    layer: spec("number", 0),
+    fit: oneOf(["none", "stretch", "contain", "cover"], "cover"),
+    ...DATA,
+};
+// `any`: each spec has its own value type, which no longer matters once checked.
+function describeProperties(specs) {
+    return Object.freeze(Object.entries(specs).map(([name, { type, nullable, values, required, default: defaultValue }]) => Object.freeze({ name, type, nullable, values, required, default: defaultValue })));
+}
+/**
+ * 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 const designObjectProperties = Object.freeze({
+    image: describeProperties(IMAGE_SPECS),
+    emoji: describeProperties(EMOJI_SPECS),
+    text: describeProperties(TEXT_SPECS),
+    background: describeProperties(BACKGROUND_SPECS),
+});
+const DESIGN_FILE_FIELDS = new Set(["format", "version", "objects"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PROPERTIES_BY_TYPE = new Map(Object.entries(designObjectProperties).map(([type, properties]) => [
+    type,
+    new Map(properties.map((property) => [property.name, property])),
+]));
+/**
+ * Validates one design object and returns a copy of it. `where` names the
+ * object in errors, such as `objects[3]`.
+ *
+ * @internal
+ */
+export function parseDesignObject(json, where, kind = "design object") {
+    const fail = (message) => new Error(`MinimoJS: Invalid ${kind}: ${message}`);
+    if (!isPlainObject(json)) {
+        throw fail(`${where} must be an object, found ${describe(json)}.`);
+    }
+    const label = typeof json.name === "string" ? `${where} ("${json.name}")` : where;
+    const id = json.id;
+    if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+        throw fail(`${label} must have an "id" that is a UUID, such as "6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27", found ${describe(id)}.`);
+    }
+    const type = json.type;
+    const properties = typeof type === "string" ? PROPERTIES_BY_TYPE.get(type) : undefined;
+    if (properties === undefined) {
+        throw fail(`${label} has the type ${describe(type)}, which is not one of ${Object.keys(designObjectProperties)
+            .map((name) => `"${name}"`)
+            .join(", ")}.`);
+    }
+    const copy = { id, type };
+    for (const [field, value] of Object.entries(json)) {
+        if (field === "id" || field === "type")
+            continue;
+        const property = properties.get(field);
+        if (property === undefined) {
+            throw fail(`${label} has an unknown field "${field}" for the type "${type}".`);
+        }
+        if (!isValidValue(value, property)) {
+            throw fail(`${label} has "${field}" set to ${describe(value)}, but it must be ${describeExpected(property)}.`);
+        }
+        copy[field] = copyJson(value);
+    }
+    for (const property of properties.values()) {
+        if (property.required && !(property.name in copy)) {
+            throw fail(`${label} must have "${property.name}", which every "${type}" object requires.`);
+        }
+    }
+    return copy;
+}
+function isValidValue(value, property) {
+    if (value === null)
+        return property.nullable;
+    switch (property.type) {
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "string":
+            return typeof value === "string" && (property.values === null || property.values.includes(value));
+        case "boolean":
+            return typeof value === "boolean";
+        case "string-list":
+            return Array.isArray(value) && value.every((item) => typeof item === "string");
+        case "object":
+            return isPlainObject(value);
+    }
+}
+function describeExpected(property) {
+    const base = property.values !== null
+        ? `one of ${property.values.map((value) => `"${value}"`).join(", ")}`
+        : {
+            number: "a finite number",
+            string: "a string",
+            boolean: "true or false",
+            "string-list": "a list of strings",
+            object: "a JSON object",
+        }[property.type];
+    return property.nullable ? `${base} or null` : base;
+}
+/** Copies JSON lists and objects deeply, so a copy never shares them with its source. */
+function copyJson(value) {
+    if (Array.isArray(value))
+        return value.map(copyJson);
+    if (isPlainObject(value)) {
+        const copy = {};
+        for (const [key, item] of Object.entries(value))
+            copy[key] = copyJson(item);
+        return copy;
+    }
+    return value;
+}
+function parseDesignFile(json) {
+    const fail = (message) => new Error(`MinimoJS: Invalid design: ${message}`);
+    if (!isPlainObject(json)) {
+        throw fail("a design must be a JSON object.");
+    }
+    for (const field of Object.keys(json)) {
+        if (!DESIGN_FILE_FIELDS.has(field)) {
+            throw fail(`the design has an unknown field "${field}".`);
+        }
+    }
+    if (json.format !== DESIGN_FILE_FORMAT) {
+        throw fail(`"format" must be "${DESIGN_FILE_FORMAT}", found ${describe(json.format)}.`);
+    }
+    const version = json.version;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        throw fail(`"version" must be a positive integer, found ${describe(version)}.`);
+    }
+    if (version > DESIGN_FILE_VERSION) {
+        throw fail(`"version" ${version} is newer than this engine reads (${DESIGN_FILE_VERSION}). Use a newer MinimoJS.`);
+    }
+    // Version 1 is the only version. When the shape changes, an older file is
+    // migrated here, before its objects are checked against the newest shape.
+    if (!Array.isArray(json.objects)) {
+        throw fail(`"objects" must be a list, found ${describe(json.objects)}.`);
+    }
+    const indexById = new Map();
+    const objects = json.objects.map((entry, index) => {
+        const where = `objects[${index}]`;
+        const object = parseDesignObject(entry, where, "design");
+        const id = object.id.toLowerCase();
+        const firstIndex = indexById.get(id);
+        if (firstIndex !== undefined) {
+            throw fail(`the id "${object.id}" is used twice, by objects[${firstIndex}] and ${where}.`);
+        }
+        indexById.set(id, index);
+        return object;
+    });
+    return { format: DESIGN_FILE_FORMAT, version: DESIGN_FILE_VERSION, objects };
+}
+/**
+ * Returns the first item `match` accepts, in order, or throws an error saying
+ * what was searched, because a name or tag that matches nothing is almost
+ * always a typo.
+ *
+ * @internal
+ */
+export function findFirst(items, match, searched, where) {
+    const found = items.find(match);
+    if (found === undefined) {
+        throw new Error(`MinimoJS: No object ${searched} in ${where}.`);
+    }
+    return found;
+}
+/**
+ * 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 class Design {
+    /**
+     * 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) {
+        this.objects = Object.freeze(parseDesignFile(json).objects);
+    }
+    /**
+     * Returns the first object whose `name` is `name`, in file order.
+     * Throws an error naming `name` when there is none.
+     */
+    findByName(name) {
+        return findFirst(this.objects, (object) => object.name === name, `named "${name}"`, "the design");
+    }
+    /** Returns every object whose `name` is `name`, in file order; an empty list when there is none. */
+    findAllByName(name) {
+        return this.objects.filter((object) => object.name === name);
+    }
+    /**
+     * Returns the first object whose `tags` include `tag`, in file order.
+     * Throws an error naming `tag` when there is none.
+     */
+    findByTag(tag) {
+        return findFirst(this.objects, (object) => object.tags?.includes(tag) === true, `tagged "${tag}"`, "the design");
+    }
+    /** Returns every object whose `tags` include `tag`, in file order; an empty list when there is none. */
+    findAllByTag(tag) {
+        return this.objects.filter((object) => object.tags?.includes(tag) === true);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rejectUnknownFields(value, allowed, where) {
+    for (const field of Object.keys(value)) {
+        if (!allowed.has(field)) {
+            throw assetError(`${where} has an unknown field "${field}".`);
+        }
+    }
+}
+function describe(value) {
+    if (value === undefined)
+        return "nothing";
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "a list";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "object")
+        return "an object";
+    return String(value);
+}
+function assetError(message) {
+    return new Error(`MinimoJS: Invalid asset file: ${message}`);
+}