rpg-engine 0.0.0-stage → 0.1.1

package/dist/grid/grid.d.ts

@@ -0,0 +1,53 @@
+/** A square of the grid, from the top left. */
+export interface Square {
+    column: number;
+    row: number;
+}
+/** A symbol of the legend: its name, its kind for the drawing, whether it keeps one out or costs more to cross. */
+export interface Feature {
+    symbol: string;
+    name: string;
+    kind: string;
+    blocks: boolean;
+    difficult: boolean;
+    /** Not found yet (GRD-6): the player sees what lies under it. */
+    hidden: boolean;
+}
+export interface Grid {
+    columns: number;
+    rows: number;
+    /** The rows as written, each as long as the widest, a space outside. */
+    lines: string[];
+    /** The legend, the symbols every map has first. */
+    features: Feature[];
+    /** Where squares lead, as written: a place's name. */
+    exits: {
+        square: Square;
+        to: string;
+    }[];
+}
+/** The symbols every map has (GRD-1): a wall, the floor and a door; a space is outside. */
+export declare const builtIn: readonly Feature[];
+/** The flags a symbol of the legend may have, after its kind. */
+export declare const flags: readonly ["blocks", "difficult", "hidden"];
+/** The first map block of a text: what stands between ```map and ```; none when it has none. */
+export declare function mapBlock(text: string): string | undefined;
+/** A text without its map block, which the dashboard draws instead, nor the heading of a section the block was all of. */
+export declare function withoutMapBlock(text: string): string;
+/** The grid of a map block (GRD-1, GRD-2), and what of it cannot be read, each as a sentence that says how to fix it. */
+export declare function readGrid(block: string): {
+    grid: Grid;
+    problems: string[];
+};
+/** A square's name, as the player says it: its column's letters and its row's number, from A1 at the top left; after Z, AA. */
+export declare function squareName(square: Square): string;
+/** The square a name such as C4 or c4 says; none for anything else. */
+export declare function readSquare(name: string): Square | undefined;
+/** The symbol at a square; a space outside the grid. */
+export declare function symbolAt(grid: Grid, square: Square): string;
+/** What stands at a square, from the legend; none outside, or for a symbol the legend does not name. */
+export declare function featureAt(grid: Grid, square: Square): Feature | undefined;
+/** The first square one can stand on, row by row from the top left, for examples; A1 when there is none. */
+export declare function firstOpenSquare(grid: Grid): Square;
+/** Why one cannot stand at a square (GRD-3): outside the map, a wall, what blocks, or a symbol the legend does not name; none when one can. */
+export declare function closedSquare(grid: Grid, square: Square): string | undefined;

package/dist/grid/grid.js

@@ -0,0 +1,151 @@
+// The map of a place as the master writes it (GRD-1, GRD-2, D-324): squares in rows, a symbol each, then a legend that names the symbols and says where a
+// square leads; and the names of the squares, from A1 at the top left.
+/** The symbols every map has (GRD-1): a wall, the floor and a door; a space is outside. */
+export const builtIn = [
+    { symbol: "#", name: "wall", kind: "wall", blocks: true, difficult: false, hidden: false },
+    { symbol: ".", name: "floor", kind: "floor", blocks: false, difficult: false, hidden: false },
+    { symbol: "+", name: "door", kind: "door", blocks: false, difficult: false, hidden: false },
+];
+/** The flags a symbol of the legend may have, after its kind. */
+export const flags = ["blocks", "difficult", "hidden"];
+// What stands in the grid for a written character that makes no square, as an emoji or a tab: no legend names it, and no one stands on it.
+const unreadableSymbol = "\uFFFD";
+/** The first map block of a text: what stands between ```map and ```; none when it has none. */
+export function mapBlock(text) {
+    return /^```map[ \t]*\r?\n([\s\S]*?)^```[ \t]*$/m.exec(text)?.[1].replace(/\r/g, "").replace(/\n$/, "");
+}
+/** A text without its map block, which the dashboard draws instead, nor the heading of a section the block was all of. */
+export function withoutMapBlock(text) {
+    const lines = text.replace(/^```map[ \t]*\r?\n[\s\S]*?^```[ \t]*(?:\r?\n|$)/m, "").split(/\r?\n/);
+    const level = (line) => /^(#{1,6})\s/.exec(line ?? "")?.[1].length ?? 0;
+    const kept = lines.filter((line, index) => {
+        const next = lines.slice(index + 1).find((other) => other.trim() !== "");
+        return level(line) === 0 || (next !== undefined && (level(next) === 0 || level(next) > level(line)));
+    });
+    return kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** The grid of a map block (GRD-1, GRD-2), and what of it cannot be read, each as a sentence that says how to fix it. */
+export function readGrid(block) {
+    const lines = block.normalize("NFC").split("\n");
+    const blank = lines.findIndex((line) => line.trim() === "");
+    const written = (blank === -1 ? lines : lines.slice(0, blank)).map((line) => [...line.replace(/\s+$/, "")]);
+    const rows = written.map((symbols) => symbols.map((symbol) => (isOneSquare(symbol) ? symbol : unreadableSymbol)).join(""));
+    const columns = Math.max(0, ...rows.map((line) => line.length));
+    const features = [...builtIn];
+    const exits = [];
+    const problems = [];
+    const legendSymbols = new Set();
+    for (const line of blank === -1 ? [] : lines.slice(blank + 1).map((each) => each.trim()).filter((each) => each !== "")) {
+        const exit = /^([A-Za-z]+\d+)\s*(?:→|->)\s*(.+)$/.exec(line);
+        const named = /^(\S)\s+([^:]+?)\s*(?::\s*(.*))?$/u.exec(line);
+        if (exit !== null) {
+            const square = readSquare(exit[1]);
+            const to = exit[2].replace(/^\[\[|\]\]$/g, "").split("|")[0].trim();
+            if (square === undefined || square.row >= rows.length || square.column >= columns) {
+                problems.push(`${exit[1].toUpperCase()} is not a square of the map, which goes from A1 to ${squareName({ column: columns - 1, row: rows.length - 1 })}: write the exit on one of its squares.`);
+            }
+            else {
+                exits.push({ square, to });
+            }
+        }
+        else if (named !== null && !isOneSquare(named[1])) {
+            problems.push(notOneSquare(named[1]));
+        }
+        else if (named !== null) {
+            const [symbol, name] = [named[1], named[2]];
+            const words = (named[3] ?? "").split(",").map((word) => word.trim().toLowerCase()).filter((word) => word !== "");
+            const unknown = words.slice(1).filter((word) => !flags.includes(word));
+            const own = builtIn.find((feature) => feature.symbol === symbol);
+            if (legendSymbols.has(symbol)) {
+                problems.push(`The legend names ${symbol} twice: keep one line for it.`);
+            }
+            else if (own !== undefined) {
+                // A symbol every map has takes another name and drawing, as rock for the walls of a cave; it never stops or starts blocking.
+                const index = features.findIndex((feature) => feature.symbol === symbol);
+                features[index] = { ...own, name, kind: words[0] ?? own.kind, difficult: words.includes("difficult") };
+                if ((words.includes("blocks") && !own.blocks) || words.includes("hidden")) {
+                    problems.push(`${symbol} is the map's ${own.name}, which ${own.blocks ? "always blocks" : "never blocks"} and is never hidden: change only its name and kind, such as "${symbol} ${name}: ${words[0] ?? own.kind}".`);
+                }
+            }
+            else {
+                features.push({ symbol, name, kind: words[0] ?? "", blocks: words.includes("blocks"), difficult: words.includes("difficult"), hidden: words.includes("hidden") });
+            }
+            legendSymbols.add(symbol);
+            if (unknown.length > 0) {
+                problems.push(`${symbol} ${name} has ${unknown.join(", ")}, which the map does not know: after the kind come only ${flags.slice(0, -1).join(", ")} and ${flags.at(-1)}.`);
+            }
+        }
+        else {
+            problems.push(`The legend's line "${line}" is neither a symbol, such as t table: table, difficult, nor an exit, such as G8 → [[Place]].`);
+        }
+    }
+    const grid = { columns, rows: rows.length, lines: rows.map((line) => line.padEnd(columns, " ")), features, exits };
+    const unreadable = written.flat().filter((symbol) => !isOneSquare(symbol)).map(notOneSquare);
+    const unnamed = [...new Set(grid.lines.join(""))].filter((symbol) => symbol !== " " && symbol !== unreadableSymbol && !features.some((feature) => feature.symbol === symbol));
+    const nameless = unnamed.map((symbol) => `The map has ${symbol}, which its legend does not name: add a line such as "${symbol} barrel: barrel, blocks".`);
+    // One comes in by an exit's square: a wall or what blocks there would put them on it.
+    const shut = exits.flatMap((exit) => {
+        const closed = closedSquare(grid, exit.square);
+        return closed === undefined ? [] : [`${squareName(exit.square)} leads to ${exit.to}, but ${closed}: write the exit on the door, or on the square one comes in by.`];
+    });
+    return { grid, problems: [...new Set([...problems, ...unreadable, ...nameless, ...shut])] };
+}
+/** A square's name, as the player says it: its column's letters and its row's number, from A1 at the top left; after Z, AA. */
+export function squareName(square) {
+    let letters = "";
+    for (let column = square.column + 1; column > 0; column = Math.floor((column - 1) / 26)) {
+        letters = String.fromCharCode(65 + ((column - 1) % 26)) + letters;
+    }
+    return `${letters}${square.row + 1}`;
+}
+/** The square a name such as C4 or c4 says; none for anything else. */
+export function readSquare(name) {
+    const match = /^([A-Za-z]+)(\d+)$/.exec(name.trim());
+    if (match === null || Number(match[2]) < 1) {
+        return undefined;
+    }
+    const column = [...match[1].toUpperCase()].reduce((total, letter) => total * 26 + letter.charCodeAt(0) - 64, 0) - 1;
+    return { column, row: Number(match[2]) - 1 };
+}
+/** The symbol at a square; a space outside the grid. */
+export function symbolAt(grid, square) {
+    return grid.lines[square.row]?.[square.column] ?? " ";
+}
+/** What stands at a square, from the legend; none outside, or for a symbol the legend does not name. */
+export function featureAt(grid, square) {
+    const symbol = symbolAt(grid, square);
+    return grid.features.find((feature) => feature.symbol === symbol);
+}
+/** The first square one can stand on, row by row from the top left, for examples; A1 when there is none. */
+export function firstOpenSquare(grid) {
+    for (let row = 0; row < grid.rows; row++) {
+        for (let column = 0; column < grid.columns; column++) {
+            if (closedSquare(grid, { column, row }) === undefined) {
+                return { column, row };
+            }
+        }
+    }
+    return { column: 0, row: 0 };
+}
+/** Why one cannot stand at a square (GRD-3): outside the map, a wall, what blocks, or a symbol the legend does not name; none when one can. */
+export function closedSquare(grid, square) {
+    const symbol = symbolAt(grid, square);
+    const feature = featureAt(grid, square);
+    if (square.column < 0 || square.row < 0 || square.column >= grid.columns || square.row >= grid.rows || symbol === " ") {
+        return `${squareName(square)} is outside the map`;
+    }
+    if (feature === undefined) {
+        return `${squareName(square)} is ${symbol === unreadableSymbol ? "a square the map cannot read" : `${symbol}, which the legend does not name`}`;
+    }
+    return feature.blocks ? `${squareName(square)} is ${feature.symbol === "#" ? "a wall" : `${feature.name}, which blocks`}` : undefined;
+}
+/** Whether a written character makes one square: a letter or a sign, not a tab, nor what shows as one character but is written as two, as an emoji. */
+function isOneSquare(symbol) {
+    return symbol !== "\t" && symbol.length === 1 && !/\p{M}/u.test(symbol);
+}
+/** What to say of a written character that makes no square. */
+function notOneSquare(symbol) {
+    return symbol === "\t"
+        ? "The map has a tab, which is not a square: write a space for each square outside the map, and a symbol for each of its squares."
+        : `The map has ${symbol}, which is not one character a square: use a letter or a sign, such as T, and name it in the legend.`;
+}

package/dist/grid/index.d.ts

@@ -0,0 +1,2 @@
+export { builtIn, closedSquare, type Feature, featureAt, firstOpenSquare, flags, type Grid, mapBlock, readGrid, readSquare, type Square, squareName, symbolAt, withoutMapBlock } from "./grid.ts";
+export { coveredSquares, type Footprint, isNextTo, reachable, shortestWay, squaresApart, type StepCosts } from "./paths.ts";

package/dist/grid/index.js

@@ -0,0 +1,2 @@
+export { builtIn, closedSquare, featureAt, firstOpenSquare, flags, mapBlock, readGrid, readSquare, squareName, symbolAt, withoutMapBlock } from "./grid.js";
+export { coveredSquares, isNextTo, reachable, shortestWay, squaresApart } from "./paths.js";

package/dist/grid/paths.d.ts

@@ -0,0 +1,27 @@
+import { type Grid, type Square } from "./grid.ts";
+/** What a step costs, as the game says (GRD-4): a diagonal one, in squares, and the factor of difficult ground. */
+export interface StepCosts {
+    diagonal: number;
+    difficult: number;
+}
+/** Where one stands on a map (GRD-4): the square at the top left of its footprint, and the footprint's side in squares. */
+export interface Footprint {
+    square: Square;
+    side: number;
+}
+/** The shortest way from one square to another (GRD-4): the squares it steps on, the goal last, and what it costs; none when no way leads there on foot. */
+export declare function shortestWay(grid: Grid, from: Square, to: Square, costs: StepCosts): {
+    squares: Square[];
+    cost: number;
+} | undefined;
+/** The squares one reaches from a square spending at most `budget` (D-328), each with what reaching it costs; the start among them, at 0. */
+export declare function reachable(grid: Grid, from: Square, budget: number, costs: StepCosts): {
+    square: Square;
+    cost: number;
+}[];
+/** Whether two footprints stand next to each other, or on a square they share (GRD-5). */
+export declare function isNextTo(first: Footprint, second: Footprint): boolean;
+/** How far apart two footprints stand, in squares as the game counts them (D-328): 1 next to each other, 0 on a square they share. */
+export declare function squaresApart(first: Footprint, second: Footprint, costs: StepCosts): number;
+/** The squares a footprint covers, row by row from its top left. */
+export declare function coveredSquares(footprint: Footprint): Square[];

package/dist/grid/paths.js

@@ -0,0 +1,128 @@
+// The ways across a place's map (GRD-4): the shortest between two squares, a square at a time, round walls and what blocks and never across their corners;
+// the squares one reaches with what is left to spend; who stands next to whom, and how far apart. Costs are in squares, as the game counts them.
+import { closedSquare, featureAt } from "./grid.js";
+/** The shortest way from one square to another (GRD-4): the squares it steps on, the goal last, and what it costs; none when no way leads there on foot. */
+export function shortestWay(grid, from, to, costs) {
+    if (!isInside(grid, from) || !isInside(grid, to)) {
+        return undefined;
+    }
+    const [start, goal] = [indexOf(grid, from), indexOf(grid, to)];
+    const { cost, previous } = spread(grid, start, costs, Infinity, goal);
+    const total = cost.get(goal);
+    if (total === undefined) {
+        return undefined;
+    }
+    const squares = [];
+    for (let at = goal; at !== undefined && at !== start; at = previous.get(at)) {
+        squares.unshift(squareAt(grid, at));
+    }
+    return { squares, cost: total };
+}
+/** The squares one reaches from a square spending at most `budget` (D-328), each with what reaching it costs; the start among them, at 0. */
+export function reachable(grid, from, budget, costs) {
+    return isInside(grid, from) ? [...spread(grid, indexOf(grid, from), costs, budget).cost].map(([index, cost]) => ({ square: squareAt(grid, index), cost })) : [];
+}
+/** Whether two footprints stand next to each other, or on a square they share (GRD-5). */
+export function isNextTo(first, second) {
+    const [columns, rows] = apart(first, second);
+    return Math.max(columns, rows) <= 1;
+}
+/** How far apart two footprints stand, in squares as the game counts them (D-328): 1 next to each other, 0 on a square they share. */
+export function squaresApart(first, second, costs) {
+    const [columns, rows] = apart(first, second);
+    return Math.abs(columns - rows) + costs.diagonal * Math.min(columns, rows);
+}
+/** The squares a footprint covers, row by row from its top left. */
+export function coveredSquares(footprint) {
+    return Array.from({ length: footprint.side * footprint.side }, (_, index) => ({ column: footprint.square.column + (index % footprint.side), row: footprint.square.row + Math.floor(index / footprint.side) }));
+}
+// The eight steps around a square: the four sides first, then the corners.
+const directions = [[0, -1], [1, 0], [0, 1], [-1, 0], [1, -1], [1, 1], [-1, 1], [-1, -1]];
+/**
+ * Dijkstra from a square: what reaching each square costs, and the square it is reached from. A step goes to an open square around, never across the corner
+ * of a closed one; it costs 1, or the diagonal's cost, times the factor of difficult ground it enters. It stops past the budget, or at the goal.
+ */
+function spread(grid, start, costs, budget, goal) {
+    const open = Array.from({ length: grid.columns * grid.rows }, (_, index) => closedSquare(grid, squareAt(grid, index)) === undefined);
+    const factor = Array.from({ length: grid.columns * grid.rows }, (_, index) => (featureAt(grid, squareAt(grid, index))?.difficult ? costs.difficult : 1));
+    const isOpen = (column, row) => column >= 0 && row >= 0 && column < grid.columns && row < grid.rows && open[row * grid.columns + column];
+    const cost = new Map([[start, 0]]);
+    const previous = new Map();
+    const settled = new Set();
+    const queue = new CostQueue();
+    queue.push(start, 0);
+    for (let next = queue.pop(); next !== undefined; next = queue.pop()) {
+        const [at, spent] = next;
+        if (settled.has(at)) {
+            continue;
+        }
+        settled.add(at);
+        if (at === goal) {
+            break;
+        }
+        const { column, row } = squareAt(grid, at);
+        for (const [across, down] of directions) {
+            const [toColumn, toRow] = [column + across, row + down];
+            const diagonal = across !== 0 && down !== 0;
+            if (!isOpen(toColumn, toRow) || (diagonal && (!isOpen(toColumn, row) || !isOpen(column, toRow)))) {
+                continue;
+            }
+            const onto = toRow * grid.columns + toColumn;
+            const total = spent + (diagonal ? costs.diagonal : 1) * factor[onto];
+            if (total <= budget && total < (cost.get(onto) ?? Infinity)) {
+                cost.set(onto, total);
+                previous.set(onto, at);
+                queue.push(onto, total);
+            }
+        }
+    }
+    return { cost: new Map([...cost].filter(([index]) => settled.has(index) || index === goal)), previous };
+}
+/** The squares between two footprints, across and down: 0 where they overlap, 1 where they touch. */
+function apart(first, second) {
+    const gap = (start, side, otherStart, otherSide) => Math.max(0, otherStart - (start + side - 1), start - (otherStart + otherSide - 1));
+    return [gap(first.square.column, first.side, second.square.column, second.side), gap(first.square.row, first.side, second.square.row, second.side)];
+}
+function isInside(grid, square) {
+    return square.column >= 0 && square.row >= 0 && square.column < grid.columns && square.row < grid.rows;
+}
+function indexOf(grid, square) {
+    return square.row * grid.columns + square.column;
+}
+function squareAt(grid, index) {
+    return { column: index % grid.columns, row: Math.floor(index / grid.columns) };
+}
+/** Squares by what reaching them costs, the cheapest first, and between equals the first by row and column: a binary heap. */
+class CostQueue {
+    items = [];
+    push(index, cost) {
+        this.items.push([index, cost]);
+        for (let at = this.items.length - 1; at > 0 && this.before(at, (at - 1) >> 1); at = (at - 1) >> 1) {
+            this.swap(at, (at - 1) >> 1);
+        }
+    }
+    pop() {
+        const first = this.items[0];
+        const last = this.items.pop();
+        if (first === undefined || last === undefined || this.items.length === 0) {
+            return first;
+        }
+        this.items[0] = last;
+        for (let at = 0;;) {
+            const [left, right] = [at * 2 + 1, at * 2 + 2];
+            const least = [left, right].filter((child) => child < this.items.length).reduce((best, child) => (this.before(child, best) ? child : best), at);
+            if (least === at) {
+                return first;
+            }
+            this.swap(at, least);
+            at = least;
+        }
+    }
+    before(first, second) {
+        const [[firstIndex, firstCost], [secondIndex, secondCost]] = [this.items[first], this.items[second]];
+        return firstCost < secondCost || (firstCost === secondCost && firstIndex < secondIndex);
+    }
+    swap(first, second) {
+        [this.items[first], this.items[second]] = [this.items[second], this.items[first]];
+    }
+}

package/dist/images/images.d.ts

@@ -0,0 +1,26 @@
+/** The folder of a campaign or of a game system that holds the pictures of its pages. */
+export declare const imagesFolderName = "images";
+/** The largest picture a page takes, in bytes: a token or a portrait needs far less. */
+export declare const largestImage: number;
+/** The formats a picture can have, by the extension its file gets. */
+export declare const imageExtensions: readonly ["png", "jpg", "webp", "svg"];
+export type ImageExtension = (typeof imageExtensions)[number];
+/** A picture read from a file, or why it cannot be one. */
+export type ReadImage = {
+    bytes: Uint8Array;
+    extension: ImageExtension;
+} | {
+    problem: string;
+};
+/** Reads the picture at `path`, by what its bytes are rather than by its extension: PNG, JPEG, WebP or SVG, up to largestImage. */
+export declare function readImage(path: string): ReadImage;
+/** The file named `name` in the images folder of the first of `folders` that has one, looked for in the folders inside it too; undefined when none has it. */
+export declare function findImage(folders: string[], name: string): string | undefined;
+/** The file name a page's image field links, such as ettore.webp for [[ettore.webp]]; undefined when the value is not a link. */
+export declare function imageFileName(value: unknown): string | undefined;
+/** A name for a picture that tells nothing of its page, as the page asks for a stranger's (D-420): a hash of its bytes, with its extension. */
+export declare function hiddenImageName(path: string): string | undefined;
+/** The picture a hidden name stands for, among the images folders of `folders`; undefined when the name is not one, or no picture has it. */
+export declare function findHiddenImage(folders: string[], name: string): string | undefined;
+/** The link an image field holds for a file name, such as [[ettore.webp]]. */
+export declare function imageLink(fileName: string): string;

package/dist/images/images.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { basename, extname, join } from "node:path";
+import { files } from "../core/store.js";
+/** The folder of a campaign or of a game system that holds the pictures of its pages. */
+export const imagesFolderName = "images";
+/** The largest picture a page takes, in bytes: a token or a portrait needs far less. */
+export const largestImage = 5 * 1024 * 1024;
+/** The formats a picture can have, by the extension its file gets. */
+export const imageExtensions = ["png", "jpg", "webp", "svg"];
+/** Reads the picture at `path`, by what its bytes are rather than by its extension: PNG, JPEG, WebP or SVG, up to largestImage. */
+export function readImage(path) {
+    const bytes = files().bytes(path);
+    if (bytes === undefined) {
+        return { problem: `There is no file at ${path}: give the full path of the picture.` };
+    }
+    const extension = imageExtensions.find((candidate) => isFormat[candidate](bytes));
+    if (extension === undefined) {
+        return { problem: `${basename(path)} is not a PNG, JPEG, WebP or SVG picture: convert it to one of those, or give another file.` };
+    }
+    if (bytes.length > largestImage) {
+        return { problem: `${basename(path)} is ${megabytes(bytes.length)} MB, and a picture can be ${megabytes(largestImage)} MB at most: make it smaller (512 pixels a side are enough).` };
+    }
+    return { bytes, extension };
+}
+/** The file named `name` in the images folder of the first of `folders` that has one, looked for in the folders inside it too; undefined when none has it. */
+export function findImage(folders, name) {
+    const wanted = name.toLowerCase();
+    for (const folder of folders) {
+        const found = files().files(join(folder, imagesFolderName), (fileName) => fileName.toLowerCase() === wanted)[0];
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return undefined;
+}
+/** The file name a page's image field links, such as ettore.webp for [[ettore.webp]]; undefined when the value is not a link. */
+export function imageFileName(value) {
+    const match = typeof value === "string" ? /^\s*\[\[([^\]|#]+)(?:\|[^\]]*)?\]\]\s*$/.exec(value) : null;
+    return match === null ? undefined : match[1].trim();
+}
+/** A name for a picture that tells nothing of its page, as the page asks for a stranger's (D-420): a hash of its bytes, with its extension. */
+export function hiddenImageName(path) {
+    const bytes = files().bytes(path);
+    return bytes === undefined ? undefined : `${createHash("sha256").update(bytes).digest("hex").slice(0, 24)}${extname(path).toLowerCase()}`;
+}
+/** The picture a hidden name stands for, among the images folders of `folders`; undefined when the name is not one, or no picture has it. */
+export function findHiddenImage(folders, name) {
+    if (!/^[0-9a-f]{24}\.[a-z]+$/.test(name)) {
+        return undefined;
+    }
+    const extension = extname(name);
+    return folders.flatMap((folder) => files().files(join(folder, imagesFolderName), (fileName) => extname(fileName).toLowerCase() === extension))
+        .find((file) => hiddenImageName(file) === name);
+}
+/** The link an image field holds for a file name, such as [[ettore.webp]]. */
+export function imageLink(fileName) {
+    return `[[${fileName}]]`;
+}
+const isFormat = {
+    png: (bytes) => startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    jpg: (bytes) => startsWith(bytes, [0xff, 0xd8, 0xff]),
+    webp: (bytes) => ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 12) === "WEBP",
+    // An SVG is text: its root element comes after an XML declaration, a doctype or comments, if any.
+    svg: (bytes) => /^(?:)?\s*(?:<\?xml[^>]*>\s*)?(?:(?:<!--[\s\S]*?-->|<!DOCTYPE[^>]*>)\s*)*<svg[\s>]/i.test(new TextDecoder().decode(bytes.subarray(0, 4096))),
+};
+function startsWith(bytes, prefix) {
+    return prefix.every((byte, index) => bytes[index] === byte);
+}
+function ascii(bytes, start, end) {
+    return String.fromCharCode(...bytes.subarray(start, end));
+}
+function megabytes(size) {
+    return (size / 1024 / 1024).toFixed(1).replace(/\.0$/, "");
+}

package/dist/images/index.d.ts

@@ -0,0 +1 @@
+export { findHiddenImage, findImage, hiddenImageName, type ImageExtension, imageExtensions, imageFileName, imageLink, imagesFolderName, largestImage, type ReadImage, readImage } from "./images.ts";

package/dist/images/index.js

@@ -0,0 +1,2 @@
+// Pictures of pages: the formats a picture can have, and where the file a page links is (D-267). It knows no game.
+export { findHiddenImage, findImage, hiddenImageName, imageExtensions, imageFileName, imageLink, imagesFolderName, largestImage, readImage } from "./images.js";

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { getVersion } from "./core/version.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export { getVersion } from "./core/version.js";

package/dist/instructions/index.d.ts

@@ -0,0 +1,17 @@
+/** A part of the instructions as a layer gives it: its text, and whether it takes the place of the layers below instead of adding to them (D-121). */
+export interface PartLayer {
+    text: string;
+    replace: boolean;
+}
+/** The few lines that send a host to `instructions` and `status`: the MCP server's instructions, and the start of the campaign's AGENTS.md. */
+export declare function startInstructions(): string;
+/** The line that sends the master to the buttons, where the player sees them (D-148, D-279); for choices alone when the player rolls their own dice (ASK-8). */
+export declare function buttonsInstructions(physicalDice: boolean): string;
+/** The dashboard at its link, which the game is played with, and how the player uses it, for the master to offer it and help them (D-404). */
+export declare function dashboardInstructions(link: string): string;
+/** The game master's full instructions, as the `instructions` command gives them. */
+export declare function masterInstructions(): string;
+/** The core's text of a part of the instructions that a situation opens, such as combat (D-121); undefined when the core has none. */
+export declare function corePart(name: string): string | undefined;
+/** A part through its layers, from the core up: each adds its text to those below, or takes their place when it says so (D-121); undefined when none has it. */
+export declare function layeredPart(layers: (PartLayer | undefined)[]): string | undefined;

package/dist/instructions/index.js

@@ -0,0 +1,48 @@
+// The game master's instructions, read from this package wherever it is installed (D-97). Depends on nothing else in rpg-engine.
+import { readFileSync } from "node:fs";
+/** The few lines that send a host to `instructions` and `status`: the MCP server's instructions, and the start of the campaign's AGENTS.md. */
+export function startInstructions() {
+    return readInstructions("start.md");
+}
+/** The line that sends the master to the buttons, where the player sees them (D-148, D-279); for choices alone when the player rolls their own dice (ASK-8). */
+export function buttonsInstructions(physicalDice) {
+    return readInstructions(physicalDice ? "buttons-physical-dice.md" : "buttons.md");
+}
+/** The dashboard at its link, which the game is played with, and how the player uses it, for the master to offer it and help them (D-404). */
+export function dashboardInstructions(link) {
+    return readInstructions("dashboard.md").replace("{link}", link);
+}
+/** The game master's full instructions, as the `instructions` command gives them. */
+export function masterInstructions() {
+    return readInstructions("core.md");
+}
+/** The core's text of a part of the instructions that a situation opens, such as combat (D-121); undefined when the core has none. */
+export function corePart(name) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+        return undefined;
+    }
+    try {
+        return readInstructions(`${name}.md`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/** A part through its layers, from the core up: each adds its text to those below, or takes their place when it says so (D-121); undefined when none has it. */
+export function layeredPart(layers) {
+    let text;
+    for (const layer of layers) {
+        if (layer !== undefined) {
+            // A blank line between layers, so that a system's text never reads as the last item of the core's list.
+            text = layer.replace || text === undefined ? layer.text : `${text}\n\n${layer.text}`;
+        }
+    }
+    return text;
+}
+function readInstructions(name) {
+    // From src/instructions/ and from dist/instructions/ alike, the package's instructions/ folder is two levels up.
+    return readFileSync(new URL(`../../instructions/${name}`, import.meta.url), "utf8").replace(/\r\n/g, "\n").trim();
+}

package/dist/map/geometry.d.ts

@@ -0,0 +1,22 @@
+/** A point of the map, in metres east and north of its centre; west and south are negative. */
+export interface Point {
+    east: number;
+    north: number;
+}
+/** How to write a direction, for messages. */
+export declare const directionHelp = "one of the 16 points of the compass, as N, NNE, NE\u2026 or north, north-north-east, north-east\u2026";
+/** A direction in degrees clockwise from north, from one of the 16 points of the compass, as NE or north-east (also northeast, north east); undefined for anything else. */
+export declare function readDirection(text: string): number | undefined;
+/** The name of the point of the compass nearest to a direction: north-east for 40°. */
+export declare function directionName(degrees: number): string;
+/** The point at a distance from another in a direction (dead reckoning, D-259). */
+export declare function pointFrom(origin: Point, degrees: number, metres: number): Point;
+export declare function distanceBetween(first: Point, second: Point): number;
+/** The direction from one point to another, in degrees clockwise from north. */
+export declare function directionTo(from: Point, to: Point): number;
+/** The point that best fits several (D-259): their mean, which is nearest to all of them together. */
+export declare function meanPoint(points: Point[]): Point;
+/** The point a fraction of the way from one point to another. */
+export declare function pointAlong(from: Point, to: Point, fraction: number): Point;
+/** Where a segment crosses another, as the fraction of the way along the first; undefined when they do not cross, or run side by side. */
+export declare function crossingAlong(from: Point, to: Point, otherFrom: Point, otherTo: Point): number | undefined;

package/dist/map/geometry.js

@@ -0,0 +1,66 @@
+// Where things are on the world map (D-259): points in metres east and north of the map's centre, the 16 directions of the compass, distances, crossings.
+/** The 16 points of the compass, clockwise from north, as abbreviations and as names. */
+const abbreviations = ["N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE", "S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW"];
+const names = [
+    "north",
+    "north-north-east",
+    "north-east",
+    "east-north-east",
+    "east",
+    "east-south-east",
+    "south-east",
+    "south-south-east",
+    "south",
+    "south-south-west",
+    "south-west",
+    "west-south-west",
+    "west",
+    "west-north-west",
+    "north-west",
+    "north-north-west",
+];
+/** How to write a direction, for messages. */
+export const directionHelp = "one of the 16 points of the compass, as N, NNE, NE… or north, north-north-east, north-east…";
+/** A direction in degrees clockwise from north, from one of the 16 points of the compass, as NE or north-east (also northeast, north east); undefined for anything else. */
+export function readDirection(text) {
+    const plain = (name) => name.toLowerCase().replace(/[\s_-]+/g, "");
+    const written = plain(text);
+    const index = abbreviations.findIndex((abbreviation, position) => plain(abbreviation) === written || plain(names[position]) === written);
+    return index === -1 ? undefined : index * 22.5;
+}
+/** The name of the point of the compass nearest to a direction: north-east for 40°. */
+export function directionName(degrees) {
+    return names[Math.round((((degrees % 360) + 360) % 360) / 22.5) % 16];
+}
+/** The point at a distance from another in a direction (dead reckoning, D-259). */
+export function pointFrom(origin, degrees, metres) {
+    const radians = (degrees * Math.PI) / 180;
+    return { east: origin.east + metres * Math.sin(radians), north: origin.north + metres * Math.cos(radians) };
+}
+export function distanceBetween(first, second) {
+    return Math.hypot(second.east - first.east, second.north - first.north);
+}
+/** The direction from one point to another, in degrees clockwise from north. */
+export function directionTo(from, to) {
+    return ((Math.atan2(to.east - from.east, to.north - from.north) * 180) / Math.PI + 360) % 360;
+}
+/** The point that best fits several (D-259): their mean, which is nearest to all of them together. */
+export function meanPoint(points) {
+    return { east: points.reduce((sum, point) => sum + point.east, 0) / points.length, north: points.reduce((sum, point) => sum + point.north, 0) / points.length };
+}
+/** The point a fraction of the way from one point to another. */
+export function pointAlong(from, to, fraction) {
+    return { east: from.east + (to.east - from.east) * fraction, north: from.north + (to.north - from.north) * fraction };
+}
+/** Where a segment crosses another, as the fraction of the way along the first; undefined when they do not cross, or run side by side. */
+export function crossingAlong(from, to, otherFrom, otherTo) {
+    const [ax, ay, bx, by] = [to.east - from.east, to.north - from.north, otherTo.east - otherFrom.east, otherTo.north - otherFrom.north];
+    const denominator = ax * by - ay * bx;
+    if (Math.abs(denominator) < 1e-9) {
+        return undefined;
+    }
+    const [cx, cy] = [otherFrom.east - from.east, otherFrom.north - from.north];
+    const along = (cx * by - cy * bx) / denominator;
+    const across = (cx * ay - cy * ax) / denominator;
+    return along >= 0 && along <= 1 && across >= 0 && across <= 1 ? along : undefined;
+}