rpg-engine 0.0.0-stage → 0.1.0

package/dist/commands/game-positions.js

@@ -0,0 +1,244 @@
+// Positions in play (D-259, POS-1–POS-8): where a place is, its own position or one worked out; relations turned into a position; regions; what is near a point;
+// each on its map, with the coordinates its map uses (D-320).
+import { lengthHelp, readLength } from "../core/length.js";
+import { comparableText } from "../core/text.js";
+import { biomes, directionHelp, directionName, directionTo, distanceBetween, meanPoint, placeKinds, pointAlong, pointFrom, readDirection } from "../map/index.js";
+import { environmentAt, formatPosition, isEmptyField, locate, pageNamed, pagesWithName, parsePageReference, readPosition, readStops } from "../pages/index.js";
+import { mapKey, mapOf, sameFrame } from "./game-maps.js";
+import { lengthText, roadsOf } from "./game-roads.js";
+/** How to write a relation, for messages. */
+export const relationHelp = "a distance, a direction and a place with a position, such as 12 km NE of [[Guadoscuro]]";
+/**
+ * Where a page is on the map (POS-4): the first of its chain, itself first, with a position: its own; for a stop, on the line between the nearest stops of its
+ * road that have one, by the lengths; undefined when none has one. A character or an item is where the place that holds it is.
+ */
+export function positionOf(world, page) {
+    for (const holder of [page, ...locate(world, page).chain]) {
+        const position = placedPosition(world, holder);
+        if (position !== undefined) {
+            return position;
+        }
+    }
+    return undefined;
+}
+/** A place's own position, or the one its roads give it, rather than its container's: the places that show on the map. */
+export function placedPosition(world, page) {
+    return page.type !== "place" || page.system !== undefined ? undefined : placedOf(world).positions.get(page.path);
+}
+/**
+ * The position a write gives a place (POS-2): written as the engine writes it, or as relations, whose points are averaged, with the largest distance between
+ * them. When no place with the same coordinates has a position yet, the one a relation starts from becomes the centre of its map: `origin`, to write too. The
+ * places it is given from share their coordinates, and those of the place written when something already holds it (POS-8); a place nothing holds yet takes
+ * them, and `map` names the map to put it in. Refused with the fix otherwise.
+ */
+export function positionFromWrite(world, value, name) {
+    const own = readPosition(value);
+    if (own !== undefined) {
+        return { position: own, spread: 0 };
+    }
+    const texts = Array.isArray(value) ? value.map(String) : [String(value)];
+    const relations = texts.map((text) => relationOf(text));
+    const places = relations.map((relation) => referenceOf(world, relation.place, name));
+    const map = sharedMap(world, places, pageNamed(world, name), name);
+    const unplaced = places.filter((place) => positionOf(world, place) === undefined);
+    const known = world.pages.filter((page) => page.system === undefined && readPosition(page.fields.position) !== undefined && mapOf(world, page).frame === mapOf(world, places[0]).frame);
+    if (unplaced.length > 0 && (known.length > 0 || new Set(unplaced).size > 1 || unplaced.length < places.length)) {
+        const such = known.length === 0 ? "" : `, such as ${known.slice(0, 3).map((page) => page.name).join(", ")}`;
+        throw new Error(`${unplaced[0].name} has no position yet: give it one first, relative to a place that has one${such}, then write ${name}. Nothing changed.`);
+    }
+    const origin = unplaced[0];
+    const points = relations.map((relation, index) => pointFrom(positionOf(world, places[index]) ?? { east: 0, north: 0 }, relation.degrees, relation.metres));
+    const spread = Math.max(0, ...points.flatMap((point) => points.map((other) => distanceBetween(point, other))));
+    return { position: meanPoint(points), spread, ...(origin === undefined ? {} : { origin }), ...(map === undefined ? {} : { map }) };
+}
+/** The regions of the world (POS-6): places of the campaign with a radius and a position, their own or one their roads give them. */
+export function regionsOf(world) {
+    return placedOf(world).regions;
+}
+/** The smallest region of a map, by its key (POS-8), that covers a point (POS-6); undefined when none does. */
+export function regionAt(world, point, map = "") {
+    return regionsOf(world)
+        .filter((region) => mapKey(world, region.page) === map && distanceBetween(region.centre, point) <= region.radius)
+        .sort((first, second) => first.radius - second.radius)[0];
+}
+/**
+ * The places near a point (TRV-13): those with a position of their own or from their roads within 3 km, nearest first, at most 5, or else the nearest one; each
+ * as "Torre Mozza, 2.1 km north-east". Regions and roads are left out.
+ */
+export function nearPlaces(world, point, measures, map = "", except = []) {
+    const placed = placesByDistance(world, point, map, except);
+    const near = placed.filter((place) => place.distance <= 3000).slice(0, 5);
+    return (near.length > 0 ? near : placed.slice(0, 1)).map((place) => `${place.page.name}, ${relationText(point, place.position, measures)}`);
+}
+/** "12 km west of Guadoscuro": a point of a map told from its nearest place with a position, or that place's name at it; its position when there is none. */
+export function pointText(world, point, measures, map = "") {
+    const nearest = placesByDistance(world, point, map, [])[0];
+    if (nearest === undefined) {
+        return formatPosition(point);
+    }
+    const relation = relationText(nearest.position, point, measures);
+    return relation === "here" ? nearest.page.name : `${relation} of ${nearest.page.name}`;
+}
+/** "2.1 km north-east", from a point to another; "here" closer than 50 m. */
+export function relationText(from, to, measures) {
+    const distance = distanceBetween(from, to);
+    return distance < 50 ? "here" : `${lengthText(distance, measures)} ${directionName(directionTo(from, to))}`;
+}
+/**
+ * What write says when a place first comes on the map without a kind, a region apart, or becomes a region without a biome (POS-7): the names the map draws. `before`
+ * is the world before the write, `existing` the page as it was there.
+ */
+export function mapLookNotes(before, existing, after, page) {
+    const placed = (world, candidate) => candidate !== undefined && placedPosition(world, candidate) !== undefined;
+    const region = (world, candidate) => candidate !== undefined && regionsOf(world).some((found) => found.page.path === candidate.path);
+    const isRoad = page.fields.stops !== undefined;
+    const biome = environmentAt(after, page).some(({ entry }) => comparableText(entry.name) === "biome");
+    return [
+        !isRoad && !region(after, page) && isEmptyField(page.fields.kind) && placed(after, page) && !placed(before, existing)
+            ? `For the dashboard's map, give ${page.name} a kind, as set kind=${placeKinds[2]}: ${placeKinds.join(", ")}.`
+            : "",
+        region(after, page) && !region(before, existing) && !biome
+            ? `For the map, give ${page.name}'s environment a biome, as add environment="biome: ${biomes[0]}": ${biomes.join(", ")}; what it holds shares it.`
+            : "",
+    ].filter((note) => note !== "");
+}
+/** The roads shorter than the straight line between two of their stops that have a position of their own (POS-5): a length or a position is wrong. */
+export function shortRoadProblems(world) {
+    return shortRoads(world).map((short) => short.problem);
+}
+/** What write says of the roads a place's position or a road's stops make shorter than the straight line (POS-5): those of the page, or with it as a stop. */
+export function shortRoadNotes(world, page) {
+    const same = (name) => comparableText(name) === comparableText(page.name);
+    return shortRoads(world).filter((short) => [short.road, short.from, short.to].some(same)).map(({ problem }) => `${problem.message} Fix: ${problem.fix}.`);
+}
+/** The roads shorter than the straight line (POS-5): each stop with the next one that has a position, in order; with the road and the stops it is about. */
+function shortRoads(world) {
+    return [...roadsOf(world).pages.values()].flatMap((road) => {
+        const read = readStops(road.fields.stops);
+        if ("problem" in read) {
+            return [];
+        }
+        const placed = read.stops.flatMap((name, index) => {
+            const page = pagesWithName(world, name)[0];
+            const position = ownPositionNamed(world, name);
+            return position === undefined || page === undefined ? [] : [{ name, index, position, page }];
+        });
+        const along = (index) => read.lengths.slice(0, index).reduce((sum, length) => sum + length, 0);
+        return placed.slice(1).flatMap((stop, index) => {
+            const before = placed[index];
+            // A passage between maps measures nothing in a straight line (POS-8, ROA-8).
+            if (mapKey(world, before.page) !== mapKey(world, stop.page)) {
+                return [];
+            }
+            const [length, straight] = [along(stop.index) - along(before.index), distanceBetween(before.position, stop.position)];
+            const km = (metres) => Math.round(metres / 100) / 10;
+            return length >= straight * 0.99 ? [] : [{
+                    road: road.name,
+                    from: before.name,
+                    to: stop.name,
+                    problem: {
+                        path: road.path,
+                        message: `${road.name} is ${km(length)} km from ${before.name} to ${stop.name}, shorter than the ${km(straight)} km between them in a straight line: a length or a position is wrong.`,
+                        fix: `write ${road.name}, set stops again with the right lengths, or write the position of ${before.name} or ${stop.name} again`,
+                    },
+                }];
+        });
+    });
+}
+/** A relation as written (POS-2): a length in metric, a direction of the compass, "of" and a link; refused with how to write it. */
+function relationOf(text) {
+    const match = /^\s*(\d+(?:\.\d+)?\s*k?m)\s+(.+?)\s+of\s+(\[\[[^\]]+\]\])\s*$/i.exec(text);
+    const metres = match === null ? undefined : readLength(match[1]);
+    const degrees = match === null ? undefined : readDirection(match[2]);
+    if (match === null || metres === undefined || degrees === undefined) {
+        const why = match === null ? `write ${relationHelp}` : metres === undefined ? `write the distance ${lengthHelp}` : `the direction must be ${directionHelp}`;
+        throw new Error(`"${text}" is not a position: ${why}. Nothing changed.`);
+    }
+    return { metres, degrees, place: parsePageReference(match[3]).name };
+}
+/**
+ * The map whose coordinates the places a position is given from share (POS-8): refused when they do not, or when the place written is held where they are not;
+ * the map to put it in when nothing holds it yet and they are on a map a place holds, which write names.
+ */
+function sharedMap(world, places, written, name) {
+    const first = places[0];
+    const other = places.find((place) => !sameFrame(world, place, first));
+    if (other !== undefined) {
+        throw new Error(`${first.name} and ${other.name} are on maps with other coordinates: give the position of ${name} from places of one map. Nothing changed.`);
+    }
+    const map = mapOf(world, first);
+    const held = written !== undefined && (locate(world, written).chain.length > 0 || written.fields.map !== undefined);
+    if (written !== undefined && held && !sameFrame(world, written, first)) {
+        const where = mapOf(world, written).root?.name ?? "the main map";
+        throw new Error(`${name} is on ${where === "the main map" ? where : `the map of ${where}`}, ${first.name} on ${map.root === undefined ? "the main map" : `that of ${map.root.name}`}: give its position from a place of its map, or of one with the same coordinates. Nothing changed.`);
+    }
+    return held || written?.fields.map !== undefined ? undefined : map.root;
+}
+/** The place a relation starts from: a place of the campaign, not the place being written. */
+function referenceOf(world, name, written) {
+    const page = pageNamed(world, name);
+    if (page === undefined || page.type !== "place" || page.system !== undefined) {
+        throw new Error(`${name} is ${page === undefined ? "no page" : "not a place of the campaign"}: a position is given from a place that has one. Nothing changed.`);
+    }
+    if (comparableText(page.name) === comparableText(written)) {
+        throw new Error(`${written} cannot be placed from itself: give its position from another place. Nothing changed.`);
+    }
+    return page;
+}
+/**
+ * The positions and regions of a world, once for each world: the places' own positions, then each stop without one on the line between the nearest stops of its
+ * road that have one, by the lengths (POS-4), the first road that gives one; the regions among them (POS-6).
+ */
+function placedOf(world) {
+    let placed = known.get(world);
+    if (placed === undefined) {
+        placed = readPlaced(world);
+        known.set(world, placed);
+    }
+    return placed;
+}
+const known = new WeakMap();
+function readPlaced(world) {
+    const positions = new Map();
+    for (const page of world.pages.filter((candidate) => candidate.type === "place" && candidate.system === undefined)) {
+        const own = readPosition(page.fields.position);
+        if (own !== undefined) {
+            positions.set(page.path, own);
+        }
+    }
+    for (const road of roadsOf(world).pages.values()) {
+        const read = readStops(road.fields.stops);
+        const pages = "problem" in read ? [] : read.stops.map((name) => pagesWithName(world, name)[0]);
+        const owned = pages.map((page) => (page === undefined ? undefined : readPosition(page.fields.position)));
+        const along = (index) => ("problem" in read ? 0 : read.lengths.slice(0, index).reduce((sum, length) => sum + length, 0));
+        pages.forEach((page, index) => {
+            const before = owned.slice(0, index).findLastIndex((position) => position !== undefined);
+            const after = owned.findIndex((position, at) => at > index && position !== undefined);
+            // Only between stops of the same map: a passage between maps places nothing (POS-8).
+            const shared = page !== undefined && before !== -1 && after !== -1 && [pages[before], pages[after]].every((other) => other !== undefined && mapKey(world, page) === mapKey(world, other));
+            if (page !== undefined && page.type === "place" && !positions.has(page.path) && shared) {
+                const [from, to] = [owned[before], owned[after]];
+                positions.set(page.path, pointAlong(from, to, (along(index) - along(before)) / (along(after) - along(before))));
+            }
+        });
+    }
+    const regions = world.pages.flatMap((page) => {
+        const radius = isEmptyField(page.fields.radius) ? undefined : readLength(page.fields.radius);
+        const centre = radius === undefined ? undefined : positions.get(page.path);
+        return centre === undefined || radius === undefined || page.type !== "place" || page.system !== undefined ? [] : [{ page, centre, radius }];
+    });
+    return { positions, regions };
+}
+/** The places of a map with a position of their own or from their roads, nearest to a point first; regions and roads left out. */
+function placesByDistance(world, point, map, except) {
+    const { positions } = placedOf(world);
+    return world.pages.flatMap((page) => {
+        const position = positions.get(page.path);
+        const listed = position !== undefined && isEmptyField(page.fields.radius) && isEmptyField(page.fields.stops) && !except.includes(page) && mapKey(world, page) === map;
+        return listed ? [{ page, position, distance: distanceBetween(point, position) }] : [];
+    }).sort((first, second) => first.distance - second.distance);
+}
+function ownPositionNamed(world, name) {
+    const page = pagesWithName(world, name)[0];
+    return page?.type === "place" && page.system === undefined ? readPosition(page.fields.position) : undefined;
+}

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

@@ -0,0 +1,46 @@
+import type { Context } from "../core/context.ts";
+import type { Problem } from "../core/problem.ts";
+import { type Page, type World } from "../pages/index.ts";
+import { type GameDate } from "../time/index.ts";
+/** What a quest measures (D-367): its counters with a maximum, its clock with its name, its deadline with the game minutes left, and whether it is the main one. */
+export interface QuestMeasures {
+    main: boolean;
+    counters: {
+        field: string;
+        value: number;
+        max: number;
+    }[];
+    clock?: {
+        value: number;
+        max: number;
+        name?: string;
+    };
+    deadline?: {
+        date: string;
+        minutes?: number;
+    };
+}
+/** What a quest measures, as its fields write it; a field that does not read is left out, and validate says why. */
+export declare function questMeasures(page: Page, now: GameDate | undefined): QuestMeasures;
+/** "clues 3/5, I rapitori lasciano la torre 2/6, deadline day 27, 10:00 (in 1d 2h)": what a quest measures, in the chat's words; empty when nothing. */
+export declare function measuresText(measures: QuestMeasures): string;
+/**
+ * What status says of an open quest (D-239, D-369): whether it is the main one, what it measures, and what to do when every goal is ticked or its deadline
+ * passed: the story's end is the master's to say, never the engine's.
+ */
+export declare function openQuestText(page: Page, now: GameDate | undefined): string;
+/** What write says when it makes a quest (D-239): every goal ticked. */
+export declare function tickedQuestNotes(existing: Page | undefined, page: Page): string[];
+/** What scene close says of each open quest whose goals are all ticked, and write of the one it leaves so. */
+export declare function tickedQuestNote(page: Page): string;
+/**
+ * What write says as a quest opens, made open or opened from planned (D-367, D-369): what the player's journal shows of it, so that the master writes it there.
+ * Kept in the output, never in the instructions, since only who opens a quest needs it.
+ */
+export declare function newQuestNotes(existing: Page | undefined, page: Page): string[];
+/** A public line as a quest the character knows is taken, done or failed (D-369): the story tells it. */
+export declare function logQuestChange(root: string, context: Context, existing: Page | undefined, page: Page): void;
+/** The quests whose deadline or clock does not read (D-369): the journal leaves them out, so validate says how to write them. */
+export declare function questProblems(world: World): Problem[];
+/** Whether a page is an open quest whose goals are all ticked. */
+export declare function isTickedOpenQuest(page: Page | undefined): boolean;

package/dist/commands/game-quests.js

@@ -0,0 +1,97 @@
+import { appendLogEntry } from "../core/log.js";
+import { comparableText } from "../core/text.js";
+import { readCounter } from "../counters/index.js";
+import { everyGoalTicked, isEmptyField } from "../pages/index.js";
+import { formatDuration, formatGameDate, minutesBetween, readGameDate } from "../time/index.js";
+import { newDatedLogEntry } from "./game-time.js";
+// What the master does with such a quest.
+const advice = "if the story has ended it, write status done";
+// The fields of a quest the journal shows apart; any other counter is a bar.
+const ownFields = new Set(["status", "kind", "giver", "place", "deadline", "clock", "clock-name"]);
+// The statuses the player character knows a quest by (D-250).
+const knownStatuses = ["open", "done", "failed"];
+/** What a quest measures, as its fields write it; a field that does not read is left out, and validate says why. */
+export function questMeasures(page, now) {
+    const counters = Object.entries(page.fields).filter(([field]) => !ownFields.has(field)).flatMap(([field, value]) => {
+        const counter = readCounter(value);
+        return counter?.max === undefined || counter.max < 1 ? [] : [{ field, value: counter.value, max: counter.max }];
+    });
+    const clock = readCounter(page.fields.clock);
+    const name = typeof page.fields["clock-name"] === "string" && page.fields["clock-name"].trim() !== "" ? page.fields["clock-name"].trim() : undefined;
+    const deadline = readGameDate(page.fields.deadline);
+    return {
+        main: (Array.isArray(page.fields.kind) ? page.fields.kind : [page.fields.kind]).some((kind) => comparableText(String(kind ?? "")) === "main"),
+        counters,
+        ...(clock?.max === undefined || clock.max < 1 ? {} : { clock: { value: clock.value, max: clock.max, ...(name === undefined ? {} : { name }) } }),
+        ...(deadline === undefined ? {} : { deadline: { date: formatGameDate(deadline), ...(now === undefined ? {} : { minutes: minutesBetween(now, deadline) }) } }),
+    };
+}
+/** "clues 3/5, I rapitori lasciano la torre 2/6, deadline day 27, 10:00 (in 1d 2h)": what a quest measures, in the chat's words; empty when nothing. */
+export function measuresText(measures) {
+    const deadline = measures.deadline;
+    const left = deadline?.minutes === undefined ? "" : deadline.minutes <= 0 ? " (passed)" : ` (in ${formatDuration(deadline.minutes)})`;
+    return [
+        ...measures.counters.map((counter) => `${counter.field} ${counter.value}/${counter.max}`),
+        ...(measures.clock === undefined ? [] : [`${measures.clock.name ?? "clock"} ${measures.clock.value}/${measures.clock.max}`]),
+        ...(deadline === undefined ? [] : [`deadline ${deadline.date}${left}`]),
+    ].join(", ");
+}
+/**
+ * What status says of an open quest (D-239, D-369): whether it is the main one, what it measures, and what to do when every goal is ticked or its deadline
+ * passed: the story's end is the master's to say, never the engine's.
+ */
+export function openQuestText(page, now) {
+    const measures = questMeasures(page, now);
+    const passed = measures.deadline?.minutes !== undefined && measures.deadline.minutes <= 0;
+    const notes = [
+        ...(measures.main ? ["main"] : []),
+        ...(measuresText(measures) === "" ? [] : [measuresText(measures)]),
+        ...(isTickedOpenQuest(page) ? [`every goal ticked: ${advice}`] : []),
+        ...(passed ? ["deadline passed: if the story has ended it, write status failed"] : []),
+    ];
+    return notes.length === 0 ? page.name : `${page.name} (${notes.join("; ")})`;
+}
+/** What write says when it makes a quest (D-239): every goal ticked. */
+export function tickedQuestNotes(existing, page) {
+    return isTickedOpenQuest(page) && !isTickedOpenQuest(existing) ? [tickedQuestNote(page)] : [];
+}
+/** What scene close says of each open quest whose goals are all ticked, and write of the one it leaves so. */
+export function tickedQuestNote(page) {
+    return `Every goal of ${page.name} is ticked and it is still open: ${advice}.`;
+}
+/**
+ * What write says as a quest opens, made open or opened from planned (D-367, D-369): what the player's journal shows of it, so that the master writes it there.
+ * Kept in the output, never in the instructions, since only who opens a quest needs it.
+ */
+export function newQuestNotes(existing, page) {
+    return page.type === "quest" && page.fields.status === "open" && existing?.fields.status !== "open"
+        ? [
+            "The player's journal shows this quest now. Give it only what the story has, and keep each up to date: goals as - [ ] lines in the character's words, "
+                + "- [x] when done, new ones as they come up; a counter of steps the character can count, such as clues: 0/5; clock: 0/6 for a danger the character sees "
+                + "growing, with clock-name saying what happens when it fills; deadline: the date the character was given, such as day 27, 10:00, with what happens then "
+                + "as a planned event on that date; giver and place as links; kind: main for the one main quest; what was promised, in the text.",
+        ]
+        : [];
+}
+/** A public line as a quest the character knows is taken, done or failed (D-369): the story tells it. */
+export function logQuestChange(root, context, existing, page) {
+    const status = String(page.fields.status ?? "");
+    if (page.type === "quest" && knownStatuses.includes(status) && existing?.fields.status !== page.fields.status) {
+        appendLogEntry(root, newDatedLogEntry(root, context, "quest-changed", "public", { quest: page.name, status }));
+    }
+}
+/** The quests whose deadline or clock does not read (D-369): the journal leaves them out, so validate says how to write them. */
+export function questProblems(world) {
+    return world.pages.filter((page) => page.type === "quest").flatMap((page) => [
+        ...(!isEmptyField(page.fields.deadline) && readGameDate(page.fields.deadline) === undefined
+            ? [{ path: page.path, message: `The deadline of ${page.name}, ${JSON.stringify(page.fields.deadline)}, is not a game date.`, fix: "write it as day 27, 10:00" }]
+            : []),
+        ...(!isEmptyField(page.fields.clock) && (readCounter(page.fields.clock)?.max ?? 0) < 1
+            ? [{ path: page.path, message: `The clock of ${page.name}, ${JSON.stringify(page.fields.clock)}, has no maximum.`, fix: "write it as 0/6" }]
+            : []),
+    ]);
+}
+/** Whether a page is an open quest whose goals are all ticked. */
+export function isTickedOpenQuest(page) {
+    return page?.type === "quest" && page.fields.status === "open" && everyGoalTicked(page.body);
+}

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

@@ -0,0 +1,34 @@
+import type { Effect } from "../effects/index.ts";
+import { type Page, type World } from "../pages/index.ts";
+import type { GameSystem, Recipe } from "../systems/index.ts";
+/** The recipe of the game system with this name, with the system; refused, with those it has, when it has none. */
+export declare function recipeNamed(system: GameSystem | undefined, name: string): {
+    system: GameSystem;
+    recipe: Recipe;
+};
+/** The pages a recipe without a page goes to: the living player characters, and the living companions where one of them is. */
+export declare function partyPages(world: World): Page[];
+/** The effects of a page split by the recipe: those that last until one of its occasions, which it ends (DAT-5), and the others. */
+export declare function effectsAtRecipe(page: Page, recipe: Recipe): {
+    ending: Effect[];
+    remaining: Effect[];
+};
+/**
+ * The counters of a page that the recipe brings back, as the page reads them, with the value each goes to (DAT-4, DAT-9): "max", which a counter without a
+ * maximum cannot take, or a value. Those it names, then the uses whose occasion it ends, as much as their refill gives, then those it regains, when no choice
+ * is left to the player.
+ */
+export declare function recipeTargets(world: World, recipe: Recipe, page: Page): {
+    field: string;
+    target: "max" | number;
+}[];
+/**
+ * What a recipe's regain leaves to the player (DAT-4): "which hit-dice come back, up to 2 of hit-dice-d10 1/3, hit-dice-d6 0/2", when fewer
+ * come back than are spent, in more than one counter.
+ */
+export declare function recipeChoices(world: World, recipe: Recipe, page: Page): string[];
+/**
+ * The page's other counters away from their usual value, which the recipe leaves to the master: their maximum, or zero for those the status line shows only
+ * when they are not, such as exhaustion; each with the rule of a threshold it is at, or of one without a value, as in "exhaustion 1/6 (rules "Exhaustion")".
+ */
+export declare function notBroughtBack(world: World, system: GameSystem, recipe: Recipe, page: Page): string[];

package/dist/commands/game-recipes.js

@@ -0,0 +1,109 @@
+// The recipes of a game system (D-185, DAT-4): which pages a rest goes to, the effects it ends, the fields it brings back, and what it leaves to the master.
+import { comparableText } from "../core/text.js";
+import { readCounter } from "../counters/index.js";
+import { isDeclaredUncounted, isInParty, locate } from "../pages/index.js";
+import { effectiveFields, effectsOf } from "./effect-layer.js";
+import { formulaValue, refillAmount } from "./worked-out.js";
+/** The recipe of the game system with this name, with the system; refused, with those it has, when it has none. */
+export function recipeNamed(system, name) {
+    const recipe = system?.recipes.find((candidate) => comparableText(candidate.name) === comparableText(name.trim()));
+    if (system === undefined || recipe === undefined) {
+        const recipes = system === undefined || system.recipes.length === 0 ? "" : ` Its recipes: ${system.recipes.map((candidate) => candidate.name).join(", ")}.`;
+        throw new Error(`${system === undefined ? "The campaign has no game system, so it has no" : `The system ${system.name} has no`} recipe "${name.trim()}".${recipes} Nothing changed.`);
+    }
+    return { system, recipe };
+}
+/** The pages a recipe without a page goes to: the living player characters, and the living companions where one of them is. */
+export function partyPages(world) {
+    const players = world.pages.filter((page) => isInParty(page) && page.fields.role === "pc");
+    const places = new Set(players.map((page) => locate(world, page).chain[0]?.name));
+    const companions = world.pages.filter((page) => isInParty(page) && page.fields.role === "companion" && places.has(locate(world, page).chain[0]?.name));
+    return [...players, ...companions];
+}
+/** The effects of a page split by the recipe: those that last until one of its occasions, which it ends (DAT-5), and the others. */
+export function effectsAtRecipe(page, recipe) {
+    const ends = (effect) => {
+        const end = effect.end;
+        return end !== undefined && "occasion" in end && recipe.ends.some((occasion) => comparableText(occasion) === comparableText(end.occasion));
+    };
+    const effects = effectsOf(page);
+    return { ending: effects.filter(ends), remaining: effects.filter((effect) => !ends(effect)) };
+}
+/**
+ * The counters of a page that the recipe brings back, as the page reads them, with the value each goes to (DAT-4, DAT-9): "max", which a counter without a
+ * maximum cannot take, or a value. Those it names, then the uses whose occasion it ends, as much as their refill gives, then those it regains, when no choice
+ * is left to the player.
+ */
+export function recipeTargets(world, recipe, page) {
+    const fields = effectiveFields(world, page);
+    const named = Object.entries(fields).flatMap(([field, value]) => {
+        const target = targetOf(recipe, field);
+        const counter = isDeclaredUncounted(world, field) ? undefined : readCounter(value);
+        return target === undefined || counter === undefined || (target === "max" && counter.max === undefined) ? [] : [{ field, target }];
+    });
+    const refilled = Object.entries(fields).flatMap(([field, value]) => {
+        const counter = isDeclaredUncounted(world, field) || targetOf(recipe, field) !== undefined ? undefined : readCounter(value);
+        const amount = counter?.max === undefined ? undefined : refillAmount(world, fields, field, recipe.ends, counter.max);
+        return counter?.max === undefined || amount === undefined || amount === 0 || counter.value >= counter.max ? [] : [{ field, target: Math.min(counter.max, counter.value + amount) }];
+    });
+    return [...named, ...refilled, ...regainsOf(world, recipe, fields).flatMap((pool) => pool.targets)];
+}
+/**
+ * What a recipe's regain leaves to the player (DAT-4): "which hit-dice come back, up to 2 of hit-dice-d10 1/3, hit-dice-d6 0/2", when fewer
+ * come back than are spent, in more than one counter.
+ */
+export function recipeChoices(world, recipe, page) {
+    return regainsOf(world, recipe, effectiveFields(world, page)).flatMap((pool) => (pool.choice === undefined ? [] : [pool.choice]));
+}
+/**
+ * The page's other counters away from their usual value, which the recipe leaves to the master: their maximum, or zero for those the status line shows only
+ * when they are not, such as exhaustion; each with the rule of a threshold it is at, or of one without a value, as in "exhaustion 1/6 (rules "Exhaustion")".
+ */
+export function notBroughtBack(world, system, recipe, page) {
+    const atZero = (field) => system.statusLine.some((entry) => entry.whenSet && comparableText(entry.field) === comparableText(field));
+    return Object.entries(effectiveFields(world, page)).flatMap(([field, value]) => {
+        // What the recipe sets, or leaves to the player among what it regains, is not left to the master.
+        const handled = targetOf(recipe, field) !== undefined || regainOf(recipe, field) !== undefined;
+        const counter = isDeclaredUncounted(world, field) || handled ? undefined : readCounter(value);
+        if (counter?.max === undefined || counter.value === (atZero(field) ? 0 : counter.max)) {
+            return [];
+        }
+        // The rule of a threshold that holds at every value, or at this one.
+        const rule = system.thresholds.find((threshold) => comparableText(threshold.field) === comparableText(field) && (threshold.value === undefined || threshold.value === counter.value))?.rule;
+        return [`${field} ${String(value).trim()}${rule === undefined ? "" : ` (rules "${rule}")`}`];
+    });
+}
+/**
+ * The regains of a recipe on these fields (DAT-4): for each, the counters it names that are spent and how many come back in all. When all that is spent comes
+ * back, or only one counter is spent, they are targets; otherwise the player chooses.
+ */
+function regainsOf(world, recipe, fields) {
+    return Object.entries(recipe.regain).flatMap(([name, formula]) => {
+        const spent = Object.entries(fields).flatMap(([field, value]) => {
+            const counter = isDeclaredUncounted(world, field) || !matches(name, field) ? undefined : readCounter(value);
+            return counter?.max === undefined || counter.value >= counter.max ? [] : [{ field, value: counter.value, max: counter.max }];
+        });
+        const budget = Math.max(0, Math.floor(formulaValue(world, fields, formula) ?? 0));
+        const missing = spent.reduce((total, counter) => total + counter.max - counter.value, 0);
+        if (spent.length === 0 || budget === 0) {
+            return [];
+        }
+        if (missing <= budget || spent.length === 1) {
+            return [{ targets: spent.map((counter) => ({ field: counter.field, target: Math.min(counter.max, counter.value + budget) })) }];
+        }
+        const counters = spent.map((counter) => `${counter.field} ${counter.value}/${counter.max}`).join(", ");
+        return [{ targets: [], choice: `which ${name.replace(/-?\*$/, "")} come back, up to ${budget} of ${counters}: change each one by what they take` }];
+    });
+}
+/** The regain of a recipe that names a field, by its name or by a name ending in *. */
+function regainOf(recipe, field) {
+    return Object.keys(recipe.regain).find((name) => matches(name, field));
+}
+function matches(name, field) {
+    return name.endsWith("*") ? comparableText(field).startsWith(comparableText(name.slice(0, -1))) : comparableText(name) === comparableText(field);
+}
+/** What a recipe asks of a field: "max", a value, or nothing; a name ending in * stands for every field that begins so, such as slots-*. */
+function targetOf(recipe, field) {
+    const entry = Object.entries(recipe.set).find(([name]) => name.endsWith("*") ? comparableText(field).startsWith(comparableText(name.slice(0, -1))) : comparableText(name) === comparableText(field));
+    return entry?.[1];
+}

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

@@ -0,0 +1,22 @@
+import { type Effect } from "../effects/index.ts";
+import type { Page, World } from "../pages/index.ts";
+import type { Scene } from "../scene/index.ts";
+import type { GameSystem } from "../systems/index.ts";
+/** "Viola keeps Eroismo (Corrado): lost 7 hp. Read rules Concentration.": what someone keeps alive, when the counter the game system names goes down by `lost` (EFF-14). */
+export declare function keepingLossNote(world: World, scene: Scene | undefined, system: GameSystem | undefined, name: string, field: string, lost: number): string;
+/** "Corrado keeps Scudo della fede (Viola): now Paralyzed. Read rules Concentration.": what someone keeps alive, when they take a condition the game system names (EFF-14). */
+export declare function keepingConditionNote(world: World, scene: Scene | undefined, system: GameSystem | undefined, name: string, condition: string): string;
+/**
+ * "Malco already keeps Scudo della fede (Malco). Read rules Concentration.": someone given one more effect to keep alive, read in the world before it was added (EFF-14).
+ * The same effect on another target is the same thing kept, as Bless on three.
+ */
+export declare function secondKeptNote(world: World, scene: Scene | undefined, system: GameSystem | undefined, effect: Effect): string;
+/** "End of Malco's turn: Paralyzed (by Corrado). Start of Ghoul 1's turn: In fiamme.": the effects on who ends a turn and on who starts the next, as the turn passes (EFF-15). */
+export declare function turnEffectsNote(world: World, scene: Scene | undefined, ending: string | undefined, starting: string): string;
+/** "Still on Corrado, with no end: Mummy Rot.": the effects without an end on who rests, whose text may ask for something at a rest (EFF-15). */
+export declare function restingEffectsNote(page: Page): string;
+/**
+ * "Corrado has temp-hp 3, which goes first: …": a counter that shields the one that went down by `lost`, while it is above 0 (DAT-14). The change took it all
+ * from the shielded counter: the note says how to put it right.
+ */
+export declare function shieldNotes(world: World, system: GameSystem | undefined, page: Page, field: string, lost: number): string[];

package/dist/commands/game-reminders.js

@@ -0,0 +1,74 @@
+// What a fight asks the master to keep by hand, said when it happens (D-266): what can break what someone keeps alive (EFF-14), the effects at a turn and at a rest
+// (EFF-15), the counter that shields another (DAT-14). The engine only says it: it ends and changes nothing by itself.
+import { comparableText } from "../core/text.js";
+import { readCounter } from "../counters/index.js";
+import { keeperOf } from "../effects/index.js";
+import { effectiveFields, effectsOf } from "./effect-layer.js";
+import { effectsOn, keptEffectHolders, keptEffects } from "./game-effects.js";
+/** "Viola keeps Eroismo (Corrado): lost 7 hp. Read rules Concentration.": what someone keeps alive, when the counter the game system names goes down by `lost` (EFF-14). */
+export function keepingLossNote(world, scene, system, name, field, lost) {
+    const keeping = system?.keeping;
+    // Damage a shield takes first, as temporary hit points, is damage still.
+    const shielded = Object.entries(system?.shields ?? {}).find(([shield]) => comparableText(shield) === comparableText(field))?.[1] ?? field;
+    if (keeping === undefined || comparableText(shielded) !== comparableText(keeping.counter) || !(lost > 0)) {
+        return "";
+    }
+    const kept = keptEffects(world, scene, name);
+    return kept.length === 0 ? "" : `${name} keeps ${kept.join(" · ")}: lost ${lost} ${field}. Read rules ${keeping.rules}.`;
+}
+/** "Corrado keeps Scudo della fede (Viola): now Paralyzed. Read rules Concentration.": what someone keeps alive, when they take a condition the game system names (EFF-14). */
+export function keepingConditionNote(world, scene, system, name, condition) {
+    const keeping = system?.keeping;
+    if (keeping === undefined || !keeping.conditions.some((named) => comparableText(named) === comparableText(condition))) {
+        return "";
+    }
+    const kept = keptEffects(world, scene, name);
+    return kept.length === 0 ? "" : `${name} keeps ${kept.join(" · ")}: now ${condition}. Read rules ${keeping.rules}.`;
+}
+/**
+ * "Malco already keeps Scudo della fede (Malco). Read rules Concentration.": someone given one more effect to keep alive, read in the world before it was added (EFF-14).
+ * The same effect on another target is the same thing kept, as Bless on three.
+ */
+export function secondKeptNote(world, scene, system, effect) {
+    const keeper = keeperOf(effect);
+    if (system?.keeping === undefined || keeper === undefined) {
+        return "";
+    }
+    const others = keptEffectHolders(world, scene, keeper).filter((kept) => comparableText(kept.effect) !== comparableText(effect.name));
+    return others.length === 0 ? "" : `${keeper} already keeps ${others.map((kept) => `${kept.effect} (${kept.holders.join(", ")})`).join(" · ")}. Read rules ${system.keeping.rules}.`;
+}
+/** "End of Malco's turn: Paralyzed (by Corrado). Start of Ghoul 1's turn: In fiamme.": the effects on who ends a turn and on who starts the next, as the turn passes (EFF-15). */
+export function turnEffectsNote(world, scene, ending, starting) {
+    const on = (name) => effectsOn(world, scene, name).map(effectWithKeeper);
+    const parts = [
+        ending === undefined || on(ending).length === 0 ? "" : `End of ${ending}'s turn: ${on(ending).join(", ")}.`,
+        on(starting).length === 0 ? "" : `Start of ${starting}'s turn: ${on(starting).join(", ")}.`,
+    ].filter((part) => part !== "");
+    return parts.length === 0 ? "" : `${parts.join(" ")} Read in their text what acts now.`;
+}
+/** "Still on Corrado, with no end: Mummy Rot.": the effects without an end on who rests, whose text may ask for something at a rest (EFF-15). */
+export function restingEffectsNote(page) {
+    const endless = effectsOf(page).filter((effect) => effect.end === undefined).map(effectWithKeeper);
+    return endless.length === 0 ? "" : `Still on ${page.name}, with no end: ${endless.join(", ")}. Read in their text whether a rest asks for something.`;
+}
+/**
+ * "Corrado has temp-hp 3, which goes first: …": a counter that shields the one that went down by `lost`, while it is above 0 (DAT-14). The change took it all
+ * from the shielded counter: the note says how to put it right.
+ */
+export function shieldNotes(world, system, page, field, lost) {
+    if (system === undefined || !(lost > 0)) {
+        return [];
+    }
+    const fields = Object.entries(effectiveFields(world, page));
+    return Object.entries(system.shields).filter(([, shielded]) => comparableText(shielded) === comparableText(field)).flatMap(([shield]) => {
+        const value = readCounter(fields.find(([name]) => comparableText(name) === comparableText(shield))?.[1])?.value ?? 0;
+        const rule = system.thresholds.find((threshold) => comparableText(threshold.field) === comparableText(shield))?.rule;
+        const read = rule === undefined ? "" : ` Read rules ${rule}.`;
+        return value > 0 ? [`${page.name} has ${shield} ${value}, which goes first: if this was damage, give ${field} back what ${shield} takes and take it from ${shield}, with change.${read}`] : [];
+    });
+}
+/** "Paralyzed (by Corrado)": an effect with who keeps it alive. */
+function effectWithKeeper(effect) {
+    const keeper = keeperOf(effect);
+    return keeper === undefined ? effect.name : `${effect.name} (by ${keeper})`;
+}