rpg-engine 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefano Caronia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+<p align="center"><img src="https://raw.githubusercontent.com/stefanocaronia/rpg-engine/main/docs/logo.png" width="160" alt="The RPG Engine mascot: a yellow robot behind a game master's screen"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# RPG Engine
+
+Play a tabletop role-playing game with an **AI as your game master**.
+
+![The dashboard during a fight in a tavern: the place's picture, the scene with the party and two hooded bandits, the quest under way and the last rolls](https://raw.githubusercontent.com/stefanocaronia/rpg-engine/main/docs/screenshots/scene.png)
+
+## A world that resists
+
+A game needs a world that resists: a locked door stays locked even when the story would like it open, the arrows run out, a dead innkeeper stays dead. Without that there is nothing to win and nothing to lose, only a story that bends to whoever tells it.
+
+An AI is a wonderful storyteller, but a storyteller tends to make the world fit the story. RPG Engine gives the master determinism: dice that are rolled, not narrated; mechanics that work the same way every time; things that stay where they were left, even when no one is looking. A world with its own rules and its own memory, independent of the master and of us. The AI tells the story and plays everyone else; RPG Engine **keeps the world**, **rolls the dice** and **keeps the accounts**.
+
+## What you can do
+
+- **Play in a chat** with the master, with the **dashboard** open beside it: your sheet, the dice, the maps, the journal.
+- **Let the master create the world** as you play, from a premise; **prepare an adventure** before you start, on what you agree together; or **bring your own** adventures, notes and house rules, which the master sets up, secrets and all.
+- **Travel with companions** that the master plays as characters of their own, each with what they know and how they feel.
+- **Roll real dice**, on the page or your own at the table: the master cannot bend them.
+- **Keep secrets secret**: the master never reveals what your character has not discovered.
+- **Live in a world that moves**: time passes, and threats advance while you rest or travel.
+- **Fight and explore** in scenes with turns, on maps of places and of the world, travelling by road or across country.
+- **Follow quests** with goals and deadlines, and a **journal** that tells your story in chapters.
+- **Save**, as in a video game: at the end of every scene, to go back or start over as you choose.
+- **Choose how you play**: difficulty, lethality, how much the master teaches the rules, its style, your lines and veils.
+- **Play in your language**: the dashboard speaks 26, and any other is translated for you. With Claude Code or Codex on your computer, the master also draws places, quests and the people you meet.
+
+## The game
+
+Today RPG Engine plays **fifth edition**, from the free System Reference Document 5.1: races, classes, the 319 spells, items, monsters, and the rules chapters, which the master reads by their exact text. Your sheet works itself out, as a digital character sheet does. A class the SRD lacks, a monster from a manual you own: the master writes them into your campaign, and RPG Engine treats them as its own.
+
+![Your character's sheet on the dashboard: hit points, armor class, experience, the spell slots and hit dice left, and the last rolls](https://raw.githubusercontent.com/stefanocaronia/rpg-engine/main/docs/screenshots/party.png)
+
+## Coming later
+
+- **Play as the master**, with the AI playing the party.
+- **An authoring mode**: write an adventure with the AI, then export it and share it.
+- **Several players on the same computer**, each with their own character, taking turns in the same chat.
+- **Extensions**: settings, adventures, features such as the weather, house rules to share.
+- **Other game systems**, and your own.
+
+## What you need
+
+**Node.js 22** or newer, a web browser, and an AI agent to be the master: an AI app that can work with the files on your computer, such as Claude Code, Codex or Gemini CLI. A plain chat such as claude.ai or ChatGPT, or a phone app, is not enough: the master needs to reach the campaign's files on your computer.
+
+RPG Engine is tied to no AI company: any agent that supports MCP tools can be the master, local ones included. We play and test it with **Claude Code**; **Codex** is connected and checked, but no whole campaign has been played with it yet; `rpg init` also sets up Gemini CLI, and [the guide](https://github.com/stefanocaronia/rpg-engine/blob/main/src/dashboard/guide/en.md#24-connect-your-ai) says how to connect any other agent. Give the master the largest model you have: a small one is easier to talk into revealing secrets or bending the rules.
+
+RPG Engine is free: the master runs on your agent's own plan (for Claude Code, a paid Claude plan; for Codex, a ChatGPT account), or on your computer with a local model. You do not need to know how to program, and once your agent is installed, you are playing in a few minutes.
+
+## Quick start
+
+Open a terminal in the folder where you keep your games, and type:
+
+```text
+npm install -g rpg-engine
+rpg init "The Salt Isles"
+cd "The Salt Isles"
+claude
+```
+
+With Codex write `codex`; with another agent, start it in that folder (the guide says how to connect it). When it asks whether you trust the folder, say yes; careful, in Claude Code the answer already selected is *No, exit*.
+
+Then write *Hi! Let's start.* The master answers with the link to your dashboard: open it beside the chat. It asks how you want to play, a few questions at a time, then you make your character together, and the story begins.
+
+**[The complete guide](https://github.com/stefanocaronia/rpg-engine/blob/main/src/dashboard/guide/en.md)** ([in Italian](https://github.com/stefanocaronia/rpg-engine/blob/main/src/dashboard/guide/it.md)) explains every step, and then how to play; the dashboard shows it in its Help.
+
+## Try it, and tell us
+
+RPG Engine is at its first versions, and it grows with the games played on it. Try it, and when something breaks, confuses you or could work better, open an [issue on GitHub](https://github.com/stefanocaronia/rpg-engine/issues): what you did, what you expected, what happened. Every report helps.
+
+## How it works
+
+RPG Engine is an MCP server and a command line, `rpg`, made from the same commands. `rpg init` writes into the campaign folder the few files that tell your AI app where RPG Engine is, and that keep the app's own memory off: the campaign lives in its files, and only there, so that going back to a save really goes back.
+
+A campaign is a folder of markdown pages with `[[links]]`, the format of Obsidian, with its settings, its state, a log of every change and its saves. It holds the secrets of your story: you never need to open it.
+
+RPG Engine stays in that folder: it reads and writes the game only there, and never touches your other files. Outside it, it keeps only a data folder of its own (the dashboard's translations, and Codex or Claude Code if you let it install them) and temporary folders while a picture is drawn. The master plays through RPG Engine's tools; anything else your agent wants to do on your computer, it asks you first.
+
+For developers: [the architecture](https://github.com/stefanocaronia/rpg-engine/blob/main/docs/architecture.md), [the commands](https://github.com/stefanocaronia/rpg-engine/blob/main/docs/commands.md), [game systems](https://github.com/stefanocaronia/rpg-engine/blob/main/docs/game-systems.md) and [the guide for development agents](https://github.com/stefanocaronia/rpg-engine/blob/main/AGENTS.md).
+
+## License
+
+The code is under the [MIT](https://github.com/stefanocaronia/rpg-engine/blob/main/LICENSE) license.
+
+The 5e system, in `systems/5e/`, is under the Creative Commons Attribution 4.0 International License ([its license](https://github.com/stefanocaronia/rpg-engine/blob/main/systems/5e/LICENSE.md)): This work includes material taken from the System Reference Document 5.1 ("SRD 5.1") by Wizards of the Coast LLC and available at https://dnd.wizards.com/resources/systems-reference-document. The SRD 5.1 is licensed under the Creative Commons Attribution 4.0 International License available at https://creativecommons.org/licenses/by/4.0/legalcode. Its creatures' icons are from game-icons.net, under the Creative Commons Attribution 3.0 Unported License, by the authors its license names. rpg-engine is compatible with fifth edition.
+
+rpg-engine ships only original or open-licensed content: for fifth edition, the SRD 5.1 under CC BY 4.0. Anything else that appears in your game is written by your AI or by you, as pages of your campaign on your computer: it is not part of rpg-engine, and we do not distribute it.
+
+The tests use a system based on Ironsworn, with the names of its mechanics and a foe of our own: This work is based on Ironsworn (https://www.ironswornrpg.com), created by Shawn Tomkin, and licensed for our use under the Creative Commons Attribution 4.0 International License (https://creativecommons.org/licenses/by/4.0/).
+
+## Development notes
+
+Developed with the help of AI coding agents. Everything is designed, reviewed and tested by the project's human maintainer.
+
+**We encourage everyone to use AI for their own purposes.**  
+The means of production should belong to the people.  
+Fight corporate control of technology, not our right to use it.
+
+---
+
+© 2026 [Stefano Caronia](https://stefanocaronia.it) · [GitHub](https://github.com/stefanocaronia/rpg-engine) · [npm](https://www.npmjs.com/package/rpg-engine) · [♥ Support RPG Engine](https://www.paypal.com/paypalme/stefanocaronia)

package/dist/campaign/create-campaign.d.ts

@@ -0,0 +1,6 @@
+import { type CampaignSettings } from "./settings.ts";
+/**
+ * Creates a campaign in `folder`: campaign.yaml, state.yaml, the sessions folder, the .mcp.json through which AI hosts such as Claude Code find the rpg tools,
+ * and the host files that send them to the start lines (D-97, D-242). `platform` is the operating system, as Node names it. Returns the campaign's full path.
+ */
+export declare function createCampaign(folder: string, settings: CampaignSettings, platform: string, startLines: string): string;

package/dist/campaign/create-campaign.js

@@ -0,0 +1,71 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { stringify } from "yaml";
+import { z } from "zod";
+import { files } from "../core/store.js";
+import { campaignFileName, findCampaign } from "./find-campaign.js";
+import { hostFileChanges, rpgServer } from "./host-files.js";
+import { settingsSchema } from "./settings.js";
+/**
+ * Creates a campaign in `folder`: campaign.yaml, state.yaml, the sessions folder, the .mcp.json through which AI hosts such as Claude Code find the rpg tools,
+ * and the host files that send them to the start lines (D-97, D-242). `platform` is the operating system, as Node names it. Returns the campaign's full path.
+ */
+export function createCampaign(folder, settings, platform, startLines) {
+    const root = resolve(folder);
+    checkNoOtherCampaign(root);
+    const parsed = settingsSchema.safeParse(settings);
+    if (!parsed.success) {
+        throw new Error(`The campaign settings are not valid:\n${z.prettifyError(parsed.error)}`);
+    }
+    const mcpConfig = mcpConfigWithRpg(root, platform);
+    const hostFiles = hostFileChanges(root, startLines, platform);
+    files().makeFolder(join(root, "sessions"));
+    files().write(join(root, campaignFileName), `# Campaign settings: change them with the config command.\n${stringify(parsed.data)}`);
+    // A new campaign starts in setup (MOD-1).
+    files().write(join(root, "state.yaml"), "# The present of the game, kept by rpg: mode, date and current scene.\nmode: setup\n");
+    files().write(join(root, ".mcp.json"), JSON.stringify(mcpConfig, null, 2) + "\n");
+    hostFiles.forEach((file) => files().write(file.path, file.text));
+    return root;
+}
+/** The folder's .mcp.json with the rpg server added; other servers already listed stay. On Windows a host must start rpg through cmd. */
+function mcpConfigWithRpg(root, platform) {
+    const path = join(root, ".mcp.json");
+    let config = {};
+    if (files().exists(path)) {
+        try {
+            config = JSON.parse(files().text(path) ?? "");
+        }
+        catch {
+            throw new Error(`${path} is not valid JSON, so the rpg server cannot be added to it. Fix it or remove it by hand, then create the campaign again.`);
+        }
+    }
+    return { ...config, mcpServers: { ...config.mcpServers, rpg: rpgServer(platform) } };
+}
+/** A campaign cannot sit inside another one, nor hold one. */
+function checkNoOtherCampaign(root) {
+    const outer = findCampaign(root);
+    if (outer !== undefined) {
+        throw new Error(outer === root ? `${root} is already a campaign.` : `${root} is inside the campaign in ${outer}, and a campaign cannot hold another one: pick a folder outside it.`);
+    }
+    const inner = campaignBelow(root, 3);
+    if (inner !== undefined) {
+        throw new Error(`${root} holds the campaign in ${inner}, and a campaign cannot hold another one: pick another folder.`);
+    }
+}
+/** The first campaign in the folders below `folder`, down to `depth` levels; hidden folders and node_modules are skipped. */
+function campaignBelow(folder, depth) {
+    if (depth === 0 || !existsSync(folder)) {
+        return undefined;
+    }
+    for (const entry of readdirSync(folder, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") {
+            continue;
+        }
+        const child = join(folder, entry.name);
+        const found = existsSync(join(child, campaignFileName)) ? child : campaignBelow(child, depth - 1);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return undefined;
+}

package/dist/campaign/find-campaign.d.ts

@@ -0,0 +1,8 @@
+/** The file that marks a folder as a campaign and holds its settings. */
+export declare const campaignFileName = "campaign.yaml";
+/** The folder of a campaign with its house rules, a markdown file for each (D-178). */
+export declare const houseRulesFolderName = "rules";
+/** The campaign that holds `folder`: the nearest folder, from `folder` upwards, with a campaign.yaml. */
+export declare function findCampaign(folder: string): string | undefined;
+/** Like findCampaign, but fails with a message that says how to get into a campaign. */
+export declare function requireCampaign(folder: string): string;

package/dist/campaign/find-campaign.js

@@ -0,0 +1,28 @@
+import { dirname, join, resolve } from "node:path";
+import { files } from "../core/store.js";
+/** The file that marks a folder as a campaign and holds its settings. */
+export const campaignFileName = "campaign.yaml";
+/** The folder of a campaign with its house rules, a markdown file for each (D-178). */
+export const houseRulesFolderName = "rules";
+/** The campaign that holds `folder`: the nearest folder, from `folder` upwards, with a campaign.yaml. */
+export function findCampaign(folder) {
+    let current = resolve(folder);
+    while (!files().exists(join(current, campaignFileName))) {
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+    return current;
+}
+/** Like findCampaign, but fails with a message that says how to get into a campaign. */
+export function requireCampaign(folder) {
+    const root = findCampaign(folder);
+    if (root === undefined) {
+        throw new Error(`There is no campaign here: no ${campaignFileName} in ${resolve(folder)} or in the folders above it. Create one with the init command, or work from inside a campaign folder.`);
+    }
+    // The session of the MCP server watches the campaign from the first call that finds it (D-193).
+    files().track(root);
+    return root;
+}

package/dist/campaign/host-files.d.ts

@@ -0,0 +1,16 @@
+/** The files of the AI hosts at the top of a campaign, which are not the game's: a save leaves them as they are (SAV-2). */
+export declare const hostFileNames: string[];
+/** A file to write, with its new text. */
+export interface HostFile {
+    path: string;
+    text: string;
+}
+/** How a host starts the rpg server: on Windows through cmd. */
+export declare function rpgServer(platform: string): {
+    command: string;
+    args: string[];
+};
+/** The host files of a campaign that are missing or out of date, with the start lines given; a broken settings file of a host stops it with how to fix it. */
+export declare function hostFileChanges(root: string, startLines: string, platform: string): HostFile[];
+/** Brings the host files of a campaign up to date, as the MCP server starts: a file that cannot be read or written stays as it is. */
+export declare function refreshHostFiles(root: string, startLines: string, platform: string): void;

package/dist/campaign/host-files.js

@@ -0,0 +1,134 @@
+// What an AI host reads in a campaign besides .mcp.json: AGENTS.md, opening with the start lines (D-97); CLAUDE.md, which imports it; Claude Code's settings,
+// with its auto memory off, so that the master keeps nothing outside the campaign (D-242), and the rpg server approved with its tools allowed (D-412); Codex's,
+// with the rpg server and its memories off, and Gemini CLI's, with the rpg server, AGENTS.md and no writing of files by itself, where a memory would go (D-362).
+import { join } from "node:path";
+import { files } from "../core/store.js";
+/** The files of the AI hosts at the top of a campaign, which are not the game's: a save leaves them as they are (SAV-2). */
+export const hostFileNames = ["AGENTS.md", "CLAUDE.md", "CLAUDE.local.md", "GEMINI.md"];
+// The marks around the start lines in AGENTS.md: rpg rewrites what lies between them, and the player's own text stays around them.
+const startMark = "<!-- rpg: rpg keeps the lines up to the end mark up to date; the player's own instructions go after it. -->";
+const endMark = "<!-- rpg: end -->";
+const markedBlock = /^<!-- rpg: (?!end)[^\n]*\n[\s\S]*?^<!-- rpg: end[^\n]*$/m;
+/** How a host starts the rpg server: on Windows through cmd. */
+export function rpgServer(platform) {
+    return platform === "win32" ? { command: "cmd", args: ["/c", "rpg", "mcp"] } : { command: "rpg", args: ["mcp"] };
+}
+/** The host files of a campaign that are missing or out of date, with the start lines given; a broken settings file of a host stops it with how to fix it. */
+export function hostFileChanges(root, startLines, platform) {
+    return hostFiles(root, startLines, platform).map((file) => file()).filter((file) => file !== undefined);
+}
+/** Brings the host files of a campaign up to date, as the MCP server starts: a file that cannot be read or written stays as it is. */
+export function refreshHostFiles(root, startLines, platform) {
+    for (const change of hostFiles(root, startLines, platform)) {
+        try {
+            const file = change();
+            if (file !== undefined) {
+                files().write(file.path, file.text);
+            }
+        }
+        catch {
+            // The game goes on with the file as it is.
+        }
+    }
+}
+function hostFiles(root, startLines, platform) {
+    return [() => agentsFile(root, startLines), () => claudeFile(root), () => claudeSettingsFile(root), () => codexConfigFile(root, platform), () => geminiSettingsFile(root, platform)];
+}
+/** AGENTS.md with the start lines between rpg's marks: rewritten when they changed, put first when the file has none, as in a folder that already had one. */
+function agentsFile(root, startLines) {
+    const path = join(root, "AGENTS.md");
+    const text = files().fresh(path);
+    const block = [startMark, startLines, endMark].join("\n");
+    if (text === undefined) {
+        return { path, text: `${block}\n` };
+    }
+    const lines = text.replace(/\r\n/g, "\n");
+    const updated = markedBlock.test(lines) ? lines.replace(markedBlock, () => block) : `${block}\n\n${lines}`;
+    return updated === lines ? undefined : { path, text: text.includes("\r\n") ? updated.replace(/\n/g, "\r\n") : updated };
+}
+/** CLAUDE.md, which Claude Code reads, importing AGENTS.md: added first to one that does not. */
+function claudeFile(root) {
+    const path = join(root, "CLAUDE.md");
+    const text = files().fresh(path);
+    if (text === undefined) {
+        return { path, text: "@AGENTS.md\n" };
+    }
+    return text.split(/\r?\n/).some((line) => line.trim() === "@AGENTS.md") ? undefined : { path, text: `@AGENTS.md\n${text}` };
+}
+/**
+ * Claude Code's settings for the campaign: its auto memory off, and the rpg server of .mcp.json approved with its tools allowed, so that the first chat neither
+ * asks whether to use it, with "continue without" chosen, nor asks for each tool (D-412); a value already written there is the player's, and stays.
+ */
+function claudeSettingsFile(root) {
+    const path = join(root, ".claude", "settings.json");
+    const text = files().fresh(path);
+    const settings = text === undefined ? {} : jsonObject(path, text, "Claude Code cannot be set up for the game in it");
+    const permissions = isObject(settings.permissions) ? settings.permissions : {};
+    const wanted = {
+        ...settings,
+        autoMemoryEnabled: settings.autoMemoryEnabled ?? false,
+        enabledMcpjsonServers: settings.enabledMcpjsonServers ?? ["rpg"],
+        permissions: { ...permissions, allow: permissions.allow ?? ["mcp__rpg"] },
+    };
+    return text !== undefined && JSON.stringify(wanted) === JSON.stringify(settings) ? undefined : { path, text: settingsText(wanted) };
+}
+/**
+ * Codex's settings for the campaign, read when the player trusts the folder: the rpg server, its tools approved and its calls waiting for the player's click
+ * as long as the server does (D-412), and its memories off; a table already written is the player's, and stays.
+ */
+function codexConfigFile(root, platform) {
+    const path = join(root, ".codex", "config.toml");
+    const text = files().fresh(path) ?? "";
+    const server = rpgServer(platform);
+    const tables = [
+        ["mcp_servers.rpg", `command = ${JSON.stringify(server.command)}\nargs = [${server.args.map((arg) => JSON.stringify(arg)).join(", ")}]\ntool_timeout_sec = 1800\ndefault_tools_approval_mode = "approve"`],
+        ["memories", "generate_memories = false\nuse_memories = false"],
+    ];
+    const missing = tables.filter(([name]) => !text.split(/\r?\n/).some((line) => line.trim() === `[${name}]`));
+    const parts = [text.trimEnd(), ...missing.map(([name, body]) => `[${name}]\n${body}`)].filter((part) => part !== "");
+    return missing.length === 0 ? undefined : { path, text: `${parts.join("\n\n")}\n` };
+}
+/**
+ * Gemini CLI's settings for the campaign, read when the player trusts the folder: the rpg server, trusted so that its tools ask no confirmation, AGENTS.md as
+ * the file it reads, and write_file and replace excluded, so that the master writes only through rpg's tools and keeps no memory in files; what the player
+ * already wrote there stays, a trust they set included.
+ */
+function geminiSettingsFile(root, platform) {
+    const path = join(root, ".gemini", "settings.json");
+    const text = files().fresh(path);
+    const settings = text === undefined ? {} : jsonObject(path, text, "Gemini CLI cannot be set to find the rpg server in it");
+    // Each value the player already wrote stays where it is: the file is written again only for what is missing.
+    const withDefault = (name, key, value) => {
+        const part = isObject(settings[name]) ? settings[name] : {};
+        return key in part ? part : { ...part, [key]: value };
+    };
+    const servers = isObject(settings.mcpServers) ? settings.mcpServers : {};
+    const rpg = isObject(servers.rpg) ? servers.rpg : rpgServer(platform);
+    const wanted = {
+        ...settings,
+        mcpServers: { ...servers, rpg: "trust" in rpg ? rpg : { ...rpg, trust: true } },
+        context: withDefault("context", "fileName", ["AGENTS.md"]),
+        tools: withDefault("tools", "exclude", ["write_file", "replace"]),
+    };
+    return text !== undefined && JSON.stringify(wanted) === JSON.stringify(settings) ? undefined : { path, text: settingsText(wanted) };
+}
+/** A host's settings file read as a JSON object; refused, with how to fix it, when it is not one. */
+function jsonObject(path, text, cannot) {
+    let settings;
+    try {
+        settings = JSON.parse(text.replace(/^\uFEFF/, ""));
+    }
+    catch {
+        settings = undefined;
+    }
+    if (!isObject(settings)) {
+        throw new Error(`${path} is not valid JSON, so ${cannot}. Fix it or remove it by hand, then create the campaign again.`);
+    }
+    return settings;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function settingsText(settings) {
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}

package/dist/campaign/index.d.ts

@@ -0,0 +1,5 @@
+export { createCampaign } from "./create-campaign.ts";
+export { campaignFileName, findCampaign, houseRulesFolderName, requireCampaign } from "./find-campaign.ts";
+export { hostFileNames, refreshHostFiles } from "./host-files.ts";
+export { type CampaignSettings, changeListSetting, changeListSettingToNone, changeMapSetting, changeOtherSetting, changeSetting, checkSettingName, checkSettings, clearSetting, companionWays, diceWays, difficulties, lethalities, listSettingNames, mapSettingNames, mentorWays, missingSettings, pictureWays, preparations, proseWays, readCampaignData, readCoinsSetting, readListSetting, readOneSetting, readSettings, readTextSetting, rigors, saveModes, settingMeaning, type SettingName, settingNames, setupSettingNames, storyWays, styleTextLengths, unansweredSettings, unitSystems, } from "./settings.ts";
+export { type CampaignState, changeState, changeStateAt, readState, readStateValues } from "./state.ts";

package/dist/campaign/index.js

@@ -0,0 +1,6 @@
+// The campaign: a folder with campaign.yaml, its settings, the present, the sessions and the files an AI host reads.
+export { createCampaign } from "./create-campaign.js";
+export { campaignFileName, findCampaign, houseRulesFolderName, requireCampaign } from "./find-campaign.js";
+export { hostFileNames, refreshHostFiles } from "./host-files.js";
+export { changeListSetting, changeListSettingToNone, changeMapSetting, changeOtherSetting, changeSetting, checkSettingName, checkSettings, clearSetting, companionWays, diceWays, difficulties, lethalities, listSettingNames, mapSettingNames, mentorWays, missingSettings, pictureWays, preparations, proseWays, readCampaignData, readCoinsSetting, readListSetting, readOneSetting, readSettings, readTextSetting, rigors, saveModes, settingMeaning, settingNames, setupSettingNames, storyWays, styleTextLengths, unansweredSettings, unitSystems, } from "./settings.js";
+export { changeState, changeStateAt, readState, readStateValues } from "./state.js";

package/dist/campaign/settings.d.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { unitSystems } from "../core/length.ts";
+import type { Problem } from "../core/problem.ts";
+/** How hard the world plays (D-13, D-141). */
+export declare const difficulties: readonly ["story", "easy", "normal", "hard", "brutal"];
+/** What a fall means (D-13, D-141): the character never dies, dies only when it matters, or as the dice say. */
+export declare const lethalities: readonly ["narrative", "epic", "dice"];
+/** When the game may go back (D-55): never, to the last end of a scene once the player character dies, or to any save, which the player may also ask for. */
+export declare const saveModes: readonly ["permadeath", "checkpoint", "free"];
+/** How closely the rules are followed, apart from difficulty (D-42): the master glosses over them, as they are written, or beyond them. */
+export declare const rigors: readonly ["smooth", "rules", "simulation"];
+/** What each difficulty means in play, from the GDD's table, which status and config give for the chosen one (D-263); fights in the words of a budget of low, moderate and high (D-266). */
+export declare const difficultyMeanings: Record<(typeof difficulties)[number], string>;
+/** What each rigor means in play (D-42, D-263): what the master counts, which status and config give for the chosen one. */
+export declare const rigorMeanings: Record<(typeof rigors)[number], string>;
+/** How much the master teaches the game, out of the story (D-347): the story alone, a hint now and then, or each rule as it first comes up. */
+export declare const mentorWays: readonly ["off", "hints", "tutorial"];
+/** What each way of the mentor means to the master, which config gives for the chosen one, and the player's change of it on the dashboard (D-347). */
+export declare const mentorMeanings: Record<(typeof mentorWays)[number], string>;
+/** What the chosen difficulty, rigor or mentor means, as status and config give it; undefined for another setting or a value it does not take. */
+export declare function settingMeaning(name: string, value: unknown): string | undefined;
+/** Who rolls the player character's dice (D-241): rpg, or the player with their own, telling the values; the master's are always rolled by rpg. */
+export declare const diceWays: readonly ["digital", "physical"];
+export { unitSystems };
+/** Which pictures the engine has made, where it can (D-308, D-388, D-420): none, only those the player asks for, or one for each new place, quest and one met. */
+export declare const pictureWays: readonly ["none", "on request", "new elements"];
+/** How the companions come (D-76, D-221): none, made in session zero with the player or by the master, or met in play. */
+export declare const companionWays: readonly ["none", "made with the player", "made by the master", "met in play"];
+/** How far ahead a world without a written campaign is made (D-80): as it is needed, or all at the start. */
+export declare const preparations: readonly ["on the fly", "all at the start"];
+/** How the master writes (D-395): plain, the core's own, literary, pulp or wry; the tone stays in the premise, and an author takes its place. */
+export declare const proseWays: readonly ["plain", "literary", "pulp", "wry"];
+/** How the master builds what they invent (D-395): situations, the core's own, arcs, episodes or a mystery; a written adventure keeps its own. */
+export declare const storyWays: readonly ["situations", "arcs", "episodes", "mystery"];
+/** The longest text the player's own words of how the master writes may be, by setting (D-395). */
+export declare const styleTextLengths: {
+    readonly author: 80;
+    readonly style: 300;
+};
+/** The settings of a campaign, kept in campaign.yaml. Other keys are kept: systems and extensions will add their own. */
+export declare const settingsSchema: z.ZodObject<{
+    name: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    system: z.ZodOptional<z.ZodString>;
+    mentor: z.ZodOptional<z.ZodEnum<{
+        off: "off";
+        hints: "hints";
+        tutorial: "tutorial";
+    }>>;
+    premise: z.ZodOptional<z.ZodString>;
+    preparation: z.ZodOptional<z.ZodEnum<{
+        "on the fly": "on the fly";
+        "all at the start": "all at the start";
+    }>>;
+    prose: z.ZodOptional<z.ZodEnum<{
+        plain: "plain";
+        literary: "literary";
+        pulp: "pulp";
+        wry: "wry";
+    }>>;
+    story: z.ZodOptional<z.ZodEnum<{
+        situations: "situations";
+        arcs: "arcs";
+        episodes: "episodes";
+        mystery: "mystery";
+    }>>;
+    author: z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>;
+    style: z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>;
+    difficulty: z.ZodOptional<z.ZodEnum<{
+        story: "story";
+        easy: "easy";
+        normal: "normal";
+        hard: "hard";
+        brutal: "brutal";
+    }>>;
+    lethality: z.ZodOptional<z.ZodEnum<{
+        narrative: "narrative";
+        epic: "epic";
+        dice: "dice";
+    }>>;
+    saves: z.ZodOptional<z.ZodEnum<{
+        permadeath: "permadeath";
+        checkpoint: "checkpoint";
+        free: "free";
+    }>>;
+    rigor: z.ZodOptional<z.ZodEnum<{
+        rules: "rules";
+        smooth: "smooth";
+        simulation: "simulation";
+    }>>;
+    dice: z.ZodOptional<z.ZodEnum<{
+        digital: "digital";
+        physical: "physical";
+    }>>;
+    units: z.ZodOptional<z.ZodEnum<{
+        metric: "metric";
+        imperial: "imperial";
+    }>>;
+    companions: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        "made with the player": "made with the player";
+        "made by the master": "made by the master";
+        "met in play": "met in play";
+    }>>;
+    pictures: z.ZodOptional<z.ZodPreprocess<z.ZodEnum<{
+        none: "none";
+        "on request": "on request";
+        "new elements": "new elements";
+    }>, unknown>>;
+    lines: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>, unknown>>>;
+    veils: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>, unknown>>>;
+    table: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>, unknown>>>;
+    precedents: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>, unknown>>>;
+    learned: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodArray<z.ZodPreprocess<z.ZodString, unknown>>, unknown>>>;
+    coins: z.ZodOptional<z.ZodUnknown>;
+    fields: z.ZodOptional<z.ZodUnknown>;
+    tables: z.ZodOptional<z.ZodUnknown>;
+    computed: z.ZodOptional<z.ZodUnknown>;
+    counters: z.ZodOptional<z.ZodUnknown>;
+    recipes: z.ZodOptional<z.ZodUnknown>;
+    "status-line": z.ZodOptional<z.ZodUnknown>;
+    travel: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+export type CampaignSettings = z.infer<typeof settingsSchema>;
+export type SettingName = keyof typeof settingsSchema.shape;
+/** The settings that the config command shows and changes. */
+export declare const settingNames: SettingName[];
+/** The settings that hold a list, changed one item at a time; none of them is ever missing in play. */
+export declare const listSettingNames: SettingName[];
+/** The settings that hold entries by name, what the campaign adds to its game system (CAM-1): given or removed one entry at a time. */
+export declare const mapSettingNames: SettingName[];
+/** What only the setup asks (D-241, MOD-3, D-347): how much the master teaches the game, how the companions come, and the lines and veils, which "none" answers too. */
+export declare const setupSettingNames: SettingName[];
+/** What the setup asks only of a campaign without a written world (D-79, D-80, MOD-3). */
+export declare const premiseSettingNames: SettingName[];
+export declare function readSettings(root: string): CampaignSettings;
+/** The coins as campaign.yaml writes them, unchecked and read on their own, so that a mistake in another setting does not hide them; the money module checks them (MON-1). */
+export declare function readCoinsSetting(root: string): unknown;
+/**
+ * A text setting as campaign.yaml writes it, such as the system or the language, read even when another setting breaks the file: YAML still gives the keys it can (SYS-1).
+ * Undefined when it is missing, not text, or the file cannot be read.
+ */
+export declare function readTextSetting(root: string, name: string): string | undefined;
+/** A list setting as campaign.yaml writes it, read even when another setting breaks the file, as the system is (SYS-1): what rules reads. Empty when it cannot be read. */
+export declare function readListSetting(root: string, name: SettingName): string[];
+export declare function readOneSetting(root: string, name: string): unknown;
+/**
+ * Changes one setting and keeps the rest of campaign.yaml, comments included, as it is. Nothing is written if the setting already has that value, or if the settings would not be valid.
+ * Returns whether it changed. The value is text, or for coins the list already read.
+ */
+export declare function changeSetting(root: string, name: string, value: unknown): boolean;
+/** Takes away a setting the player may leave unset again, as the author the master writes like (D-395). Returns whether it changed. */
+export declare function clearSetting(root: string, name: string): boolean;
+/**
+ * Writes a setting that is not the campaign's own but one a game system adds (DAT-10), as text, keeping the rest of campaign.yaml as it is; its value is checked by
+ * who knows the system. Returns whether it changed.
+ */
+export declare function changeOtherSetting(root: string, name: string, value: string): boolean;
+/** Adds items to a list setting, or removes them, keeping the rest of campaign.yaml as it is. Returns whether it changed. */
+export declare function changeListSetting(root: string, name: string, change: {
+    add?: string[];
+    remove?: string[];
+}): boolean;
+/** Answers a list setting with none (MOD-3): an empty list, refused while it holds items, which are removed one by one. Returns whether it changed. */
+export declare function changeListSettingToNone(root: string, name: string): boolean;
+/** What campaign.yaml adds to the game system, as it writes it, read even when another setting breaks the file (CAM-1); empty when it cannot be read. */
+export declare function readCampaignData(root: string): Record<string, unknown>;
+/**
+ * Gives entries by name to a setting that holds them, such as counters, each in place of one with that name, or removes entries by name (CAM-1); keeps the
+ * rest of campaign.yaml as it is. Returns whether it changed.
+ */
+export declare function changeMapSetting(root: string, name: string, change: {
+    set?: Record<string, unknown>;
+    remove?: string[];
+}): boolean;
+/** What is wrong in campaign.yaml, one problem for each setting, with how to fix it. */
+export declare function checkSettings(root: string): Problem[];
+/** The settings that are still missing: the AI asks the player for them. */
+export declare function missingSettings(settings: CampaignSettings): SettingName[];
+/**
+ * The settings the setup still has to ask, in order (MOD-3): those every campaign needs, how the companions come, the lines and veils until answered, even
+ * with none, and, for a campaign without a written world, its premise and preparation.
+ */
+export declare function unansweredSettings(settings: CampaignSettings, writtenWorld: boolean): SettingName[];
+export declare function checkSettingName(name: string): SettingName;