rpg-engine 0.0.0-stage → 0.1.1

package/dist/core/formula.js

@@ -0,0 +1,590 @@
+// The formulas of a game system (FOR-1–FOR-9, D-199): arithmetic on the fields of a page, read once and worked out on any page. They know no game: a system
+// writes what a modifier or a bonus is, and the core only counts.
+import { comparableText, linkTargetName, valueNamed } from "./text.js";
+/**
+ * Reads the formulas of a system (FOR-1, FOR-9): each must read as a formula, name only tables the system has, and computed fields must not read each other
+ * in a circle. Refused with the place of the first that does not.
+ */
+export function readFormulas(data) {
+    const tables = Object.fromEntries(Object.entries(data.tables ?? {}).map(([name, rows]) => [name, tableOf(rows)]));
+    const computed = Object.entries(data.computed ?? {}).map(([name, given]) => [name, computedFormula(name, given)]);
+    const twice = computed.find(([name], index) => computed.findIndex(([other]) => comparableText(other) === comparableText(name)) !== index);
+    if (twice !== undefined) {
+        throw new Error(`computed.${twice[0]}: the field is given twice, in different cases: give it once.`);
+    }
+    const counters = Object.fromEntries(Object.entries(data.counters ?? {}).map(([name, limits]) => [name, {
+            ...(limits.min === undefined ? {} : { min: placed(`counters.${name}.min`, () => formulaOf(limits.min)) }),
+            ...(limits.max === undefined ? {} : { max: placed(`counters.${name}.max`, () => formulaOf(limits.max)) }),
+            ...(limits.refill === undefined ? {} : { refill: refillOf(name, limits.refill) }),
+        }]));
+    const all = [
+        ...computed.map(([name, formula]) => [`computed.${name}`, formula]),
+        ...Object.entries(counters).flatMap(([name, limits]) => [
+            ...[limits.min, limits.max].flatMap((formula, index) => (formula === undefined ? [] : [[`counters.${name}.${index === 0 ? "min" : "max"}`, formula]])),
+            ...Object.entries(limits.refill ?? {}).map(([occasion, formula]) => [`counters.${name}.refill.${occasion}`, formula]),
+        ]),
+    ];
+    for (const [place, formula] of all) {
+        const missing = tablesRead(formula).find((table) => !Object.keys(tables).some((name) => comparableText(name) === comparableText(table)));
+        if (missing !== undefined) {
+            throw new Error(`${place}: there is no table "${missing}" in tables.`);
+        }
+    }
+    checkCircles(computed);
+    return { computed, tables, counters };
+}
+const mathNames = ["floor", "ceil", "min", "max", "best"];
+const listNames = ["has", "count", "item", "sum"];
+const namePattern = /[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*/y;
+const numberPattern = /\d+(?:\.\d+)?/y;
+// "[[Cleric]] 3", "Perception +3": a name in a list, and the number after it.
+const itemPattern = /^(.*?)\s+([+-]?\d+)$/;
+// "Channel Divinity (2/rest)": a name and a value in parentheses after it.
+const valuePattern = /^(.*?\S)\s*\(([^()]*)\)$/;
+// [[Page]], [[Page#Section]], [[Page|label]].
+const linkPattern = /^\[\[([^\]|#]+)(?:#([^\]|]+))?(?:\|[^\]]*)?\]\]$/;
+/** Reads a formula; refused, with where and why, when it does not read as one (FOR-9). */
+export function parseFormula(text) {
+    const reader = new FormulaReader(text);
+    const formula = reader.expression();
+    reader.end();
+    return formula;
+}
+/**
+ * Reads a formula that may begin with dice, such as 1d8 or 2d6, or with dice(…), the largest of several, such as dice(1d6, martial-arts) (D-235), and end with
+ * words, such as a damage type: "1d8 + str-mod + bonus slashing". Refused, with why, when what is between does not read as a formula (FOR-9).
+ */
+export function parseRollFormula(text) {
+    const opening = openingDice(text);
+    const dice = opening?.choices;
+    const rest = (opening === undefined ? text : text.slice(opening.length)).trim();
+    const words = rest.split(/\s+/).filter((word) => word !== "");
+    if (dice !== undefined && words.length > 0 && !/^[+-]/.test(rest)) {
+        return { dice, words: rest };
+    }
+    // The longest beginning that reads as a formula; the words after it are said as they are.
+    for (let count = words.length; count > 0; count--) {
+        const formula = tryFormula(words.slice(0, count).join(" ").replace(/^\+\s*/, ""));
+        const tail = words.slice(count).join(" ");
+        if (formula !== undefined && /^[\p{L} ]*$/u.test(tail)) {
+            return { ...(dice === undefined ? {} : { dice }), formula, ...(tail === "" ? {} : { words: tail }) };
+        }
+    }
+    if (dice !== undefined && words.length === 0) {
+        return { dice };
+    }
+    // Read again, after the dice, which are allowed, for the reason it does not read.
+    return { formula: parseFormula(dice === undefined ? text : rest.replace(/^\+\s*/, "")) };
+}
+/**
+ * The dice a roll takes (D-235): of its choices, the largest that has a value, by the average it rolls, the first of two alike; a field gives dice it holds,
+ * such as a monk's martial-arts 1d6, or a number. Undefined when none has a value, as martial-arts for one who is no monk.
+ */
+export function chosenDice(choices, scope) {
+    const valued = choices.flatMap((choice) => {
+        if ("dice" in choice) {
+            return [{ dice: choice.dice, reads: [] }];
+        }
+        if ("number" in choice) {
+            return [{ number: choice.number, reads: [] }];
+        }
+        const value = scope.field(choice.field);
+        const number = numberOf(value);
+        const dice = typeof value === "string" && dicePattern.test(value.trim()) ? value.trim() : undefined;
+        return dice !== undefined ? [{ dice, reads: [{ field: choice.field, dice }] }] : number !== undefined ? [{ number, reads: [{ field: choice.field, value: number }] }] : [];
+    });
+    const average = (choice) => (choice.dice === undefined ? (choice.number ?? 0) : diceAverage(choice.dice));
+    return valued.reduce((best, choice) => (best === undefined || average(choice) > average(best) ? choice : best), undefined);
+}
+/** The fields a roll's dice read, as martial-arts in dice(1d6, martial-arts) (D-235). */
+export function diceFields(roll) {
+    return (roll.dice ?? []).flatMap((choice) => ("field" in choice ? [choice.field] : []));
+}
+// 1d8, d6, 2d6: dice as a roll writes them.
+const dicePattern = /^(\d*)d(\d+)$/i;
+/** What dice roll on average, as 4.5 for 1d8. */
+function diceAverage(dice) {
+    const [, count, faces] = dicePattern.exec(dice) ?? [];
+    return (count === "" || count === undefined ? 1 : Number(count)) * (Number(faces) + 1) / 2;
+}
+/** The dice a roll formula begins with, and how much of its text they take: 1d8, or dice(…) with dice, numbers and fields (D-235); undefined for none. */
+function openingDice(text) {
+    const written = /^\s*(\d*d\d+)\b/i.exec(text);
+    if (written !== null) {
+        return { choices: [{ dice: written[1] }], length: written[0].length };
+    }
+    const call = /^\s*dice\s*\(([^()]*)\)/i.exec(text);
+    if (call === null && /^\s*dice\s*\(/i.test(text)) {
+        throw new Error(`"${text}" is not a formula: dice() holds only dice, numbers and fields, between commas, such as dice(1d6, martial-arts).`);
+    }
+    if (call === null) {
+        return undefined;
+    }
+    const choices = call[1].split(",").map((part) => {
+        const choice = part.trim();
+        namePattern.lastIndex = 0;
+        const name = namePattern.exec(choice);
+        if (dicePattern.test(choice)) {
+            return { dice: choice };
+        }
+        if (/^\d+$/.test(choice)) {
+            return { number: Number(choice) };
+        }
+        if (name !== null && name[0] === choice) {
+            return { field: choice };
+        }
+        throw new Error(`"${text}" is not a formula: dice, a number or a field that holds dice was expected in dice() at "${choice}", such as dice(1d6, martial-arts).`);
+    });
+    return { choices, length: call[0].length };
+}
+function tryFormula(text) {
+    try {
+        return parseFormula(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A formula given as a number or as text, as system.yaml writes it. */
+export function formulaOf(value) {
+    return typeof value === "number" ? { kind: "number", value } : parseFormula(value);
+}
+/** Works a formula out on what a page holds (FOR-4): no value when a field it needs is missing, a table has no row for the key, or it divides by zero. */
+export function workOut(formula, scope) {
+    const reads = [];
+    const value = evaluate(formula, scope, reads);
+    // Never -0, which a sheet would show as such.
+    return { value: value === undefined || !Number.isFinite(value) ? undefined : value === 0 ? 0 : value, reads };
+}
+/**
+ * What a result came from (FOR-8): the values it read that change it, a number tried higher, lower and at 0, and a list tried empty; a value multiplied by 0,
+ * as a proficiency without the skill, did not count. The rows of tables, and what gives their keys, always count.
+ */
+export function contributingReads(formula, scope, worked) {
+    return worked.reads.filter((read) => {
+        if ("table" in read || "dice" in read || ("field" in read && read.key === true)) {
+            return true;
+        }
+        const name = "field" in read ? read.field : read.list;
+        // Tried in several ways: a value halved and rounded down moves only on one side of it.
+        const probes = "field" in read ? [read.value + 1, read.value - 1, 0, read.value + 10] : [[]];
+        return probes.some((probe) => workOut(formula, { field: (field) => (comparableText(field) === comparableText(name) ? probe : scope.field(field)), table: scope.table }).value !== worked.value);
+    });
+}
+/** The fields a formula reads, lists included, each once and in order: what it comes from. */
+export function fieldsRead(formula) {
+    switch (formula.kind) {
+        case "number":
+            return [];
+        case "field":
+            return [formula.name];
+        case "negate":
+            return fieldsRead(formula.operand);
+        case "operation":
+            return unique([...fieldsRead(formula.left), ...fieldsRead(formula.right)]);
+        case "math":
+            return unique(formula.operands.flatMap(fieldsRead));
+        case "table":
+            return fieldsRead(formula.key);
+        case "list":
+            return [formula.list];
+        case "first":
+            return unique(formula.options.flatMap(fieldsRead));
+    }
+}
+/** The tables a formula reads. */
+export function tablesRead(formula) {
+    switch (formula.kind) {
+        case "negate":
+            return tablesRead(formula.operand);
+        case "operation":
+            return unique([...tablesRead(formula.left), ...tablesRead(formula.right)]);
+        case "math":
+            return unique(formula.operands.flatMap(tablesRead));
+        case "table":
+            return unique([formula.table, ...tablesRead(formula.key)]);
+        case "first":
+            return unique(formula.options.flatMap(tablesRead));
+        default:
+            return [];
+    }
+}
+/** A table from its rows as system.yaml writes them, `{1: 2, 5: 3}` or `{troublesome: 12}`. */
+export function tableOf(rows) {
+    return { rows: Object.entries(rows) };
+}
+/** The names of the items of a list field, as has, count and item read them (FOR-2): a link as the page or the section it names, without the number after a name. */
+export function listItemNames(value) {
+    return itemsOf(value).map((item) => item.name);
+}
+/** The items of a list field with the number after each name, such as Fighter and 3 for [[Fighter]] 3 (FOR-2); a single value is a list of one. */
+export function listItems(value) {
+    return itemsOf(value);
+}
+/** A field's value read as a number (FOR-2): a number, a counter's current value, or text such as +2. Undefined for anything else. */
+export function numberOf(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const match = /^\s*([+-]?\d+(?:\.\d+)?)\s*(?:\/\s*\d+\s*)?$/.exec(value);
+    return match === null ? undefined : Number(match[1]);
+}
+function evaluate(formula, scope, reads) {
+    switch (formula.kind) {
+        case "number":
+            return formula.value;
+        case "field":
+            return fieldNumber(formula.name, scope, reads);
+        case "negate": {
+            const operand = evaluate(formula.operand, scope, reads);
+            return operand === undefined ? undefined : -operand;
+        }
+        case "operation":
+            return operate(formula.operator, evaluate(formula.left, scope, reads), evaluate(formula.right, scope, reads));
+        case "math":
+            return mathValue(formula.name, formula.operands, scope, reads);
+        case "table": {
+            const before = reads.length;
+            const key = evaluate(formula.key, scope, reads);
+            // What gives the key always counts: a level one higher may stay in the same row (FOR-8).
+            for (const read of reads.slice(before)) {
+                if ("value" in read && "field" in read) {
+                    read.key = true;
+                }
+            }
+            return tableValue(formula.table, key, formula.key, scope, reads);
+        }
+        case "list":
+            return listValue(formula, scope, reads);
+        case "first":
+            return firstValue(formula.options, scope, reads);
+    }
+}
+/** The value of the first of a field's formulas that has one, with only what that one read (D-210). */
+function firstValue(options, scope, reads) {
+    for (const option of options) {
+        const tried = [];
+        const value = evaluate(option, scope, tried);
+        if (value !== undefined && Number.isFinite(value)) {
+            reads.push(...tried);
+            return value;
+        }
+    }
+    return undefined;
+}
+function fieldNumber(name, scope, reads) {
+    const value = numberOf(scope.field(name));
+    if (value !== undefined) {
+        reads.push({ field: name, value });
+    }
+    return value;
+}
+function operate(operator, left, right) {
+    if (left === undefined || right === undefined) {
+        return undefined;
+    }
+    switch (operator) {
+        case "+":
+            return left + right;
+        case "-":
+            return left - right;
+        case "*":
+            return left * right;
+        case "/":
+            return right === 0 ? undefined : left / right;
+    }
+}
+/** A function of its operands; min, max and best keep only what the operand that gives the result read, as first does (FOR-8). */
+function mathValue(name, operands, scope, reads) {
+    const tried = operands.map((operand) => {
+        const own = [];
+        return { value: evaluate(operand, scope, own), reads: own };
+    });
+    const value = mathOf(name, tried.map((operand) => operand.value));
+    // Of operands that tie, one that read something: min(1, level) at level 1 comes from the level.
+    const winners = tried.filter((operand) => operand.value === value);
+    const chosen = value !== undefined && (name === "min" || name === "max" || name === "best") ? [winners.find((operand) => operand.reads.length > 0) ?? winners[0]] : tried;
+    reads.push(...chosen.flatMap((operand) => operand.reads));
+    return value;
+}
+function mathOf(name, operands) {
+    // The highest of those that have a value, as the best of the ways to work out an armor class (FOR-2).
+    if (name === "best") {
+        const values = operands.filter((operand) => operand !== undefined);
+        return values.length === 0 ? undefined : Math.max(...values);
+    }
+    if (operands.some((operand) => operand === undefined)) {
+        return undefined;
+    }
+    const values = operands;
+    switch (name) {
+        case "floor":
+            return Math.floor(values[0]);
+        case "ceil":
+            return Math.ceil(values[0]);
+        case "min":
+            return Math.min(...values);
+        case "max":
+            return Math.max(...values);
+    }
+}
+function tableValue(name, key, keyFormula, scope, reads) {
+    const table = scope.table(name);
+    const text = key === undefined && keyFormula.kind === "field" ? scope.field(keyFormula.name) : key;
+    if (table === undefined || text === undefined) {
+        return undefined;
+    }
+    const row = typeof text === "number" ? numberRow(table, text) : table.rows.find(([candidate]) => comparableText(candidate) === comparableText(String(text)));
+    if (row !== undefined) {
+        reads.push({ table: name, key: String(text), value: row[1] });
+    }
+    return row?.[1];
+}
+function numberRow(table, key) {
+    return table.rows.filter(([row]) => numberOf(row) !== undefined && Number(row) <= key).sort(([first], [second]) => Number(second) - Number(first))[0];
+}
+function listValue(formula, scope, reads) {
+    const raw = scope.field(formula.list);
+    // Only sum needs the list: has, count and item read a missing one as empty (FOR-4).
+    if (formula.name === "sum" && raw === undefined) {
+        return undefined;
+    }
+    // sum(classes, hit-die = d10): only the items whose page has that value in that field (D-215).
+    const where = formula.where;
+    const items = itemsOf(raw).filter((item) => {
+        const fields = where === undefined ? undefined : scope.page?.(item.name);
+        const value = fields === undefined || where === undefined ? undefined : valueNamed(fields, where.field);
+        return where === undefined || (value !== undefined && comparableText(String(value).trim()) === comparableText(where.value));
+    });
+    const named = (item) => comparableText(item.name) === comparableText(formula.item ?? "");
+    const value = formula.name === "has"
+        ? (items.some(named) ? 1 : 0)
+        : formula.name === "count"
+            ? items.length
+            : formula.name === "item"
+                ? (items.find(named)?.number ?? 0)
+                : items.reduce((total, item) => total + (item.number ?? 0), 0);
+    // "5 in classes, spellcasting full": a filtered total says its filter; a count says how many, not a number of the list.
+    const filter = where === undefined ? {} : { where: `${where.field} ${where.value}` };
+    const counted = formula.name === "count" ? { count: true } : {};
+    reads.push(formula.item === undefined ? { list: formula.list, value, ...filter, ...counted } : { list: formula.list, item: formula.item, value });
+    return value;
+}
+/**
+ * The items of a list field, each with its name and the number after it, if any. A link reads as the page it names, or as its section, as a feature
+ * [[Cleric#Channel Divinity]] does. A value in parentheses after the name is not part of it, and gives the number it begins with when no number follows the
+ * name: Channel Divinity (2/rest) is Channel Divinity with 2, Bardic Inspiration (d8) has none (D-220). A single value is a list of one.
+ */
+function itemsOf(value) {
+    const values = value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
+    return values.map((item) => {
+        const text = String(item).trim();
+        const match = itemPattern.exec(text);
+        const valued = match === null ? valuePattern.exec(text) : null;
+        const written = (match !== null ? match[1] : valued !== null ? valued[1] : text).trim();
+        const link = linkPattern.exec(written);
+        const name = link === null ? written : (link[2] ?? linkTargetName(link[1])).trim();
+        const inside = valued === null ? null : /^\s*([+-]?\d+)/.exec(valued[2]);
+        return { name, number: match !== null ? Number(match[2]) : inside === null ? undefined : Number(inside[1]) };
+    });
+}
+function unique(names) {
+    return names.filter((name, index) => names.findIndex((other) => comparableText(other) === comparableText(name)) === index);
+}
+/** A computed field as system.yaml writes it: one formula, or several in order, of which the first with a value counts (FOR-1, D-210). */
+function computedFormula(name, given) {
+    if (!Array.isArray(given)) {
+        return placed(`computed.${name}`, () => formulaOf(given));
+    }
+    if (given.length === 0) {
+        throw new Error(`computed.${name}: give a formula, or formulas in order, such as [a formula, another].`);
+    }
+    const options = given.map((option, index) => placed(`computed.${name}[${index + 1}]`, () => formulaOf(option)));
+    return options.length === 1 ? options[0] : { kind: "first", options };
+}
+/** How much of a counter comes back on each occasion (DAT-9): an occasion alone brings it all back, as "long rest" does max; or by occasion, a formula. */
+function refillOf(name, refill) {
+    const all = { kind: "field", name: "max" };
+    return typeof refill === "string"
+        ? { [refill.trim()]: all }
+        : Object.fromEntries(Object.entries(refill).map(([occasion, amount]) => [occasion.trim(), placed(`counters.${name}.refill.${occasion}`, () => formulaOf(amount))]));
+}
+/** A formula read at its place in system.yaml, such as computed.insight, which a refusal names first. */
+function placed(place, read) {
+    try {
+        return read();
+    }
+    catch (error) {
+        throw new Error(`${place}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Refuses computed fields that read each other in a circle, such as a → b → a: none of them could be worked out. */
+function checkCircles(computed) {
+    const named = (name) => computed.find(([candidate]) => comparableText(candidate) === comparableText(name));
+    const visit = (name, path) => {
+        if (path.some((step) => comparableText(step) === comparableText(name))) {
+            throw new Error(`computed fields read each other in a circle: ${[...path, name].join(" → ")}. Give one of them a formula that does not.`);
+        }
+        const entry = named(name);
+        for (const next of entry === undefined ? [] : fieldsRead(entry[1]).filter((field) => named(field) !== undefined)) {
+            visit(next, [...path, name]);
+        }
+    };
+    for (const [name] of computed) {
+        visit(name, []);
+    }
+}
+/** Reads the text of a formula from left to right: an expression is terms added or subtracted, a term factors multiplied or divided. */
+class FormulaReader {
+    position = 0;
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    expression() {
+        let formula = this.term();
+        for (let operator = this.operator("+-"); operator !== undefined; operator = this.operator("+-")) {
+            formula = { kind: "operation", operator, left: formula, right: this.term() };
+        }
+        return formula;
+    }
+    end() {
+        this.skipSpaces();
+        if (this.position < this.text.length) {
+            this.fail("an operator, or the end of the formula");
+        }
+    }
+    term() {
+        let formula = this.factor();
+        for (let operator = this.operator("*/"); operator !== undefined; operator = this.operator("*/")) {
+            formula = { kind: "operation", operator, left: formula, right: this.factor() };
+        }
+        return formula;
+    }
+    factor() {
+        this.skipSpaces();
+        if (this.take("-")) {
+            return { kind: "negate", operand: this.factor() };
+        }
+        if (this.take("(")) {
+            const inner = this.expression();
+            this.expect(")");
+            return inner;
+        }
+        const number = this.match(numberPattern);
+        if (number !== undefined) {
+            return { kind: "number", value: Number(number) };
+        }
+        const name = this.match(namePattern);
+        if (name === undefined) {
+            this.fail("a number, a field, a function or (");
+        }
+        this.skipSpaces();
+        return this.take("(") ? this.call(name) : { kind: "field", name };
+    }
+    call(name) {
+        const lower = name.toLowerCase();
+        if (mathNames.includes(lower)) {
+            const operands = [this.expression()];
+            while (this.take(",")) {
+                operands.push(this.expression());
+            }
+            this.expect(")");
+            if ((lower === "floor" || lower === "ceil") !== (operands.length === 1)) {
+                this.fail(lower === "floor" || lower === "ceil" ? `one value in ${lower}()` : `at least two values in ${lower}()`);
+            }
+            return { kind: "math", name: lower, operands };
+        }
+        if (lower === "table") {
+            const table = this.name("the name of a table");
+            this.expect(",");
+            const key = this.expression();
+            this.expect(")");
+            return { kind: "table", table, key };
+        }
+        if (listNames.includes(lower)) {
+            const list = this.name("the name of a list");
+            // sum(classes, hit-die = d10), count(classes, spellcasting = full): only the items whose page has that value (D-215, D-227).
+            if ((lower === "sum" || lower === "count") && this.take(",")) {
+                const [field, value, ...rest] = this.rawUntilClose().split("=").map((part) => part.trim());
+                if (field === undefined || field === "" || value === undefined || value === "" || rest.length > 0) {
+                    this.fail("a field = value, such as hit-die = d10, then )");
+                }
+                return { kind: "list", name: lower, list, where: { field, value } };
+            }
+            if (lower === "count" || lower === "sum") {
+                this.expect(")");
+                return { kind: "list", name: lower, list };
+            }
+            this.expect(",");
+            const item = this.rawUntilClose();
+            return { kind: "list", name: lower, list, item };
+        }
+        // Dice only begin the formula of an item's page (D-235).
+        if (lower === "dice") {
+            throw new Error(`"${this.text}" is not a formula: dice() goes only at the beginning of an item's formula, such as dice(1d6, martial-arts) + dex-mod.`);
+        }
+        this.fail(`a function: ${[...mathNames, "table", ...listNames].join(", ")}`);
+    }
+    /** The name of an item in has() or item(), as it is written: it may hold spaces, as in Dwarven Toughness. */
+    rawUntilClose() {
+        const close = this.text.indexOf(")", this.position);
+        const item = close === -1 ? "" : this.text.slice(this.position, close).trim();
+        if (item === "") {
+            this.fail("the name of an item, then )");
+        }
+        this.position = close + 1;
+        return item;
+    }
+    name(what) {
+        this.skipSpaces();
+        const name = this.match(namePattern);
+        if (name === undefined) {
+            this.fail(what);
+        }
+        return name;
+    }
+    operator(operators) {
+        this.skipSpaces();
+        const next = this.text[this.position];
+        if (next !== undefined && operators.includes(next)) {
+            this.position++;
+            return next;
+        }
+        return undefined;
+    }
+    match(pattern) {
+        pattern.lastIndex = this.position;
+        const match = pattern.exec(this.text);
+        if (match === null) {
+            return undefined;
+        }
+        this.position += match[0].length;
+        return match[0];
+    }
+    take(text) {
+        this.skipSpaces();
+        if (this.text.startsWith(text, this.position)) {
+            this.position += text.length;
+            return true;
+        }
+        return false;
+    }
+    expect(text) {
+        if (!this.take(text)) {
+            this.fail(`"${text}"`);
+        }
+    }
+    skipSpaces() {
+        while (this.text[this.position] === " " || this.text[this.position] === "\t") {
+            this.position++;
+        }
+    }
+    fail(expected) {
+        const rest = this.text.slice(this.position);
+        throw new Error(`"${this.text}" is not a formula: ${expected} was expected ${rest === "" ? "at the end" : `at "${rest}"`}.`);
+    }
+}

package/dist/core/frozen.d.ts

@@ -0,0 +1,2 @@
+/** The value made read-only with all it holds, as it is: a command that tried to change it fails at once, in the tests first. */
+export declare function frozen<T>(value: T): T;

package/dist/core/frozen.js

@@ -0,0 +1,11 @@
+// What is read from the files is never changed in place (step 11): once the server keeps it for later calls, a change there would last and spread.
+/** The value made read-only with all it holds, as it is: a command that tried to change it fails at once, in the tests first. */
+export function frozen(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const inner of Object.values(value)) {
+            frozen(inner);
+        }
+    }
+    return value;
+}

package/dist/core/length.d.ts

@@ -0,0 +1,27 @@
+/** The units of measure of the story (D-33). */
+export declare const unitSystems: readonly ["metric", "imperial"];
+export type UnitSystem = (typeof unitSystems)[number];
+/** How many metres a game's mile and foot are worth (D-262), as 1.5 km and 0.3 m in the fifth edition; the true ones when the game says nothing. */
+export interface ImperialUnits {
+    mile: number;
+    foot: number;
+}
+export declare const trueImperialUnits: ImperialUnits;
+/** How to write a length, for messages. */
+export declare const lengthHelp = "in km or m, such as 8 km, 1.5 km or 500 m: the engine keeps every measure in metric, and its outputs give them in the player's units";
+/** How to write a speed, for messages. */
+export declare const speedHelp = "the distance of an hour in metric, such as 4.5 km or 4.5 km/h";
+/** A length in metres from a number and its metric unit, such as 8 km, 1.5 km or 500 m; undefined for anything else, miles, a number without a unit and 0 among them. */
+export declare function readLength(value: unknown): number | undefined;
+/** A speed in metres an hour (TRV-1): the distance of an hour, with or without /h, such as 4.5 km or 4.5 km/h; undefined for anything else. */
+export declare function readSpeed(value: unknown): number | undefined;
+/** A length in the units of the story, with one decimal at most: 12 km, 800 m; in imperial with the game's units, 8 miles, 300 feet. */
+export declare function formatLength(metres: number, units: UnitSystem, imperial?: ImperialUnits): string;
+/** A speed in the units of the story: 4.5 km an hour, 3 miles an hour. */
+export declare function formatSpeed(metresAnHour: number, units: UnitSystem, imperial?: ImperialUnits): string;
+/** A short length, as on the map of a place (GRD-5), in the units of the story: 7.5 m; in imperial with the game's foot, 25 feet. */
+export declare function formatStep(metres: number, units: UnitSystem, imperial?: ImperialUnits): string;
+/** A text with the lengths it writes in feet told in the units of the story, as a speed of the sheet (D-328): 30 ft., fly 60 ft. is 9 m, fly 18 m in metric. */
+export declare function lengthsInUnits(text: string, units: UnitSystem, imperial?: ImperialUnits): string;
+/** The first length a text gives, in metres, as a sheet writes a speed: 30 ft., 30 feet, 9 m; undefined when it gives none, or a number without its unit. */
+export declare function readFirstLength(value: unknown, imperial?: ImperialUnits): number | undefined;