rpg-engine 0.0.0-stage → 0.1.1

package/dist/commands/game-saves.js

@@ -0,0 +1,249 @@
+// The saves of a campaign as commands use them (D-54, D-55): which files a save holds, a save made at the end of a scene or when asked, and given back.
+import { join, relative, resolve, sep } from "node:path";
+import { campaignFileName, hostFileNames, readSettings } from "../campaign/index.js";
+import { filesIn } from "../core/files.js";
+import { appendLogEntry, logFileName, logLine, readLog } from "../core/log.js";
+import { files, isInside } from "../core/store.js";
+import { locate } from "../pages/index.js";
+import { packFiles, readSaves, saveFileName, unpackFiles } from "../saves/index.js";
+import { formatGameDate } from "../time/index.js";
+import { playerCharacter } from "./game-knowledge.js";
+import { newDatedLogEntry, readPresent } from "./game-time.js";
+import { campaignWorld } from "./game-world.js";
+/** The folder of the saves, at the top of the campaign. */
+export const savesFolderName = ".saves";
+// The mark of a load under way, with the number of its save: while it is there, save load finishes it (SAV-5).
+const loadingMarkName = "loading.txt";
+// The mark of a load done, with its save: the chat that was going on remembers what is gone, and only a new chat goes on (SAV-5, D-361).
+const newChatMarkName = "new chat.txt";
+/** The points the campaign starts over from (D-361): the start of play, with the same character, or before session zero, to make one again. */
+export const resetPoints = ["start", "session zero"];
+/** What the master does once the game went back: this chat remembers what is gone, so a new one goes on (D-361). */
+export const newChatText = "This chat remembers what is gone: ask the player to open a new chat (/clear in Claude Code, a new conversation elsewhere) and to write continua "
+    + "there. Nothing goes on in this one.";
+const hostNames = new Set(hostFileNames.map((name) => name.toLowerCase()));
+/** The campaign's mode of saves (SAV-1); checkpoint until the setup asks it. A campaign.yaml that cannot be read stops the command, with how to fix it. */
+export function saveMode(root) {
+    return readSettings(root).saves ?? "checkpoint";
+}
+/** The saves of the campaign, in order. */
+export function campaignSaves(root) {
+    return readSaves(files().entries(join(root, savesFolderName)).filter((entry) => !entry.isFolder).map((entry) => entry.name));
+}
+/** Whether the player character is dead: every one the campaign has, when it has one. Then no save is made, since going back is what one is for (SAV-3). */
+export function isPlayerDead(world) {
+    const players = world.pages.filter((page) => page.type === "character" && page.fields.role === "pc");
+    return players.length > 0 && players.every((page) => page.fields.status === "dead");
+}
+/** The save whose load stopped halfway, which save load finishes (SAV-5); undefined when none did. */
+export function interruptedLoad(root) {
+    const mark = files().bytes(join(root, savesFolderName, loadingMarkName));
+    const number = mark === undefined ? undefined : Number(new TextDecoder().decode(mark).trim());
+    return campaignSaves(root).find((save) => save.number === number);
+}
+/**
+ * Makes a save, numbered after the last and named by the game date and `label` (SAV-3, SAV-4): the game's files as the disk has them, with the public line of
+ * the save already in the log; the line is written once the zip is. Fails, writing nothing, when the zip cannot be written.
+ */
+export function makeSave(root, context, label, why) {
+    const number = (campaignSaves(root).at(-1)?.number ?? 0) + 1;
+    const date = readPresent(root).date;
+    const file = saveFileName(number, [date === undefined ? undefined : formatGameDate(date), label]);
+    const place = partyPlace(root, context);
+    const entry = newDatedLogEntry(root, context, "saved", "public", { save: number, label, why, ...(place === undefined ? {} : { place }) });
+    const held = gameFileBytes(root);
+    held[logFileName] = joinBytes(held[logFileName], new TextEncoder().encode(logLine(entry)));
+    files().writeBytes(join(root, savesFolderName, file), packFiles(held));
+    appendLogEntry(root, entry);
+    return readSaves([file])[0];
+}
+/**
+ * Gives the campaign back as a save holds it (SAV-5): its game files as they were, but campaign.yaml, its settings, as it is now (D-360), those made since
+ * removed, and the later saves removed; then a public line in the log, and the mark that the chat going on must give way to a new one (D-361). What it removes or rewrites goes first into `before load NNN.zip`, never in place of an older one, so that a load can be undone by hand. A save that
+ * cannot be read, holds a file outside the game's or no campaign.yaml is refused before anything is written; a load that stops halfway leaves its mark, and save
+ * load finishes it. Returns the saves removed and the copy made, none when it finishes a load.
+ */
+export function loadSave(root, context, save) {
+    const settings = resolve(root, campaignFileName);
+    const targets = Object.entries(readSave(root, save)).map(([path, bytes]) => ({ path: resolve(root, ...path.split("/")), bytes }))
+        .map((target) => (target.path === settings ? { ...target, bytes: files().bytes(settings) ?? target.bytes } : target));
+    const stranger = targets.find((target) => !isGameFile(root, target.path));
+    if (stranger !== undefined) {
+        throw new Error(`${save.file} holds ${relative(root, stranger.path)}, which is not one of the game's files: it was not made by rpg. Nothing changed; load another save.`);
+    }
+    if (!targets.some((target) => target.path === settings)) {
+        throw new Error(`${save.file} holds no ${campaignFileName}: it is not a whole save made by rpg. Nothing changed; load another save.`);
+    }
+    const folder = join(root, savesFolderName);
+    const later = campaignSaves(root).filter((other) => other.number > save.number);
+    const kept = new Set(targets.map((target) => target.path));
+    const step = (path, work) => {
+        try {
+            work();
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`Loading ${saveText(save)} stopped at ${relative(root, path)}: ${reason}. Close what holds that file, or let it be written, then call save load again: it finishes the load.`);
+        }
+    };
+    const copy = interruptedLoad(root) === undefined ? freeCopyName(root, save) : undefined;
+    if (copy !== undefined) {
+        step(join(folder, copy), () => files().writeBytes(join(folder, copy), packFiles(gameFileBytes(root))));
+        step(join(folder, loadingMarkName), () => files().writeBytes(join(folder, loadingMarkName), new TextEncoder().encode(String(save.number))));
+    }
+    for (const path of gameFiles(root).filter((candidate) => !kept.has(resolve(candidate)))) {
+        step(path, () => files().remove(path));
+    }
+    for (const target of targets) {
+        step(target.path, () => files().writeBytes(target.path, target.bytes));
+    }
+    for (const other of later) {
+        step(join(folder, other.file), () => files().remove(join(folder, other.file)));
+    }
+    appendLogEntry(root, newDatedLogEntry(root, context, "save-loaded", "public", { save: save.number, label: save.label, removed: later.length === 0 ? undefined : later.map((other) => other.number) }));
+    files().remove(join(folder, loadingMarkName));
+    files().writeBytes(join(folder, newChatMarkName), new TextEncoder().encode(saveText(save)));
+    return { removed: later, copy };
+}
+/** The save the game went back to, until the player confirms a new chat: the chat that went on before remembers what is gone (D-361, D-362). */
+export function wentBackTo(root) {
+    const mark = files().bytes(join(root, savesFolderName, newChatMarkName));
+    return mark === undefined ? undefined : new TextDecoder().decode(mark).trim();
+}
+/** The player confirmed a new chat: the game goes on in it (D-362). */
+export function newChatBegun(root) {
+    files().remove(join(root, savesFolderName, newChatMarkName));
+}
+/** Why each save was made, by its number, as its line in the log says: start, session zero, scene closed or asked. */
+export function savesWhy(root) {
+    return new Map(readLog(root).filter((entry) => entry.type === "saved").map((entry) => {
+        const data = entry.data;
+        return [Number(data.save), String(data.why ?? "")];
+    }));
+}
+/**
+ * The save a reset goes back to (D-361): the one before session zero, or the start of play, else, in a campaign older than the start's save, the first one
+ * made after session zero; undefined when there is none.
+ */
+export function resetSave(saves, why, to) {
+    return to === "session zero"
+        ? saves.find((save) => why.get(save.number) === "session zero")
+        : (saves.find((save) => why.get(save.number) === "start") ?? saves.find((save) => why.get(save.number) !== "session zero"));
+}
+/** "before load 003.zip", or "before load 003 (2).zip" when that one is there: a copy before a load never takes the place of another. */
+function freeCopyName(root, save) {
+    const taken = new Set(files().entries(join(root, savesFolderName)).map((entry) => entry.name.toLowerCase()));
+    const base = `before load ${String(save.number).padStart(3, "0")}`;
+    for (let count = 1;; count++) {
+        const name = count === 1 ? `${base}.zip` : `${base} (${count}).zip`;
+        if (!taken.has(name.toLowerCase())) {
+            return name;
+        }
+    }
+}
+/** "3 - day 2, 06.10 - Scontro all'ossario": a save as outputs name it. */
+export function saveText(save) {
+    return `${save.number} - ${save.label}`;
+}
+/**
+ * What the death of the last living player character allows (D-55, SAV-7): the save it may go back to, as the mode says, so that the master offers only what
+ * exists; none when campaign.yaml cannot be read, which other outputs say.
+ */
+export function deathNotes(root, name) {
+    let mode;
+    try {
+        mode = saveMode(root);
+    }
+    catch {
+        return [];
+    }
+    const last = campaignSaves(root).at(-1);
+    // Under permadeath, starting over is there once a start was saved (D-359).
+    if (mode === "permadeath") {
+        return resetSave(campaignSaves(root), savesWhy(root), "start") === undefined
+            ? [`${name} is dead, and with saves permadeath the game never goes back: offer the player a new character, if they want to go on.`]
+            : [
+                `${name} is dead, and with saves permadeath the game never goes back: offer the player a new character, or the campaign started over from its start, `
+                    + "if they want to go on; save reset only once they choose it.",
+            ];
+    }
+    if (last === undefined) {
+        return [`${name} is dead, and there is no save to go back to yet: offer the player a new character, if they want to go on.`];
+    }
+    const which = mode === "checkpoint" ? `the last save, ${saveText(last)}` : `a save, the last being ${saveText(last)} (save list gives every one)`;
+    return [`${name} is dead. With saves ${mode}, offer the player to go back to ${which}, or a new character; save load only once they choose it.`];
+}
+/** The files a save holds, by their path inside it; refused, with what to do, when the zip cannot be read. */
+function readSave(root, save) {
+    try {
+        return unpackFiles(files().bytes(join(root, savesFolderName, save.file)) ?? new Uint8Array());
+    }
+    catch (error) {
+        throw new Error(`${save.file} cannot be read as a save (${error instanceof Error ? error.message : String(error)}): it is broken, or was not made by rpg. Nothing changed; load another save.`);
+    }
+}
+/** The game's files with their bytes as the disk has them now, by their path inside a save. */
+function gameFileBytes(root) {
+    return Object.fromEntries(gameFiles(root).map((path) => [relative(root, path).split(sep).join("/"), files().bytes(path) ?? new Uint8Array()]));
+}
+/**
+ * The files a save holds (SAV-2), as the disk has them, not as a session last saw them: every file of the campaign but those of the AI hosts and those under a
+ * name with a dot at its top, as .saves, .git, .obsidian.
+ */
+function gameFiles(root) {
+    return files().entries(root).filter((entry) => isGameName(entry.name)).flatMap((entry) => {
+        const path = join(root, entry.name);
+        return entry.isFolder ? filesIn(path, () => true) : [path];
+    });
+}
+/** Whether a path is one of the game's files: in the campaign, not the host's nor under a name with a dot at its top (SAV-2). */
+export function isGameFile(root, path) {
+    return isInside(root, path) && isGameName(relative(root, path).split(sep)[0]);
+}
+/** Whether a name at the top of a campaign is the game's: not the host's, in any case, as Windows reads them, and not starting with a dot. */
+function isGameName(name) {
+    return !name.startsWith(".") && !hostNames.has(name.toLowerCase());
+}
+function joinBytes(first, second) {
+    const joined = new Uint8Array((first?.length ?? 0) + second.length);
+    joined.set(first ?? new Uint8Array(), 0);
+    joined.set(second, first?.length ?? 0);
+    return joined;
+}
+/** What loading may do under each mode of saves (D-55); reset, back to the start, in every mode (D-359). */
+export function loadRule(mode) {
+    switch (mode) {
+        case "free":
+            return "With saves free, load goes back to any of them when the player asks, and make saves when they ask.";
+        case "checkpoint":
+            return "With saves checkpoint, load goes back to the last one, and only once the player character is dead, if the player wants.";
+        default:
+            return "With saves permadeath, the game never goes back, but to its start with reset when the player wants to start over. "
+                + "If something broke outside the story, the player may unzip a save from .saves by hand.";
+    }
+}
+/** Why the mode of saves does not allow going back to a save (D-55): permadeath never, checkpoint only to the last and once the player character is dead; undefined when it may. */
+export function loadRefusal(mode, saves, chosen, dead) {
+    if (mode === "permadeath") {
+        return loadRule(mode);
+    }
+    if (mode === "checkpoint" && !dead) {
+        return "With saves checkpoint, the game goes back only once the player character is dead, and they are alive: go on with the story.";
+    }
+    if (mode === "checkpoint" && chosen !== saves.at(-1)) {
+        return `With saves checkpoint, the game goes back only to the last save, ${saveText(saves.at(-1))}.`;
+    }
+    return undefined;
+}
+/** The place the player character is in, the nearest that holds it, which a save keeps for its picture, as in a video game (D-359); undefined in none. */
+function partyPlace(root, context) {
+    try {
+        const world = campaignWorld(root, context);
+        const character = playerCharacter(world);
+        return character === undefined ? undefined : [character, ...locate(world, character).chain].find((holder) => holder.type === "place")?.name;
+    }
+    catch {
+        // A world that does not read now never stops a save: it only has no place.
+        return undefined;
+    }
+}

package/dist/commands/game-scene.d.ts

@@ -0,0 +1,69 @@
+import type { Problem } from "../core/problem.ts";
+import { type Page, type World } from "../pages/index.ts";
+import { type Scene, type SceneCopy } from "../scene/index.ts";
+/** A scene that has been closed, as the log keeps it. */
+export interface ClosedScene {
+    title: string;
+    type: string;
+    summary: string;
+}
+/** The open scene, or the problem that keeps state.yaml from giving it; neither when no scene is open. */
+export declare function readOpenScene(root: string): {
+    scene?: Scene;
+    problem?: Problem;
+};
+/** The open scene; undefined when there is none. A scene that cannot be read stops the command, with how to fix it. */
+export declare function openScene(root: string): Scene | undefined;
+/** The scene as state.yaml holds it, unchecked: what is left of a scene that cannot be read. */
+export declare function rawScene(root: string): unknown;
+/** What a copy changed: all its fields but the creature it copies (D-110). */
+export declare function copyChanges(copy: SceneCopy): Record<string, unknown>;
+/** A copy seen as a page that derives from its creature (INH-14): what it changed are its fields, the scene is where it is written. */
+export declare function copyPage(name: string, copy: SceneCopy): Page;
+/** The creature a copy copies, as a link: one written by hand without brackets is a link all the same. */
+export declare function copyLink(copy: SceneCopy): string;
+/** A copy's counters as the outputs show them (INH-12): what it changed, and the current/max ones it reads from its creature. */
+export declare function copyCounters(world: World, copy: SceneCopy): Record<string, unknown>;
+/**
+ * The copy in the open scene or the page that `name` names, the copy first (INH-14); refused, with how to find it, when there is none.
+ * `partHint` says why a part of a page, such as Ennio#Storia, cannot be meant.
+ */
+export declare function pageOrCopy(world: World, open: {
+    scene?: Scene;
+    problem?: Problem;
+}, name: string, partHint: (page: string) => string): {
+    page: Page;
+    copy?: string;
+};
+/** The copy in the open scene that `name` names, ignoring case; undefined when none does. A page with the same name leaves unclear which one is meant: refused. */
+export declare function copyName(world: World, scene: Scene | undefined, name: string): string | undefined;
+/**
+ * A creature whose copies are in the open scene, directly or through a variant, gives them what they do not change: what is meant for a copy must not land on it (INH-10, INH-11).
+ * A scene that cannot be read may hold copies of any creature.
+ */
+export declare function checkNotCopied(world: World, open: {
+    scene?: Scene;
+    problem?: Problem;
+}, page: Page): void;
+/** Refuses to change a page of the game system (SYS-6): the same call goes to one of its copies in the open scene; with none, how one enters the story. */
+export declare function checkNotSystemPage(world: World, open: {
+    scene?: Scene;
+}, page: Page): void;
+/**
+ * "in the files Ettore is in Mulino abbandonato: if they are in Ossario, move, page Ettore, to Ossario; if they left the scene, scene leave Ettore": the living members
+ * of the party in a scene whom the files put elsewhere, as a hand-made change may leave them (CON-8). Empty when there are none, or the scene is a travel one.
+ */
+export declare function partyAwayText(world: World, scene: Scene): string;
+/** Writes a whole new scene into state.yaml, or, undefined, removes it when the scene closes. */
+export declare function saveScene(root: string, scene: Scene | undefined): void;
+/** Changes values inside the open scene, each at its path, such as ["copies", "Annegato 1", "hp"]; the rest of the scene stays as it is. */
+export declare function updateScene(root: string, changes: [string[], unknown][]): void;
+/**
+ * What happened in the open scene since it opened, from the log, round by round, with every why (D-266, SCN-10): what a master who starts a new chat in the
+ * middle of a fight reads before the recap. Where each one stands is never written, and the text says so.
+ */
+export declare function openSceneLog(root: string, scene: Scene): string;
+/** The scenes closed so far, newest first, from the log; lines written wrongly by hand are left out. */
+export declare function closedScenes(root: string): ClosedScene[];
+/** The problems of the open scene: a scene that cannot be read, links to pages that do not exist, copies named like pages. A state.yaml that cannot be read at all is reported with the game date. */
+export declare function sceneProblems(root: string, world: World): Problem[];

package/dist/commands/game-scene.js

@@ -0,0 +1,285 @@
+// The open scene as several commands use it: read from state.yaml, written back, and checked against the world.
+import { z } from "zod";
+import { changeStateAt, readStateValues } from "../campaign/index.js";
+import { readLog } from "../core/log.js";
+import { sameName } from "../core/text.js";
+import { baseChain, findPage, isEmptyField, isInParty, kindMessage, locate, pagesWithName, parsePageReference, readOnlyMessage, systemFirstFix, systemLabel, systemPageNamed } from "../pages/index.js";
+import { readScene } from "../scene/index.js";
+import { missingSystemHint } from "./game-world.js";
+import { countersText, pageCounters } from "./page-counters.js";
+const closedSceneSchema = z.looseObject({ title: z.string(), type: z.string(), summary: z.string() });
+/** The open scene, or the problem that keeps state.yaml from giving it; neither when no scene is open. */
+export function readOpenScene(root) {
+    let value;
+    try {
+        value = rawScene(root);
+    }
+    catch (error) {
+        return { problem: { message: error instanceof Error ? error.message : String(error), fix: "fix state.yaml by hand" } };
+    }
+    if (isEmptyField(value)) {
+        return {};
+    }
+    try {
+        return { scene: readScene(value) };
+    }
+    catch (error) {
+        const message = `The open scene in state.yaml is not valid: ${error instanceof Error ? error.message : String(error)}`;
+        return { problem: { path: "state.yaml", message, fix: "close it with scene close and a summary, then open it again" } };
+    }
+}
+/** The open scene; undefined when there is none. A scene that cannot be read stops the command, with how to fix it. */
+export function openScene(root) {
+    const { scene, problem } = readOpenScene(root);
+    if (problem !== undefined) {
+        throw new Error(`${problem.message} To fix it, ${problem.fix}.`);
+    }
+    return scene;
+}
+/** The scene as state.yaml holds it, unchecked: what is left of a scene that cannot be read. */
+export function rawScene(root) {
+    return readStateValues(root).scene;
+}
+/** What a copy changed: all its fields but the creature it copies (D-110). */
+export function copyChanges(copy) {
+    return Object.fromEntries(Object.entries(copy).filter(([field]) => field !== "creature"));
+}
+/** A copy seen as a page that derives from its creature (INH-14): what it changed are its fields, the scene is where it is written. */
+export function copyPage(name, copy) {
+    return { name, type: "creature", path: "state.yaml", fields: { creature: copyLink(copy), ...copyChanges(copy) }, body: "" };
+}
+/** The creature a copy copies, as a link: one written by hand without brackets is a link all the same. */
+export function copyLink(copy) {
+    return `[[${parsePageReference(copy.creature).name}]]`;
+}
+/** A copy's counters as the outputs show them (INH-12): what it changed, and the current/max ones it reads from its creature. */
+export function copyCounters(world, copy) {
+    return pageCounters(world, copyPage("copy", copy));
+}
+/**
+ * The copy in the open scene or the page that `name` names, the copy first (INH-14); refused, with how to find it, when there is none.
+ * `partHint` says why a part of a page, such as Ennio#Storia, cannot be meant.
+ */
+export function pageOrCopy(world, open, name, partHint) {
+    const reference = parsePageReference(name);
+    if (reference.section !== undefined) {
+        throw new Error(`Give the page without #${reference.section}: ${partHint(reference.name)}.`);
+    }
+    // A scene that cannot be read holds no copies here; validate reports it.
+    const copy = copyName(world, open.scene, reference.name);
+    if (open.scene !== undefined && copy !== undefined) {
+        return { page: copyPage(copy, open.scene.copies[copy]), copy };
+    }
+    const page = findPage(world, reference.name);
+    if (page === undefined) {
+        const copies = open.scene === undefined ? "" : ", nor a copy of that name in the open scene";
+        const unreadable = open.problem === undefined ? "" : " The open scene in state.yaml cannot be read: validate shows how to fix it.";
+        throw new Error(`There is no page named ${reference.name}${copies}. Look for it with the find command.${unreadable}${missingSystemHint(world)}`);
+    }
+    return { page };
+}
+/** The copy in the open scene that `name` names, ignoring case; undefined when none does. A page with the same name leaves unclear which one is meant: refused. */
+export function copyName(world, scene, name) {
+    const copy = scene === undefined ? undefined : sameName(Object.keys(scene.copies), name);
+    if (copy !== undefined && pagesWithName(world, copy).length > 0) {
+        throw new Error(`${copy} is both a copy in the open scene and a page, so it is not clear which one is meant. Close the scene, which removes the copy, or rename the page. Nothing changed.`);
+    }
+    return copy;
+}
+/**
+ * A creature whose copies are in the open scene, directly or through a variant, gives them what they do not change: what is meant for a copy must not land on it (INH-10, INH-11).
+ * A scene that cannot be read may hold copies of any creature.
+ */
+export function checkNotCopied(world, open, page) {
+    if (open.problem !== undefined && page.type === "creature") {
+        throw new Error(`${page.name} is a creature, and the open scene, which may hold its copies, cannot be read: ${open.problem.message} To fix it, ${open.problem.fix}. Nothing changed.`);
+    }
+    const copies = open.scene === undefined ? [] : copiesReadingFrom(world, open.scene, page);
+    if (copies.length > 0) {
+        throw new Error(`${page.name} has copies in the open scene, which read from it what they do not change: ${copies.join(", ")}. Change a copy; to change ${page.name} for all, close the scene first. Nothing changed.`);
+    }
+}
+/** Refuses to change a page of the game system (SYS-6): the same call goes to one of its copies in the open scene; with none, how one enters the story. */
+export function checkNotSystemPage(world, open, page) {
+    if (page.system === undefined) {
+        return;
+    }
+    const copies = open.scene === undefined ? [] : Object.entries(open.scene.copies).filter(([name, copy]) => baseChain(world, copyPage(name, copy)).includes(page)).map(([name]) => name);
+    if (copies.length > 0) {
+        throw new Error(`${page.name} is ${systemLabel(page)}, read-only: its copies in the open scene are ${copies.join(", ")}. Make the same call on the one you mean, such as page "${copies[0]}". Nothing changed.`);
+    }
+    throw new Error(page.type === "creature" ? `${kindMessage(page)} Nothing changed.` : readOnlyMessage(page, [], world));
+}
+/** The copies in the scene that read from a page, directly or through a variant, with their counters: "Annegato 1 (hp 22/22)". */
+function copiesReadingFrom(world, scene, page) {
+    return Object.entries(scene.copies).filter(([name, copy]) => baseChain(world, copyPage(name, copy)).includes(page)).map(([name, copy]) => {
+        const counters = countersText(copyCounters(world, copy));
+        return counters === "" ? name : `${name} (${counters})`;
+    });
+}
+/**
+ * "in the files Ettore is in Mulino abbandonato: if they are in Ossario, move, page Ettore, to Ossario; if they left the scene, scene leave Ettore": the living members
+ * of the party in a scene whom the files put elsewhere, as a hand-made change may leave them (CON-8). Empty when there are none, or the scene is a travel one.
+ */
+export function partyAwayText(world, scene) {
+    // Read without stopping at names two pages share, which validate reports.
+    const pageCalled = (link) => pagesWithName(world, parsePageReference(link).name)[0];
+    const place = scene.place === undefined ? undefined : pageCalled(scene.place);
+    const members = scene.with.map(pageCalled).filter((page) => page !== undefined && isInParty(page));
+    const away = place === undefined || scene.type === "travel" ? [] : members.filter((page) => !locate(world, page).chain.includes(place));
+    if (place === undefined || away.length === 0) {
+        return "";
+    }
+    // More than one name goes as a list, which the tools take as it is.
+    const names = away.length === 1 ? away[0].name : `[${away.map((page) => page.name).join(", ")}]`;
+    const where = away.map((page) => `${page.name} is in ${locate(world, page).chain.find((holder) => holder.type === "place")?.name ?? "no place"}`).join(", ");
+    return `in the files ${where}: if they are in ${place.name}, move, page ${names}, to ${place.name}; if they left the scene, scene leave, who ${names}`;
+}
+/** Writes a whole new scene into state.yaml, or, undefined, removes it when the scene closes. */
+export function saveScene(root, scene) {
+    changeStateAt(root, [[["scene"], scene]]);
+}
+/** Changes values inside the open scene, each at its path, such as ["copies", "Annegato 1", "hp"]; the rest of the scene stays as it is. */
+export function updateScene(root, changes) {
+    changeStateAt(root, changes.map(([path, value]) => [["scene", ...path], value]));
+}
+/**
+ * What happened in the open scene since it opened, from the log, round by round, with every why (D-266, SCN-10): what a master who starts a new chat in the
+ * middle of a fight reads before the recap. Where each one stands is never written, and the text says so.
+ */
+export function openSceneLog(root, scene) {
+    const entries = readLog(root);
+    // The last scene opened with its title, or the last opened when state.yaml was written by hand.
+    const titled = entries.findLastIndex((entry) => entry.type === "scene-opened" && entry.data.title === scene.title);
+    const opened = titled >= 0 ? titled : entries.findLastIndex((entry) => entry.type === "scene-opened");
+    const lines = [];
+    let round;
+    for (const entry of opened < 0 ? [] : entries.slice(opened + 1)) {
+        // A line first, as who left at the end of a round, then the round its turn moved to.
+        const line = sceneLogLine(entry.type, entry.data);
+        if (line !== "") {
+            lines.push(`- ${line}`);
+        }
+        if (entry.type === "scene-changed" && entry.data.round !== undefined && entry.data.round !== round) {
+            round = entry.data.round;
+            lines.push(`Round ${String(round)}:`);
+        }
+        // The first order of turns starts round 1 with its first, who acts before any turn passes (SCN-6).
+        if (entry.type === "scene-changed" && Array.isArray(entry.data.order) && round === undefined) {
+            round = 1;
+            lines.push("Round 1:");
+        }
+    }
+    const place = scene.place === undefined ? "" : ` at ${parsePageReference(scene.place).name}`;
+    return [
+        `${scene.title} (${scene.type}, open)${place}: what happened since it opened, from the log.`,
+        ...(lines.length === 0 ? ["Nothing yet."] : lines),
+        "Where each one stands is not kept: leave it out of a recap, and ask the player only when it matters to their next move.",
+    ].join("\n");
+}
+/** The scenes closed so far, newest first, from the log; lines written wrongly by hand are left out. */
+export function closedScenes(root) {
+    return readLog(root).filter((entry) => entry.type === "scene-closed").flatMap((entry) => {
+        const parsed = closedSceneSchema.safeParse(entry.data);
+        return parsed.success ? [parsed.data] : [];
+    }).reverse();
+}
+/** The problems of the open scene: a scene that cannot be read, links to pages that do not exist, copies named like pages. A state.yaml that cannot be read at all is reported with the game date. */
+export function sceneProblems(root, world) {
+    try {
+        readStateValues(root);
+    }
+    catch {
+        return [];
+    }
+    const { scene, problem } = readOpenScene(root);
+    if (problem !== undefined) {
+        return [problem];
+    }
+    if (scene === undefined) {
+        return [];
+    }
+    const exists = (name) => pagesWithName(world, name).length > 0;
+    // A copy may copy a creature of the game system (SYS-7).
+    const creatureExists = (name) => exists(name) || systemPageNamed(world, name) !== undefined;
+    const links = [scene.place, ...scene.with].filter((link) => link !== undefined).map((link) => ({ link, found: exists }));
+    const copied = Object.values(scene.copies).map((copy) => ({ link: copy.creature, found: creatureExists }));
+    const missing = [...links, ...copied].filter(({ link, found }) => !found(parsePageReference(link).name)).map(({ link }) => ({
+        path: "state.yaml",
+        message: `The open scene links to ${link}, which does not exist.`,
+        fix: systemFirstFix(world) === undefined ? "create that page, or close the scene and open it again" : `${systemFirstFix(world)}; otherwise create that page`,
+    }));
+    const clashes = Object.keys(scene.copies).filter(exists).map((name) => ({
+        path: "state.yaml",
+        message: `${name} is both a copy in the open scene and a page, so change cannot tell which one is meant.`,
+        fix: "close the scene, which removes the copy, or rename the page",
+    }));
+    return [...missing, ...clashes];
+}
+/** One line of the log as the open scene's log gives it, or nothing for a line it leaves out, such as a turn passing, a save, or one written by hand without what it needs. */
+function sceneLogLine(type, data) {
+    const why = typeof data.why === "string" && data.why !== "" ? ` (${data.why})` : "";
+    const needs = {
+        roll: ["total"],
+        "counter-changed": ["page", "field", "before", "after"],
+        "effect-added": ["page", "effect"],
+        "effect-ended": ["page", "effect"],
+        moved: ["pages", "to"],
+        asked: ["question"],
+        "time-advanced": ["to"],
+        "page-created": ["page"],
+        "page-updated": ["page"],
+    };
+    if ((needs[type] ?? []).some((field) => data[field] === undefined || data[field] === null)) {
+        return "";
+    }
+    switch (type) {
+        case "roll":
+            return `${typeof data.who === "string" ? data.who : "roll"}: ${String(data.why ?? data.notation)}: ${String(data.total)}`;
+        case "counter-changed":
+            return `${String(data.page)}: ${String(data.field)} ${String(data.before)} → ${String(data.after)}${why}`;
+        case "effect-added":
+            return `${String(data.page)}: ${String(data.effect)}${why}`;
+        case "effect-ended":
+            return `${String(data.page)}: ${String(data.effect)} ended${why}`;
+        case "moved":
+            return `${namesText(data.pages)} to ${String(data.to)}${why}`;
+        case "asked":
+            return `asked the player: ${String(data.question)} → ${data.answer === undefined ? "no answer" : String(data.answer)}`;
+        case "time-advanced":
+            return `time to ${String(data.to)}${why}`;
+        case "page-created":
+        case "page-updated":
+            return `wrote ${String(data.page)}`;
+        case "scene-changed":
+            return sceneChangeLine(data);
+        case "scene-now":
+            return `now: ${String(data.now)}`;
+        default:
+            return "";
+    }
+}
+/** "left: Cultista 1 (hp 2/9)": who joined or left, the order, or the copies, as the open scene's log gives them; nothing for a turn passing. */
+function sceneChangeLine(data) {
+    const copies = data.copies !== null && typeof data.copies === "object" ? data.copies : {};
+    const withNumbers = (name) => {
+        const copy = copies[name];
+        const numbers = copy === null || typeof copy !== "object" ? [] : Object.entries(copy).filter(([field]) => field !== "creature").map(([field, value]) => `${field} ${String(value)}`);
+        return numbers.length === 0 ? name : `${name} (${numbers.join(", ")})`;
+    };
+    if (Array.isArray(data.order)) {
+        return `order: ${data.order.map(String).join(" · ")}`;
+    }
+    if (Array.isArray(data.left)) {
+        return `left: ${data.left.map((name) => withNumbers(String(name))).join(", ")}`;
+    }
+    const seen = data.seen !== null && typeof data.seen === "object" ? Object.entries(data.seen).map(([name, said]) => `${name} as ${String(said)}`) : [];
+    const joined = Array.isArray(data.added) && data.added.length > 0 ? [`joined: ${namesText(data.added)}`] : [];
+    if (joined.length > 0 || seen.length > 0) {
+        return [...joined, ...(seen.length === 0 ? [] : [`seen: ${seen.join(", ")}`])].join("; ");
+    }
+    return Object.keys(copies).length === 0 ? "" : `copies: ${Object.keys(copies).map(withNumbers).join(", ")}`;
+}
+function namesText(value) {
+    return Array.isArray(value) ? value.map(String).join(", ") : String(value);
+}

package/dist/commands/game-thresholds.d.ts

@@ -0,0 +1,13 @@
+import type { GameSystem } from "../systems/index.ts";
+/**
+ * The notes of the thresholds that a change of a field touches: it reaches the value, even going beyond it, takes more while at it, leaves it, or goes past it,
+ * as in "hp is at 0, 7 beyond: read rules "Dropping to 0 Hit Points"."; a value an effect gives says so. A threshold without a value gives its rule's text at
+ * every change, a house rule first (DAT-6).
+ */
+export declare function thresholdNotes(root: string, system: GameSystem | undefined, field: string, change: {
+    before: unknown;
+    after: unknown;
+    amount: {
+        beyond?: number;
+    };
+}, effect?: string): string[];