rpg-engine 0.0.0-stage → 0.1.0

package/dist/commands/effect-layer.js

@@ -0,0 +1,84 @@
+// The values effects give for a while, as a layer over a page (D-123, EFF-3): read by every command that shows or changes a page's fields.
+import { fieldsRead } from "../core/formula.js";
+import { comparableText, valueNamed } from "../core/text.js";
+import { readCounter } from "../counters/index.js";
+import { formatEffect, readEffects } from "../effects/index.js";
+import { declaredKind } from "../pages/index.js";
+import { hasSheet, signedText, withEffectValues, withWorkedOut } from "./worked-out.js";
+/** The effects field of a page or copy, written in any case (EFF-1). */
+export function effectsField(page) {
+    return Object.entries(page.fields).find(([field]) => comparableText(field) === "effects")?.[1];
+}
+/** The effects a page or copy holds; none when its field cannot be read, which validate reports and effect refuses to touch (EFF-12). */
+export function effectsOf(page) {
+    const read = readEffects(effectsField(page));
+    return "effects" in read ? read.effects : [];
+}
+/**
+ * The fields a page reads with its effects over them (EFF-3): from the newest effect that gives a field, then the page, then its bases; a bonus field adds up
+ * the effects that give it (FOR-5). Over them, what the game system works out (FOR-3).
+ */
+export function effectiveFields(world, page) {
+    // A world and its pages never change: a page's fields are worked out once in each world, and each caller gets its own copy (D-194).
+    let byPage = readByWorld.get(world);
+    if (byPage === undefined) {
+        byPage = new WeakMap();
+        readByWorld.set(world, byPage);
+    }
+    const known = byPage.get(page) ?? withWorkedOut(world, withEffectValues(world, page), hasSheet(world, page));
+    byPage.set(page, known);
+    return { ...known };
+}
+const readByWorld = new WeakMap();
+/** The newest effect that gives a field to a page: change changes its value, not the page's (EFF-7). */
+export function effectGiving(page, field) {
+    return effectsOf(page).findLast((effect) => effect.values.some(([name]) => comparableText(name) === comparableText(field)));
+}
+/**
+ * "ac 13 → 15": the values an effect changes on a page, as they read before and after it; and "ac stays 17, from Scudo della fede" for a value
+ * another effect still gives, which was written while this one was on (EFF-3). A bonus that changes nothing else is said to be read by nothing.
+ */
+export function valuesChanged(world, before, after, effect) {
+    const was = effectiveFields(world, before);
+    const is = effectiveFields(world, after);
+    const value = (fields, field) => valueNamed(fields, field);
+    const read = (fields, field) => valueText(world, field, value(fields, field));
+    const changed = (field) => read(was, field) !== read(is, field);
+    const given = new Set(effect.values.map(([field]) => comparableText(field)));
+    // Anything else that changed with it, worked out or not, but the list of effects itself.
+    const followed = [...new Set([...Object.keys(was), ...Object.keys(is)])].some((field) => !given.has(comparableText(field)) && comparableText(field) !== "effects" && changed(field));
+    const own = effect.values.map(([field]) => field).flatMap((field) => {
+        if (changed(field)) {
+            // An item's bonus is read by who has it, as a weapon's by its wielder's attack.
+            const unread = !followed && after.type !== "item" && declaredKind(world, field) === "bonus" ? `, which nothing of ${after.name} reads` : "";
+            return [`${field} ${read(was, field)} → ${read(is, field)}${unread}`];
+        }
+        const other = effectGiving(after, field);
+        return other === undefined || comparableText(other.name) === comparableText(effect.name) ? [] : [`${field} stays ${read(is, field)}, from ${other.name}: check it`];
+    });
+    // The counters whose maximum follows what the effect gives, as hp after Aid (FOR-6), the numbers worked out right from it, as ac from Mage Armor's
+    // unarmored-base (FOR-3), and those of the status line, as ac after dex.
+    const counters = Object.keys(is).filter((field) => !given.has(comparableText(field)) && readCounter(is[field])?.max !== undefined && changed(field));
+    const computed = (world.system?.formulas?.computed ?? [])
+        .filter(([name, formula]) => !given.has(comparableText(name)) && fieldsRead(formula).some((field) => given.has(comparableText(field))) && changed(name))
+        .map(([name]) => name);
+    const status = (world.system?.statusLine ?? []).map((entry) => entry.field).filter((field) => !given.has(comparableText(field)) && changed(field));
+    const others = [...counters, ...computed, ...status].filter((field, index, all) => all.findIndex((other) => comparableText(other) === comparableText(field)) === index);
+    return [...own, ...others.map((field) => `${field} ${read(was, field)} → ${read(is, field)}`)];
+}
+/** "+2", "Dueling, Defense", "none": a value as an effect's output says it, with its sign when the system declares a modifier or a bonus (FOR-8). */
+function valueText(world, field, value) {
+    if (value === undefined || value === null) {
+        return "none";
+    }
+    return typeof value === "number" ? signedText(world, field, value) : Array.isArray(value) ? value.map(String).join(", ") : String(value);
+}
+/** The effect with a new value for one of its fields, as change writes it (EFF-7). */
+export function withValue(effect, field, value) {
+    return { ...effect, values: effect.values.map(([name, old]) => [name, comparableText(name) === comparableText(field) ? value : old]) };
+}
+/** A page or copy with these effects instead of its own. */
+export function withEffects(page, effects) {
+    const fields = Object.fromEntries(Object.entries(page.fields).filter(([field]) => comparableText(field) !== "effects"));
+    return { ...page, fields: effects.length === 0 ? fields : { ...fields, effects: effects.map(formatEffect) } };
+}

package/dist/commands/effect.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+declare const actions: readonly ["add", "end"];
+/** What effect did: on whom, which effect, and what changed, with what the master should know. */
+interface EffectResult {
+    action: (typeof actions)[number];
+    page?: string;
+    effect?: string;
+    end?: string;
+    values: string[];
+    /** For end with by: the effects that someone kept alive, as they ended. */
+    ended: string[];
+    notes: string[];
+}
+export declare const effect: import("../core/registry.ts").Command<z.ZodObject<{
+    action: z.ZodEnum<{
+        add: "add";
+        end: "end";
+    }>;
+    page: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    for: z.ZodOptional<z.ZodString>;
+    until: z.ZodOptional<z.ZodString>;
+    by: z.ZodOptional<z.ZodString>;
+    set: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    why: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, EffectResult>;
+export {};

package/dist/commands/effect.js

@@ -0,0 +1,369 @@
+import { z } from "zod";
+import { requireCampaign } from "../campaign/index.js";
+import { numberOf } from "../core/formula.js";
+import { appendLogEntry } from "../core/log.js";
+import { defineCommand } from "../core/registry.js";
+import { comparableText, sameName, valueNamed } from "../core/text.js";
+import { readCounter } from "../counters/index.js";
+import { effectNamed, formatEffect, formatEnd, isSceneDuration, readEffect, readRounds, withEffect } from "../effects/index.js";
+import { concernsPlayer, declaredKind, environmentAt, isDeclaredUncounted, isNeverInherited, isStandardField, parsePageReference, readFieldValue } from "../pages/index.js";
+import { addDuration, formatGameDate, readDuration } from "../time/index.js";
+import { effectGiving, effectiveFields, effectsOf, valuesChanged, withEffects } from "./effect-layer.js";
+import { checkEffectsReadable, endEffects, keptBy, saveEffects } from "./game-effects.js";
+import { keepingConditionNote, secondKeptNote } from "./game-reminders.js";
+import { houseRules, ruleBlock, ruleTitled } from "./game-rules.js";
+import { checkNotSystemPage, pageOrCopy, readOpenScene } from "./game-scene.js";
+import { newDatedLogEntry, presentDate } from "./game-time.js";
+import { campaignSystem, campaignWorld, missingSystemHint, occasionsOf } from "./game-world.js";
+import { computedField, counterLimits, effectBonuses, itemSource, maximumSources } from "./worked-out.js";
+const actions = ["add", "end"];
+// Values arrive as field=value strings from a command line, or as an object through MCP.
+const fieldValues = z.union([z.array(z.string()), z.record(z.string(), z.unknown())]);
+export const effect = defineCommand({
+    name: "effect",
+    description: "Put a condition or an effect on a character, a place or a copy in the open scene, or end one: frightened, prone, a spell, a form. "
+        + "On a place, such as rain or magical darkness, it holds for all inside by its name, and its values are the place's own. "
+        + "Beyond the values it gives, what it does in play is yours to rule. It ends by itself, and advance or scene says so; end takes it away sooner. "
+        + 'Example: action add, page Ennio, name "Scudo della fede", for 10m, by [[Lena]], set bonus-ac=2.',
+    group: "game",
+    positionals: ["action", "page", "name"],
+    input: z.object({
+        action: z.enum(actions).describe("add or end"),
+        page: z.string().optional().describe("who has it: a page, or a copy in the open scene such as Annegato 2"),
+        name: z.string().optional().describe("the effect's name, such as Benedizione; a condition of the game system always by its name there, such as Frightened"),
+        for: z.string().optional().describe("add: how long it lasts: 10m, 1h, 1d 6h; in a scene with turns, rounds from the current turn, such as 1 round; scene, until it ends; or an occasion of the game system its recipe brings, such as long rest. "
+            + "Left out, until it is ended: so for one that ends with something in the story, such as breathing clean air; end it then"),
+        until: z.string().optional().describe("add, in a scene with turns: whose next turn ends it when it starts, such as Ennio, instead of for"),
+        by: z.string().optional().describe("add: who keeps it alive, if someone must (concentration), such as [[Lena]]; end: take away every effect they keep, on everyone"),
+        set: fieldValues.optional().describe("add: the values it gives while it lasts, field=value, repeatable, such as speed=20; for a field the game system declares a bonus, what it adds, such as bonus-ac=2. "
+            + "What must outlive it, such as hit points it adds, change on the page instead"),
+        why: z.string().optional().describe("what caused it, or ended it"),
+    }),
+    run(input, context) {
+        const root = requireCampaign(context.folder);
+        const world = campaignWorld(root, context);
+        const open = readOpenScene(root);
+        const why = input.why?.trim() === "" ? undefined : input.why;
+        if (input.action === "end" && input.by !== undefined && input.page === undefined && input.name === undefined) {
+            const keeper = parsePageReference(input.by).name;
+            const ended = endEffects(root, context, world, open.scene, (effect) => keptBy(effect, keeper), why ?? `${keeper} stopped keeping them`);
+            if (ended.length === 0) {
+                throw new Error(`${keeper} keeps no effect alive.`);
+            }
+            return { action: "end", values: [], ended, notes: [] };
+        }
+        if (input.page === undefined || input.name === undefined || input.name.trim() === "") {
+            throw new Error(`Give the page and the effect's name, such as page Ennio, name Benedizione${input.action === "end" ? "; or only by, to end every effect someone keeps alive" : ""}.`);
+        }
+        const found = pageOrCopy(world, open, input.page, (page) => `effects are on the whole page, such as page ${page}`);
+        checkNotSystemPage(world, open, found.page);
+        const holder = { page: found.page, copy: found.copy !== undefined };
+        checkEffectsReadable(holder.page);
+        const current = effectsOf(holder.page);
+        const visibility = !holder.copy && concernsPlayer(world, holder.page) ? "public" : "hidden";
+        if (input.action === "end") {
+            if (input.for !== undefined || input.until !== undefined || input.set !== undefined || input.by !== undefined) {
+                throw new Error("end takes the page and the effect's name, or by alone: nothing else.");
+            }
+            const ended = effectNamed(current, input.name);
+            if (ended === undefined) {
+                const held = current.length === 0 ? `${holder.page.name} has no effects.` : `Its effects: ${current.map((effect) => effect.name).join(", ")}.`;
+                throw new Error(`${holder.page.name} has no effect named ${input.name.trim()}. ${held}`);
+            }
+            const remaining = current.filter((effect) => effect !== ended);
+            const values = valuesChanged(world, holder.page, withEffects(holder.page, remaining), ended);
+            saveEffects(root, context, world, holder, remaining);
+            appendLogEntry(root, newDatedLogEntry(root, context, "effect-ended", visibility, { page: holder.page.name, copy: holder.copy ? true : undefined, effect: ended.name, why }));
+            return { action: "end", page: holder.page.name, effect: ended.name, values, ended: [], notes: [] };
+        }
+        const name = input.name.trim();
+        // An end first: "until day 1, 18:10" in parentheses is no value.
+        if (/\buntil\b/i.test(name)) {
+            throw new Error(`The name ${name} has "until" in it: give the end with for or until, not in the name.`);
+        }
+        const inName = /\(([^()]*:[^()]*)\)/.exec(name);
+        if (inName !== null) {
+            const values = inName[1].split(",").map((value) => value.trim().replace(/\s*:\s*/, "="));
+            throw new Error(`Give the values with set, not in the name, such as name ${name.replace(/\s*\(.*$/, "")}, set ${values.join(", set ")}.`);
+        }
+        const values = readValues(world, holder.page, input.set);
+        checkPlaceValues(world, holder, values);
+        const keeper = input.by === undefined ? undefined : keeperLink(world, open.scene, input.by);
+        const system = campaignSystem(root, context);
+        checkNotCounter(system, holder.page, name);
+        const added = { name, ...(keeper === undefined ? {} : { by: keeper }), values, ...withEnd(root, open.scene, input.for, input.until, system, inScene(open.scene, holder), missingSystemHint(world)) };
+        checkLine(added);
+        const replaced = effectNamed(current, name);
+        const effects = withEffect(current, added);
+        const changed = valuesChanged(world, holder.page, withEffects(holder.page, effects), added);
+        // What the condition may break that the holder keeps alive, and what the keeper already keeps, read before the effect is written (EFF-14).
+        const keeping = [keepingConditionNote(world, open.scene, system, holder.page.name, name), secondKeptNote(world, open.scene, system, added)].filter((note) => note !== "");
+        const notes = [...addNotes(world, holder.page, current, added, open.scene, system), ...conditionNote(root, system, name), ...roundsNote(input.for, added.end, system), ...keeping];
+        saveEffects(root, context, world, holder, effects);
+        appendLogEntry(root, newDatedLogEntry(root, context, "effect-added", visibility, { page: holder.page.name, copy: holder.copy ? true : undefined, effect: formatEffect(added), why }));
+        const instead = replaced === undefined ? [] : [`It takes the place of ${formatEffect(replaced)}.`];
+        return { action: "add", page: holder.page.name, effect: added.name, end: added.end === undefined ? undefined : formatEnd(added.end), values: changed, ended: [], notes: [...instead, ...notes] };
+    },
+    format(result) {
+        const values = result.values.length === 0 ? "" : `; ${result.values.join(", ")}`;
+        if (result.action === "end") {
+            return result.effect === undefined ? `Ended: ${result.ended.join(" · ")}.` : `${result.page}: ${result.effect} ended${values}.`;
+        }
+        const line = `${result.page}: ${result.effect}${result.end === undefined ? ", until it is ended" : ` until ${result.end}`}${values}.`;
+        // A note of several lines, such as the text of a condition, goes on lines of its own.
+        const short = result.notes.filter((note) => !note.includes("\n"));
+        const long = result.notes.filter((note) => note.includes("\n"));
+        return [[line, ...short].join(" "), ...long].join("\n\n");
+    },
+});
+/**
+ * An effect on a place holds for all inside by its name and its end; its values are the place's own (ENV-3, D-157). One named as an entry of the environment
+ * that holds there would seem to change it, and would not: refused.
+ */
+function checkPlaceValues(world, holder, values) {
+    if (holder.copy || holder.page.type !== "place") {
+        return;
+    }
+    const entries = environmentAt(world, holder.page);
+    const clash = values.find(([field]) => entries.some(({ entry }) => comparableText(entry.name) === comparableText(field)));
+    if (clash !== undefined) {
+        const where = entries.find(({ entry }) => comparableText(entry.name) === comparableText(clash[0]))?.place.name ?? holder.page.name;
+        throw new Error(`${clash[0]} is in the environment of ${where}: an effect on a place holds for all inside by its name and end, and its values are the place's own. Leave ${clash[0]} out and let the name say it, such as Magical darkness.`);
+    }
+}
+/** An effect never bears the name of a counter of the game system, such as exhaustion: the counter is kept on the page, with change (DAT-6). */
+function checkNotCounter(system, page, name) {
+    const field = Object.keys(system?.fields ?? {}).find((candidate) => comparableText(candidate) === comparableText(name));
+    if (system !== undefined && field !== undefined && system.fields[field] === "counter") {
+        throw new Error(`${field} is a counter of the system ${system.name}, kept on the page: change it, such as page ${page.name}, field ${field}, by 1. Nothing changed.`);
+    }
+}
+/** Whether the holder of an effect is in the open scene: a copy in it, or a character it is with. */
+function inScene(scene, holder) {
+    return scene !== undefined && (holder.copy || scene.with.some((link) => comparableText(parsePageReference(link).name) === comparableText(holder.page.name)));
+}
+/**
+ * When the effect ends (EFF-4): a duration in game time from now; rounds from the current turn, or the next turn of someone, in a scene with turns;
+ * the end of the scene; an occasion of the game system; or nothing. `member` says whether its holder is in the open scene, and `hint` what a missing
+ * game system means, for a duration that does not read.
+ */
+function withEnd(root, scene, duration, until, system, member, hint) {
+    if (duration !== undefined && until !== undefined) {
+        throw new Error("Give for or until, not both.");
+    }
+    if (until !== undefined) {
+        return { end: untilTurn(scene, until) };
+    }
+    if (duration === undefined || duration.trim() === "") {
+        return {};
+    }
+    if (isSceneDuration(duration)) {
+        if (scene === undefined) {
+            throw new Error("No scene is open: an effect that lasts the scene needs one. Open it with scene open, or give a duration such as 10m.");
+        }
+        return { end: { scene: true } };
+    }
+    const rounds = readRounds(duration);
+    if (rounds !== undefined) {
+        const turns = sceneTurns(scene);
+        return { end: { round: turns.round + rounds, turn: turns.turn } };
+    }
+    const occasion = occasionsOf(system).find((candidate) => comparableText(candidate) === comparableText(duration.trim()));
+    if (occasion !== undefined) {
+        return { end: { occasion } };
+    }
+    const minutes = readDuration(duration);
+    if (minutes === undefined) {
+        const occasions = occasionsOf(system);
+        const named = occasions.length === 0 ? "" : `, or an occasion of the system ${system?.name ?? ""}: ${occasions.join(", ")}`;
+        throw new Error(`"${duration}" is not a duration: write it as 10m, 1h or 1d 6h, as rounds such as 1 round or 10 rounds, or scene${named}.${hint}`);
+    }
+    // In a scene with turns, time does not pass with the rounds: a duration of up to a minute, on someone in the scene, becomes rounds as long as the system's
+    // round; a longer one stays in game time and outlasts the scene (DAT-7).
+    if (member && minutes <= 1 && scene?.order !== undefined && system?.roundSeconds !== undefined) {
+        const turns = sceneTurns(scene);
+        return { end: { round: turns.round + Math.ceil((minutes * 60) / system.roundSeconds), turn: turns.turn } };
+    }
+    const now = presentDate(root);
+    if (now === undefined) {
+        throw new Error('The game has no date yet, so a duration in time cannot end: set the date with advance to, such as "day 1, 18:00", or count the effect in rounds.');
+    }
+    return { end: { date: formatGameDate(addDuration(now, minutes)) } };
+}
+/** The start of someone's next turn: in this round, if their turn is still to come, else in the next (EFF-4). */
+function untilTurn(scene, name) {
+    const turns = sceneTurns(scene);
+    const who = sameName(turns.order, parsePageReference(name).name);
+    if (who === undefined) {
+        throw new Error(`${name} takes no turn in this scene. The order: ${turns.order.join(", ")}.`);
+    }
+    const later = turns.order.indexOf(who) > turns.order.indexOf(turns.turn);
+    return { round: later ? turns.round : turns.round + 1, turn: who };
+}
+/** The order, round and turn of the open scene; refused, with how to set them, when it has none. */
+function sceneTurns(scene) {
+    if (scene?.order === undefined || scene.turn === undefined) {
+        throw new Error(`Rounds are counted in a scene with turns: ${scene === undefined ? "open one with scene open, then set the order" : "set the order with scene order"}, or give a duration in time, such as 1m.`);
+    }
+    return { order: scene.order, round: scene.round ?? 1, turn: scene.turn };
+}
+/** Who keeps the effect alive, as the line writes it: a link to a page, or the name of a copy in the open scene (D-138). */
+function keeperLink(world, scene, name) {
+    const found = pageOrCopy(world, { scene }, name, (page) => `who keeps an effect alive is a whole page, such as ${page}`);
+    return found.copy ?? `[[${found.page.name}]]`;
+}
+/**
+ * The values an effect gives (EFF-3, EFF-4): counters and free fields, never a fixed field or a relation; one value for each field; a counter stays a counter.
+ * As text, the way the line writes them.
+ */
+function readValues(world, page, set) {
+    const pairs = Array.isArray(set)
+        ? set.map((assignment) => {
+            const separator = assignment.indexOf("=");
+            if (separator <= 0 || assignment.slice(separator + 1).trim() === "") {
+                throw new Error(`Write a value as field=value, such as speed=20, not "${assignment}".`);
+            }
+            return [assignment.slice(0, separator).trim(), assignment.slice(separator + 1).trim()];
+        })
+        : Object.entries(set ?? {});
+    const fields = effectiveFields(world, page);
+    return pairs.map(([field, value], index) => {
+        if (isStandardField(page.type, field) || isNeverInherited(field) || comparableText(field) === "by") {
+            throw new Error(`An effect gives values to counters and free fields, such as speed=20, not to ${field}.`);
+        }
+        if (pairs.findIndex(([other]) => comparableText(other) === comparableText(field)) !== index) {
+            throw new Error(`${field} is given twice: give each value once.`);
+        }
+        if (value === null || value === undefined || String(value).trim() === "") {
+            throw new Error(`Give ${field} a value, such as ${field}=15.`);
+        }
+        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+            throw new Error(`Give ${field} one value, such as ${field}=15: an effect does not hold lists.`);
+        }
+        const text = String(value).trim();
+        checkValue(world, page, fields, field, text);
+        return [field, text];
+    });
+}
+/** A value reads as a page would hold it, and a field the page reads as a counter gets a counter: the value it reads, not a bonus. */
+function checkValue(world, page, fields, field, text) {
+    let value;
+    try {
+        value = readFieldValue(text);
+    }
+    catch (error) {
+        throw new Error(`${error instanceof Error ? error.message : String(error)} Nothing changed.`);
+    }
+    const current = valueNamed(fields, field);
+    const computed = computedField(world, field, fields);
+    // An effect changes what a computed field comes from, never the field (FOR-7, D-200).
+    // What the tables of a character's classes give comes from its lists alone, which no effect gives (PRO-2).
+    if (computed !== undefined && computed.from.length > 0 && computed.from.every((name) => declaredKind(world, name) === "list" || computedField(world, name, fields) !== undefined)) {
+        throw new Error(`${computed.name} on ${page.name} is what its ${computed.from.join(" and ")} give, from the tables of their pages: an effect cannot change it. Nothing changed.`);
+    }
+    if (computed !== undefined && computed.from.length === 0) {
+        throw new Error(`${computed.name} on ${page.name} is ${String(computed.value)} for everyone, a fixed value of the game data (system ${world.system?.name ?? ""} or campaign.yaml): an effect cannot change it. Nothing changed.`);
+    }
+    // What an item of a list gives, as a shield's armor-class-bonus, changes with an effect on the item, through what its formula reads of it (PRO-5).
+    const source = computed === undefined || effectBonuses(world, computed.from).length > 0 ? undefined : itemSource(world, fields, computed.name);
+    if (computed !== undefined && source !== undefined) {
+        const through = source.own.length === 0 ? "" : `, through ${source.own.join(" or ")}, such as effect add, page ${source.item}, set ${source.own[0]}=1`;
+        throw new Error(`${computed.name} on ${page.name} is what ${source.item} in its ${source.list} gives, by the formula of its page: an effect on ${source.item} changes it${through}. Nothing changed.`);
+    }
+    if (computed !== undefined) {
+        // A bonus field of the page first, which is what an effect is for; else a field the page writes.
+        const from = [...effectBonuses(world, computed.from), ...computed.from.filter((name) => computedField(world, name, fields) === undefined)];
+        throw new Error(`${computed.name} on ${page.name} is worked out by the system ${world.system?.name ?? ""} from ${computed.from.join(", ")}: give the effect one of the fields it comes from instead, such as ${from[0] ?? computed.from[0]}. Nothing changed.`);
+    }
+    // A bonus is what the effect adds, with its sign or without (FOR-5).
+    if (declaredKind(world, field) === "bonus" && numberOf(text) === undefined) {
+        throw new Error(`${field} on ${page.name} is a bonus: give what the effect adds, such as ${field}=1, not "${text}". Nothing changed.`);
+    }
+    // A field the game system declares as a number takes a number; a counter stays a counter (SYS-8, EFF-3).
+    if (["number", "modifier"].includes(declaredKind(world, field) ?? "") && typeof value !== "number" && !(declaredKind(world, field) === "modifier" && numberOf(text) !== undefined)) {
+        throw new Error(`${field} on ${page.name} is a number, ${String(current ?? "none")}: give the value it reads while the effect lasts, such as ${field}=${exampleValue(current, text)}, not "${text}". Nothing changed.`);
+    }
+    // The maximum of a counter the system works out comes from what the formula reads, as hp from hp-base (FOR-6, FOR-7).
+    const limits = readCounter(value)?.max === undefined ? {} : counterLimits(world, fields, field);
+    if (limits.max !== undefined && readCounter(value)?.max !== limits.max) {
+        const from = maximumSources(world, field, fields);
+        throw new Error(`The maximum of ${field} on ${page.name} is worked out by the system ${world.system?.name ?? ""}: ${limits.max}, from ${from.join(", ")}. Give the effect the current value alone, such as ${field}=${readCounter(value)?.value ?? 0}, or one of those fields, such as ${from[0] ?? field}. Nothing changed.`);
+    }
+    // A current above the maximum would read as the maximum: the maximum comes from what it is made of (FOR-6).
+    const above = readCounter(value)?.max === undefined ? counterLimits(world, fields, field).max : undefined;
+    const given = readCounter(value)?.value;
+    if (above !== undefined && given !== undefined && given > above) {
+        // An effect gives no list, such as the classes (PRO-2).
+        const from = maximumSources(world, field, fields).filter((name) => declaredKind(world, name) !== "list");
+        if (from.length === 0) {
+            throw new Error(`${field}=${given} on ${page.name} is above its maximum, ${above}, which the system ${world.system?.name ?? ""} works out from what the character's lists give: an effect cannot raise it. Nothing changed.`);
+        }
+        throw new Error(`${field}=${given} on ${page.name} is above its maximum, ${above}, which the system ${world.system?.name ?? ""} works out from ${from.join(", ")}: to raise the maximum while the effect lasts, give the effect one of those, such as ${from[0] ?? field}. Nothing changed.`);
+    }
+    if (!isDeclaredUncounted(world, field) && readCounter(current) !== undefined && readCounter(value) === undefined) {
+        throw new Error(`${field} on ${page.name} is a counter, ${String(current)}: give the value it reads while the effect lasts, such as ${field}=${exampleValue(current, text)}, not "${text}". Nothing changed.`);
+    }
+}
+/** The effect must read back from its line as it is. */
+function checkLine(added) {
+    const read = readEffect(formatEffect(added));
+    if ("problem" in read) {
+        throw new Error(`${read.problem} Nothing changed.`);
+    }
+    if (JSON.stringify(read.effect) !== JSON.stringify(added)) {
+        throw new Error(`"${formatEffect(added)}" would not read back as written: give values without commas. Nothing changed.`);
+    }
+}
+/**
+ * What the master should know about an effect just added: a current/max counter in it changes there and is lost at its end; a value it gives over another
+ * effect's; a duration in time in a scene whose turns do not move time (EFF-3, EFF-4).
+ */
+function addNotes(world, page, current, added, scene, system) {
+    const others = withEffects(page, current.filter((effect) => comparableText(effect.name) !== comparableText(added.name)));
+    const fields = effectiveFields(world, others);
+    const read = (field) => String(valueNamed(fields, field) ?? "none");
+    const counters = added.values.filter(([field, value]) => !isDeclaredUncounted(world, field) && readCounter(value)?.max !== undefined).map(([field]) => field);
+    // A bonus field adds up the effects that give it, so none goes over another (FOR-5).
+    const over = added.values.filter(([field]) => declaredKind(world, field) !== "bonus").flatMap(([field]) => {
+        const other = effectGiving(others, field);
+        return other === undefined ? [] : [`${field} goes over ${other.name} (${field} ${read(field)})`];
+    });
+    // With a round, a short duration became rounds and a long one outlasts the scene on purpose (DAT-7): only a system without one needs the warning.
+    const timed = scene?.order !== undefined && added.end !== undefined && "date" in added.end && system?.roundSeconds === undefined;
+    return [
+        counters.length === 0
+            ? ""
+            : `${counters.join(", ")} change${counters.length === 1 ? "s" : ""} on ${added.name} while it lasts, and at its end ${page.name} reads ${counters.map((field) => `${field} ${read(field)}`).join(", ")} again: what must outlive it goes on the page, with change.`,
+        over.length === 0 ? "" : `Its ${over.join(", ")}: write the value both give together.`,
+        timed ? "The scene counts turns, and time does not pass with them: if it should end during the turns, give it in rounds." : "",
+    ].filter((note) => note !== "");
+}
+/**
+ * The text of a condition of the game system, when the effect bears its name (DAT-6): who believes they know a rule does not look it up. A house rule
+ * on it comes first, with the precedents on it.
+ */
+function conditionNote(root, system, name) {
+    const condition = system?.conditions.find((candidate) => comparableText(candidate) === comparableText(name));
+    if (system === undefined || condition === undefined) {
+        return [];
+    }
+    const rule = ruleTitled(root, system, condition);
+    if (rule === undefined) {
+        return [];
+    }
+    const source = rule.source === houseRules ? ", by a house rule of the campaign" : "";
+    return [`${condition} is a condition of the system ${system.name}${source}:\n${ruleBlock(rule)}`];
+}
+/** "1m is 10 rounds of 6 seconds.": a duration in time that became rounds, in a scene with turns (DAT-7). */
+function roundsNote(duration, end, system) {
+    const minutes = duration === undefined ? undefined : readDuration(duration);
+    if (minutes === undefined || end === undefined || !("round" in end) || system?.roundSeconds === undefined) {
+        return [];
+    }
+    const rounds = Math.ceil((minutes * 60) / system.roundSeconds);
+    return [`${duration?.trim() ?? ""} is ${rounds} ${rounds === 1 ? "round" : "rounds"} of ${system.roundSeconds} seconds.`];
+}
+/** The value an effect would give, such as 18 for "+2" on ac 16; 16 when the change is not a number added to one. */
+function exampleValue(current, text) {
+    return typeof current === "number" && /^[+-]\d+$/.test(text.trim()) ? current + Number(text.trim()) : 16;
+}

package/dist/commands/find.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export declare const find: import("../core/registry.ts").Command<z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        place: "place";
+        quest: "quest";
+        creature: "creature";
+        character: "character";
+        faction: "faction";
+        item: "item";
+        event: "event";
+        topic: "topic";
+    }>>;
+}, z.core.$strip>, {
+    language: string | undefined;
+    searchHint: string;
+    problems: string[];
+    system: string | undefined;
+    systemMatches: {
+        page: string;
+        type: "place" | "quest" | "creature" | "character" | "faction" | "item" | "event" | "topic" | undefined;
+        excerpt: string | undefined;
+    }[];
+    systemMore: number;
+    systemMoreByName: number;
+    withText: boolean;
+    type: "place" | "quest" | "creature" | "character" | "faction" | "item" | "event" | "topic" | undefined;
+    matches: {
+        page: string;
+        type: "place" | "quest" | "creature" | "character" | "faction" | "item" | "event" | "topic" | undefined;
+        path: string;
+        excerpt: string | undefined;
+    }[];
+}>;

package/dist/commands/find.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { requireCampaign } from "../campaign/index.js";
+import { defineCommand } from "../core/registry.js";
+import { pageTypeNames, searchPages, searchSystemPages } from "../pages/index.js";
+import { campaignWorld, foreignSystemLanguage, systemSearchHint } from "./game-world.js";
+import { skippedPagesNote } from "./notes.js";
+// The pages of the game system that find lists for one text; the others are counted.
+const listedSystemPages = 10;
+export const find = defineCommand({
+    name: "find",
+    description: "Find pages of the world. "
+        + "It looks for a text in their names, fields and text, or lists the pages of a type; the game system's pages only by their names and fields. "
+        + "Use it when you do not know a page's exact name, and before creating a page, to check that it does not exist under another name. "
+        + 'Example: text "lanterna"; or type place.',
+    group: "game",
+    readOnly: true,
+    positionals: ["text"],
+    input: z.object({
+        text: z.string().optional().describe("text to look for, ignoring case; every page if left out"),
+        type: z.enum(pageTypeNames).optional().describe(`only pages of this type: ${pageTypeNames.join(", ")}`),
+    }),
+    run(input, context) {
+        const world = campaignWorld(requireCampaign(context.folder), context);
+        const matches = searchPages(world, input).map(({ page, excerpt }) => ({ page: page.name, type: page.type, path: page.path, excerpt }));
+        // The game system's pages are found by name only, and listed only for a text: there may be hundreds (SYS-3).
+        const withText = (input.text?.trim() ?? "") !== "";
+        const system = searchSystemPages(world, input);
+        const listed = withText ? system.slice(0, listedSystemPages).map(({ page, excerpt }) => ({ page: page.name, type: page.type, excerpt })) : [];
+        const byName = system.slice(listed.length).filter((match) => match.excerpt === undefined).length;
+        const systemFound = { system: world.system?.name, systemMatches: listed, systemMore: system.length - listed.length, systemMoreByName: byName, withText, type: input.type };
+        return { matches, ...systemFound, language: foreignSystemLanguage(world), searchHint: systemSearchHint(world).trim(), problems: world.problems };
+    },
+    format(result) {
+        const lines = result.matches.map((match) => `${match.page} (${match.type ?? "free page"})${match.excerpt === undefined ? "" : `: ${match.excerpt}`}`);
+        const system = result.systemMatches.map((match) => `${match.page} (${match.type ?? "page"}, system ${result.system ?? ""})${match.excerpt === undefined ? "" : `: ${match.excerpt}`}`);
+        const found = [...lines, ...system];
+        const note = systemNote(result, lines.length > 0);
+        // A name said in play and never written is no page: the player who remembers it is right (D-266).
+        const unwritten = result.withText ? " What was said in play and never written is not in the files: if the player remembers it, write it." : "";
+        const none = `${note === "" || result.withText ? "No page matches." : "No page of the campaign matches."}${unwritten}`;
+        return [found.length > 0 ? found.join("\n") : none, note, skippedPagesNote(result.problems)].filter((block) => block !== "").join("\n\n");
+    },
+});
+/** What find says of the game system's pages it does not list: how many more there are and how to find them, or that it names them in another language. */
+function systemNote(result, listed) {
+    if (result.system === undefined) {
+        return "";
+    }
+    const named = result.language;
+    if (!result.withText && result.systemMore > 0) {
+        const what = result.type === undefined ? "pages" : `${result.type}s`;
+        const language = named === undefined ? "" : `, named in ${named}`;
+        return `The system ${result.system} has ${result.systemMore}${listed ? " more" : ""} ${what}${language}: give part of a name${named === undefined ? "" : `, in ${named},`} to find them.`;
+    }
+    // Those by name come first: what is left beyond them is found only in fields, which more of a name will not narrow.
+    if (result.systemMore > 0) {
+        const fields = result.systemMore - result.systemMoreByName;
+        const how = result.systemMoreByName > 0 ? "give more of the name" : "find takes one text: give a rarer one, or show a page that lists them";
+        const which = result.systemMoreByName > 0 && fields > 0 ? ` (${result.systemMoreByName} by name, ${fields} in their fields)` : result.systemMoreByName === 0 ? " whose fields name it" : "";
+        return `And ${result.systemMore} more of the system ${result.system}${which}: ${how}.`;
+    }
+    // Nothing of the system found: how find looks for its pages, when nothing at all was found or they are named in another language (D-165).
+    return result.withText && result.systemMatches.length === 0 && (!listed || named !== undefined) ? result.searchHint : "";
+}

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

@@ -0,0 +1,50 @@
+import type { Context } from "../core/context.ts";
+import { type World } from "../pages/index.ts";
+import { type GameDate } from "../time/index.ts";
+import { type DatedEvent } from "./game-events.ts";
+/** What time passing did, as outputs tell it. */
+export interface TimePassed {
+    /** Undefined when an advance set the date the game starts on. */
+    from?: string;
+    to: string;
+    passed: number;
+    wanted: number;
+    /** The events it stopped at. */
+    due: string[];
+    /** Events whose date had already come, still planned. */
+    stillDue: string[];
+    next?: string;
+    /** Planned events whose date is not a game date: time does not stop at them. */
+    unreadable: string[];
+    /** Files of the world that could not be read as pages. */
+    skipped: string[];
+    /** The scene still open after an hour or more: "Alla locanda (since day 1, 18:00)" (D-115). */
+    openScene?: string;
+    /** The effects whose end in game time this advance reached (EFF-8). */
+    ended: string[];
+    /** What holds around the player character after an hour or more (ENV-5): "Ettore: light: dark (Cripta)". */
+    around?: string;
+    /** How many midnights it passed, and the clocks to move then (EVT-8), with how to move them the first time in a chat (D-97). */
+    newDays: number;
+    clocks: string[];
+    newDayPart: string;
+}
+/**
+ * Lets `wanted` minutes pass from `now` (TIM-5), stopping at the first planned event whose date comes (TIM-6): writes the new date and a public line with `why`,
+ * ends the effects whose time came (EFF-8), and says the clocks to move on a new day (EVT-8).
+ */
+export declare function passTime(root: string, context: Context, world: World, now: GameDate, wanted: number, why: string | undefined, requested: string): TimePassed;
+/**
+ * What outputs say after time passed, line by line: the effects ended, the events due with how to play them and `then`, what to do after them, those still due,
+ * the next, the open scene, what holds around, the clocks of a new day, and what could not be read.
+ */
+export declare function passedLines(result: TimePassed, then: string): string[];
+/** The planned events whose date is not a game date, and the files that are no pages: what an advance says it could not read. */
+export declare function unreadNotes(world: World): {
+    unreadable: string[];
+    skipped: string[];
+};
+/** The first events after `date`: all those at the same moment. */
+export declare function nextAfter(events: DatedEvent[], date: GameDate): string | undefined;
+/** "Ettore: light: dark (Cripta)": what holds around the player character, for rules that count the hours spent there (ENV-5); undefined when nothing does. */
+export declare function aroundLead(world: World): string | undefined;