rpg-engine 0.0.0-stage → 0.1.0

package/dist/commands/rules.js

@@ -0,0 +1,194 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { houseRulesFolderName, readListSetting, readTextSetting, requireCampaign } from "../campaign/index.js";
+import { defineCommand } from "../core/registry.js";
+import { comparableText } from "../core/text.js";
+import { findPage, pageFileNamed, pageNamed as pageWithName, sectionTitles } from "../pages/index.js";
+import { bookTitles, findRules, hasAllWords, readRuleBook, shownRules } from "../rules/index.js";
+import { disagreementAdvice, houseRules, precedentRule } from "./game-rules.js";
+import { campaignSystem, campaignWorld, foreignLanguage } from "./game-world.js";
+// About how many words an answer shows: a section of the system has about 80 words in the middle (D-178).
+const answerWords = 800;
+// What the rules add when the text is the name of a page, which holds the answer: a spell, an item (D-195).
+const answerWordsBesidePage = 150;
+// How many more sections an answer names after those it shows.
+const namedSections = 8;
+export const rules = defineCommand({
+    name: "rules",
+    description: "Find the exact text of a rule: the campaign's house rules first, then the game system's rules, then the table's precedents. "
+        + "Use it whenever you are unsure how a rule works, before you rule and say what is at stake, and when the player questions a ruling. "
+        + "Give the book's words, such as grappled, opportunity attack or long rest; a heading, or headings joined by ›, reads that section.",
+    group: "game",
+    readOnly: true,
+    positionals: ["text"],
+    input: z.object({
+        text: z.string().optional().describe("the words of the rule, or the heading of a section; the chapters when left out"),
+    }),
+    run(input, context) {
+        const root = requireCampaign(context.folder);
+        const system = campaignSystem(root, context);
+        const named = readTextSetting(root, "system");
+        // Read one by one, as the system is (SYS-1): a mistake elsewhere in campaign.yaml does not stop the rules.
+        const precedents = readListSetting(root, "precedents");
+        const house = readRuleBook(join(root, houseRulesFolderName), houseRules);
+        const book = system === undefined ? [] : readRuleBook(join(system.folder, "rules"), system.name);
+        const text = input.text?.trim() ?? "";
+        const common = {
+            text,
+            system: system?.name,
+            missingSystem: named !== undefined && system === undefined ? named : undefined,
+            language: system === undefined ? undefined : foreignLanguage(system.language, readTextSetting(root, "language")),
+            houseRules: bookTitles(house),
+            chapters: chaptersOf(book),
+        };
+        if (text === "") {
+            return { ...common, house: undefined, found: undefined, precedents };
+        }
+        // One search over both, so that a word is rare or common among all the rules (RUL-5); the house rules come first. A page by that name holds the
+        // answer, and the rules add little.
+        const page = pageNamed(root, context, system, text);
+        // Or the sections of pages it names, as a class's features: Cleric › Domain Spells, or Domain Spells alone (RUL-6).
+        const pageSections = page === undefined ? sectionsNamed(root, context, text) : [];
+        const budget = page === undefined && pageSections.length === 0 ? answerWords : answerWordsBesidePage;
+        const found = findRules([...house, ...book], text);
+        const houseAnswer = answerOf(found.filter((finding) => finding.section.source === houseRules), budget);
+        const systemAnswer = answerOf(found.filter((finding) => finding.section.source !== houseRules), budget - houseAnswer.used);
+        const shownTitles = [...houseAnswer.shown, ...systemAnswer.shown].map((shown) => shown.path.at(-1) ?? "");
+        return {
+            ...common,
+            house: houseAnswer,
+            found: systemAnswer,
+            precedents: precedents.filter((precedent) => hasAllWords(precedent, text) || isAboutAny(precedent, text, shownTitles)),
+            page,
+            pageSections,
+        };
+    },
+    format(result) {
+        if (result.house === undefined || result.found === undefined) {
+            return [contents(result), precedentsLine(result.precedents), houseRulesLine(result.houseRules)].filter((line) => line !== "").join("\n");
+        }
+        const sections = [...shownBlocks(result.house, "house rule"), ...shownBlocks(result.found, result.system ?? "")];
+        const others = [...result.house.others, ...result.found.others];
+        const lines = [
+            missingSystemLine(result.missingSystem),
+            pageLine(result.page),
+            sectionsLine(result.pageSections),
+            ...sections,
+            others.length === 0 ? "" : `Also: ${others.slice(0, namedSections).join("; ")}. Read one by its heading.`,
+            sections.length === 0 ? notFound(result) : "",
+            precedentsLine(result.precedents),
+            result.precedents.length > 0 && result.found.shown.length > 0 ? disagreementAdvice : "",
+            houseRulesLine(result.houseRules),
+        ];
+        return lines.filter((line) => line !== "").join("\n\n");
+    },
+});
+/** Whether a precedent is about a rule that the search names, or about the title of a section shown: "Poisoned: …" goes with Poisoned (D-179). */
+function isAboutAny(precedent, text, titles) {
+    const rule = precedentRule(precedent);
+    return rule !== undefined && (hasAllWords(text, rule) || titles.some((title) => comparableText(rule) === comparableText(title)));
+}
+/**
+ * The page of the campaign, or else of the game system, whose name or alias is the text: it holds rules too, such as a spell or how long a potion takes to drink.
+ */
+function pageNamed(root, context, system, text) {
+    const page = pageFileNamed(root, text);
+    const systemPage = page === undefined && system !== undefined ? pageFileNamed(system.folder, text) : undefined;
+    if (page !== undefined) {
+        return page;
+    }
+    if (systemPage !== undefined) {
+        return { ...systemPage, system: system?.name };
+    }
+    // By an alias, as "Shield spell": the world knows them.
+    try {
+        const aliased = pageWithName(campaignWorld(root, context), text);
+        return aliased === undefined ? undefined : { name: aliased.name, type: aliased.type, system: aliased.system };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The sections of pages, the campaign's or else the game system's, that a text names: Page › Section, or a section's title alone (RUL-6). */
+function sectionsNamed(root, context, text) {
+    const titles = text.split(/\s*[›>/]\s*/).map((title) => title.trim().replace(/[.:]$/, "")).filter((title) => title !== "");
+    let pages;
+    // A world that cannot be read, or two pages with the first title's name, leave the rules to answer alone.
+    try {
+        const world = campaignWorld(root, context);
+        const named = titles.length > 1 ? findPage(world, titles[0]) : undefined;
+        pages = titles.length === 1 ? [...world.pages, ...(world.system?.pages ?? [])] : named === undefined ? [] : [named];
+    }
+    catch {
+        return [];
+    }
+    return pages.flatMap((page) => {
+        const section = sectionTitles(page.body).find((title) => comparableText(title) === comparableText(titles.at(-1) ?? ""));
+        return section === undefined ? [] : [{ page: page.name, section, type: page.type, system: page.system }];
+    });
+}
+/** "Domain Spells is a section of Cleric, a page of the system 5e (topic): show Cleric#Domain Spells reads it.": first, as for a page (RUL-6). */
+function sectionsLine(sections) {
+    const [first] = sections ?? [];
+    if (first === undefined || sections === undefined) {
+        return "";
+    }
+    if (sections.length === 1) {
+        return `${first.section} is a section of ${first.page}, a page of ${first.system === undefined ? "the campaign" : `the system ${first.system}`} (${first.type ?? "page"}): `
+            + `show ${first.page}#${first.section} reads it. What the rules say of it:`;
+    }
+    const more = sections.length > namedSections ? `, and ${sections.length - namedSections} more` : "";
+    return `${first.section} is a section of several pages: ${sections.slice(0, namedSections).map(({ page, section }) => `show ${page}#${section}`).join("; ")}${more}. What the rules say of it:`;
+}
+/** "Fireball is a page of the system 5e (topic): show Fireball reads it.": first, since the page holds the answer, and the rules after it add to it. */
+function pageLine(page) {
+    return page === undefined ? "" : `${page.name} is a page of ${page.system === undefined ? "the campaign" : `the system ${page.system}`} (${page.type ?? "page"}): show ${page.name} reads it. What the rules say of it:`;
+}
+function answerOf(found, words) {
+    const { shown, others, used } = shownRules(found, Math.max(words, 0));
+    return { shown: shown.map(({ section, text, parts }) => ({ path: section.path, text, parts })), others: others.map((section) => section.path.join(" › ")), used };
+}
+function shownBlocks(answer, source) {
+    return answer.shown.map((shown) => {
+        const parts = shown.parts.length === 0 ? "" : `\n(Its parts: ${shown.parts.join("; ")}. Read one by its heading.)`;
+        return `${shown.path.join(" › ")} (${source}):\n${shown.text}${parts}`;
+    });
+}
+/** The chapters of a game system with the sections each opens with: "Combat: The Order of Combat, Movement and Position, …". */
+function chaptersOf(book) {
+    const files = [...new Set(book.map((section) => section.file))];
+    return files.map((file) => {
+        const top = book.find((section) => section.file === file);
+        return top === undefined || top.parts.length === 0 ? file : `${file}: ${top.parts.join(", ")}`;
+    });
+}
+function contents(result) {
+    if (result.system === undefined) {
+        return missingSystemLine(result.missingSystem) || "The campaign has no game system: only its own rules can be read.";
+    }
+    const language = result.language === undefined ? "" : `, in ${result.language}`;
+    return result.chapters.length === 0 ? `The system ${result.system} has no rules to read.` : `The rules of the system ${result.system}${language}, by chapter:\n${result.chapters.join("\n")}`;
+}
+/** What rules says when no text matches: how to search the book, and, when no precedent holds and the system is there, how to record the ruling as one (D-179). */
+function notFound(result) {
+    if (result.precedents.length > 0) {
+        return `No text of the rules matches "${result.text}": the table's precedent below holds.`;
+    }
+    const chapters = result.chapters.map((chapter) => chapter.split(":")[0]);
+    const words = "the book's words, such as a condition, an action or a heading";
+    const search = result.language === undefined ? `Search with ${words}.` : `The system ${result.system} writes its rules in ${result.language}: search with ${words}.`;
+    const book = result.system === undefined || chapters.length === 0 ? "" : ` ${search} The chapters of ${result.system}: ${chapters.join(", ")}.`;
+    const name = result.language === undefined ? "the rule's name" : `the rule's name in ${result.language}`;
+    const precedent = result.system === undefined ? "" : ` If you rule without the text, tell the player it is your call, and add it to the precedents: `
+        + `config, setting precedents, add "<${name}>: what you said".`;
+    return `No rule matches "${result.text}".${book}${precedent}`;
+}
+function precedentsLine(precedents) {
+    return precedents.length === 0 ? "" : `Precedents: ${precedents.join("; ")}`;
+}
+function houseRulesLine(houseRules) {
+    return houseRules.length === 0 ? "" : `House rules of the campaign: ${houseRules.join(", ")}.`;
+}
+function missingSystemLine(missing) {
+    return missing === undefined ? "" : `The campaign's system, ${missing}, is not installed, so its rules cannot be read: validate says how to fix it.`;
+}

package/dist/commands/save.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import type { Save } from "../saves/index.ts";
+import { type ResetPoint, type SaveMode } from "./game-saves.ts";
+/** What save did: the list, a save made, or the game gone back to a save or to its start. */
+export type SaveResult = {
+    action: "list";
+    mode: SaveMode;
+    saves: Save[];
+} | {
+    action: "make";
+    save: Save;
+} | {
+    action: "load";
+    save: Save;
+    removed: Save[];
+    copy?: string;
+    finished: boolean;
+} | {
+    action: "reset";
+    to: ResetPoint;
+    save: Save;
+    removed: Save[];
+    copy?: string;
+    finished: boolean;
+} | {
+    action: "new chat";
+    save: string;
+};
+export declare const save: import("../core/registry.ts").Command<z.ZodObject<{
+    action: z.ZodDefault<z.ZodEnum<{
+        list: "list";
+        make: "make";
+        load: "load";
+        reset: "reset";
+        "new chat": "new chat";
+    }>>;
+    label: z.ZodOptional<z.ZodString>;
+    save: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodEnum<{
+        start: "start";
+        "session zero": "session zero";
+    }>>;
+}, z.core.$strip>, {
+    action: "list";
+    mode: SaveMode;
+    saves: Save[];
+} | {
+    action: "make";
+    save: Save;
+} | {
+    action: "load";
+    save: Save;
+    removed: Save[];
+    copy?: string;
+    finished: boolean;
+} | {
+    action: "reset";
+    to: ResetPoint;
+    save: Save;
+    removed: Save[];
+    copy?: string;
+    finished: boolean;
+} | {
+    action: "new chat";
+    save: string;
+}>;
+/** What the master hears of what the player did with the saves on the dashboard, at the head of their next call (D-359). */
+export declare function playerSaveNews(result: SaveResult): string;

package/dist/commands/save.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { requireCampaign } from "../campaign/index.js";
+import { defineCommand } from "../core/registry.js";
+import { campaignSaves, interruptedLoad, isPlayerDead, loadRefusal, loadRule, loadSave, makeSave, newChatBegun, newChatText, resetPoints, resetSave, saveMode, savesWhy, saveText, wentBackTo, } from "./game-saves.js";
+import { campaignWorld } from "./game-world.js";
+const actions = ["list", "make", "load", "reset", "new chat"];
+export const save = defineCommand({
+    name: "save",
+    description: "The saves of the campaign, made by themselves at the end of each scene. "
+        + "list gives them, with what loading may do under the campaign's saves setting; make saves when the player asks, only with saves free; "
+        + "load goes back to a save: with free to any, with checkpoint only to the last and only once the player character is dead, with permadeath never. "
+        + "reset starts the campaign over, in every mode, permadeath too. Going back removes what happened since, the later saves too: load or reset only when the player has said so. "
+        + "A load that stopped halfway is finished by save load. "
+        + "After going back the game goes on only in a new chat: new chat, once the player confirms this chat began after it, never in one that went on before. "
+        + "Example: action load, save last.",
+    group: "game",
+    positionals: ["action", "save"],
+    input: z.object({
+        action: z.enum(actions).default("list").describe("list, make, load, reset or new chat"),
+        label: z.string().optional().describe("make: a few words that name the save, such as before the duel"),
+        save: z.string().optional().describe("load: the number of a save, or last"),
+        to: z.enum(resetPoints).optional().describe("reset: start, the start of play with the same character (if left out), or session zero, to make the character again"),
+    }),
+    run(input, context) {
+        const root = requireCampaign(context.folder);
+        const mode = saveMode(root);
+        const saves = campaignSaves(root);
+        checkParameters(input);
+        if (input.action === "list") {
+            return { action: "list", mode, saves };
+        }
+        // The player confirms the chat began after going back: the game goes on in it (D-362).
+        if (input.action === "new chat") {
+            const back = wentBackTo(root);
+            if (back === undefined) {
+                throw new Error("The game did not go back since the last chat began: there is nothing to confirm. Go on with the story.");
+            }
+            newChatBegun(root);
+            return { action: "new chat", save: back };
+        }
+        if (input.action === "make") {
+            if (mode !== "free") {
+                throw new Error(`With saves ${mode}, a save is made by itself at the end of each scene; on request only with saves free, which the player may choose with config. Nothing changed.`);
+            }
+            return { action: "make", save: makeSave(root, context, input.label?.trim() === "" ? undefined : input.label?.trim(), "asked") };
+        }
+        // A load that stopped halfway is finished first, whatever the mode: it was allowed when it began (SAV-5); never in the place of a reset.
+        const interrupted = interruptedLoad(root);
+        if (interrupted !== undefined && input.action === "reset") {
+            throw new Error(`A load to ${saveText(interrupted)} stopped halfway: save load finishes it first, then reset. Nothing changed.`);
+        }
+        if (interrupted !== undefined) {
+            return { action: "load", save: interrupted, ...loadSave(root, context, interrupted), finished: true };
+        }
+        // The campaign starting over, from the start of play or from before session zero (SAV-5, D-359, D-361).
+        if (input.action === "reset") {
+            const to = input.to ?? "start";
+            const start = resetSave(saves, savesWhy(root), to);
+            if (start === undefined) {
+                throw new Error(to === "start"
+                    ? "There are no saves yet: the start is saved when the campaign enters play, and the end of each scene makes one. Nothing changed."
+                    : "There is no save before session zero: this campaign was first saved after it. Start over with reset, to start. Nothing changed.");
+            }
+            return { action: "reset", to, save: start, ...loadSave(root, context, start), finished: false };
+        }
+        const chosen = chosenSave(saves, input.save);
+        const refusal = loadRefusal(mode, saves, chosen, isPlayerDead(campaignWorld(root, context)));
+        if (refusal !== undefined) {
+            throw new Error(`${refusal} Nothing changed.`);
+        }
+        return { action: "load", save: chosen, ...loadSave(root, context, chosen), finished: false };
+    },
+    format(result) {
+        if (result.action === "new chat") {
+            return `The game goes on in this chat, from save ${result.save}, as status gives it: tell nothing of what came after.`;
+        }
+        if (result.action === "make") {
+            return `Saved: ${saveText(result.save)}.`;
+        }
+        if (result.action === "reset") {
+            const copy = result.copy === undefined ? "" : ` What the reset replaced is in .saves/${result.copy}, to undo it by hand.`;
+            return `${resetText(result.to, result.save)}, what happened since gone from the game, every later save too.${copy} ${newChatText}`;
+        }
+        if (result.action === "load") {
+            const removed = result.removed.length === 0 ? "" : ` The later saves are gone: ${result.removed.map((removed) => removed.number).join(", ")}.`;
+            const finished = result.finished ? "The load that had stopped halfway is finished. " : "";
+            const copy = result.copy === undefined ? "" : ` What the load replaced is in .saves/${result.copy}, to undo it by hand.`;
+            return `${finished}Back to ${saveText(result.save)}: the campaign's files are as they were then, and what happened since is gone from the game.${removed}${copy} ${newChatText}`;
+        }
+        const listed = result.saves.length === 0 ? "No saves yet: one is made at the end of each scene." : `Saves: ${result.saves.map(saveText).join(" · ")}.`;
+        return `${listed}\n${loadRule(result.mode)}`;
+    },
+});
+/** The save asked for, by its number or last. */
+function chosenSave(saves, asked) {
+    if (saves.length === 0) {
+        throw new Error("There are no saves yet: one is made at the end of each scene. Nothing changed.");
+    }
+    const wanted = asked === undefined || asked.trim().toLowerCase() === "last" ? saves.at(-1) : saves.find((candidate) => candidate.number === Number(asked.trim()));
+    const twins = wanted === undefined ? [] : saves.filter((candidate) => candidate.number === wanted.number);
+    if (twins.length > 1) {
+        throw new Error(`Two saves have the number ${wanted?.number}: ${twins.map((twin) => twin.file).join(" and ")}. Rename or remove the one that is a copy, in .saves. Nothing changed.`);
+    }
+    if (wanted === undefined) {
+        throw new Error(`There is no save "${asked}": give its number or last. Saves: ${saves.map(saveText).join(" · ")}.`);
+    }
+    return wanted;
+}
+function checkParameters(input) {
+    if (input.label !== undefined && input.action !== "make") {
+        throw new Error(`save ${input.action} does not take label: only make does.`);
+    }
+    if (input.save !== undefined && input.action !== "load") {
+        throw new Error(`save ${input.action} does not take save: only load does.`);
+    }
+    if (input.to !== undefined && input.action !== "reset") {
+        throw new Error(`save ${input.action} does not take to: only reset does.`);
+    }
+}
+/** What the master hears of what the player did with the saves on the dashboard, at the head of their next call (D-359). */
+export function playerSaveNews(result) {
+    switch (result.action) {
+        case "make":
+            return `The player saved on the dashboard: ${saveText(result.save)}.`;
+        case "load":
+            return `The player went back on the dashboard to save ${saveText(result.save)}: the campaign's files are as they were then, and what happened since is gone from the game, `
+                + `the later saves too. ${newChatText}`;
+        case "reset":
+            return `The player started the campaign over on the dashboard. ${resetText(result.to, result.save)}, what happened since gone from the game, every later save too. ${newChatText}`;
+        case "new chat":
+            return `The player opened a new chat after going back to save ${result.save}, and confirmed it on the dashboard: the game goes on in it, from that save.`;
+        default:
+            return "";
+    }
+}
+/** "Back to the start, 1 - start: the campaign starts over from there with the same character": where a reset went. */
+function resetText(to, save) {
+    return to === "start"
+        ? `Back to the start, ${saveText(save)}: the campaign starts over from there with the same character`
+        : `Back to before session zero, ${saveText(save)}: the campaign starts over, the player character to make again in session zero`;
+}

package/dist/commands/scene.d.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+/** The order of turns, where the scene has one, and whether the turn is the player's character's. */
+interface Turns {
+    order: string[];
+    round: number;
+    turn: string;
+    player: boolean;
+}
+/** Someone in the scene, with their counters. */
+interface Member {
+    name: string;
+    counters: Record<string, unknown>;
+    /** A character's effects with their end, such as "Poisoned until day 1, 19:00". */
+    effects?: string[];
+}
+/** Who of the party a scene brought into its place, and what that set off (CON-6). */
+interface Brought {
+    moved: string[];
+    notes: string[];
+}
+/** The save the end of a scene made, or why it made none (SAV-3). */
+interface Saved {
+    saved?: string;
+    unsaved?: string;
+}
+export declare const scene: import("../core/registry.ts").Command<z.ZodObject<{
+    action: z.ZodEnum<{
+        next: "next";
+        open: "open";
+        add: "add";
+        now: "now";
+        order: "order";
+        hostile: "hostile";
+        close: "close";
+        leave: "leave";
+        calm: "calm";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        travel: "travel";
+        rest: "rest";
+        other: "other";
+        combat: "combat";
+        social: "social";
+        exploration: "exploration";
+        challenge: "challenge";
+    }>>;
+    place: z.ZodOptional<z.ZodString>;
+    with: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    creatures: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodRecord<z.ZodString, z.ZodNumber>]>>;
+    who: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    order: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    now: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    seen: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+}, z.core.$strip>, ({
+    action: "open";
+    title: string;
+    type: string;
+    opened?: string;
+    place?: string;
+    members: Member[];
+    around: string;
+    part: string;
+} & Brought) | ({
+    action: "add";
+    title: string;
+    place?: string;
+    members: Member[];
+    ordered: boolean;
+    seen?: Record<string, string>;
+} & Brought) | {
+    action: "leave";
+    left: Member[];
+    turns?: Turns;
+    noTurns: boolean;
+    ended: string[];
+    acting?: string;
+} | ({
+    action: "order" | "next";
+    noTurn: string[];
+    ended: string[];
+    acting?: string;
+} & Turns) | {
+    action: "now";
+    title: string;
+    now: string;
+} | {
+    action: "hostile" | "calm";
+    title: string;
+    marked: string[];
+    hostile: string[];
+} | ({
+    action: "close";
+    title?: string;
+    rounds?: number;
+    copies: Member[];
+    gone?: Member[];
+    unreadable?: string;
+    ended: string[];
+    endless: string[];
+    rewards?: string[];
+    quests: string[];
+} & Saved)>;
+export {};