Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ Release notes for each version; the GitHub release carries the same text and the

## Unreleased

- `export-web` (the command line) reads a game note the way `check-ink` and the plugin do: a `system:` pack is layered under it and `from:` tables, decks, maps and characters are read. Pages exported from a game on a rule pack had lost the pack's rules, party and foes.
- New command "Install rule pack (download)": lists the rule packs published in the public games repo (luoxin9510/ink-games, `systems/`), asks before downloading, then writes the chosen pack into `规则包/<id>/` / `Rule packs/<id>/` (files of the same names are overwritten, others kept; nothing is written when a download fails). "New game" also offers packs installed in the vault, not only the bundled ones. A pack's `system.md` now lists its files (`files:`). `api.availablePacks()`, `api.installPack(id)`.
- Two more rule packs (RPG R6), both in "New game". **Turn battle**: a knight, a mage and a cleric against a band of foes, everyone acting once a round by speed; attacks, arts (shield bash stuns, fireball hits every foe, mend heals and cures), guarding, potions, poison and stun; the story spawns the foes and calls `-> battle ->`, then reads `battle_result`. **Narrative checks**: the rules of the dorm horror game *302* (2d6 checks on choices, six difficulties, five skills that speak as inner voices, fear and stamina, companions' fear and trust, fear lowering reason) plus `clamp()`; a game adds its own characters, resources and items.
- Levels and campaigns (RPG R5). `levels: { resource: xp, at: [0, 4, 10] }` gives the story `level`, `next_level_at()`, `level_up_ready()` and `level_up()`; the status bar shows the level and marks when one can be taken. Perks are ordinary items. A line tagged `#sheet` (or the command "Save character sheet", `api.saveSheet()`) writes the character being played as a note in the game's `sheets:` folder: its frontmatter is a `characters` entry (skills, items, what is worn, counts, level, resources, statuses), its body gets the adventure's epilogue. The next adventure reads such notes with `characters: { from: ../角色 }`. Characters written in `game.md` can also set `equipped`, `level`, `resources` and `statuses`.

Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ PRD: `docs/game-engine-prd.md` — TTRPG-style rules engine on top of Inkwright
- RPG R4 stacks, slots, statuses: `ItemDef.stack` (count VAR `<id><stackSuffix>`, `_n`; `inkgen stackInk`: `give(item, n)`/`take(item, n)` → taken/`inv_count(item)`, list-item arguments, the inventory follows the count; non-stacking items: give adds, take removes one, count 0/1), `CharacterDef.counts` (set in `pick_character`, also carried); `slots: SlotDef[]` + `ItemDef.slot` (`slotInk`: `VAR equipped`, `equip` drops the slot's other items and carries it, `unequip`; `pick_character` equips the first carried item per slot; character only); `collectModifiers` counts a slotted item only while equipped and carried, and the character's own statuses' `modifiers`. `statuses: StatusDef[]` (name, desc, modifiers, `rest`): `src/game/statuses.ts` (pure store `who|id|turns;…`, turns ≤ 0 = until cleared, re-adding keeps the longer; tested in `tests/statuses.test.ts`), `statusInk` (`VAR statuses`, pure EXTERNALs `status_put/in/left/take/tick/rest` with no-engine fallbacks where nothing takes hold, wrappers `add_status(who, id, turns)`, `has_status`, `status_turns`, `clear_status` ("" = all of who's), `tick_statuses`, `rest_statuses`; who = an entity/member id or `InkNames.self` "me"/zh "我"), `GameEngine.bindStatuses`, `statusesOf` → `hud().statuses` (the character's), `PartyMemberView.statuses`, `EntityView.statuses`; `ItemView.count/equipped/slot`. Problems `itemSlot`, `statusSkill`, `countItem`; the new InkNames are reserved only when used (`amountParam` also with stacks). Panel: `status.ts itemChip`/`statusTags` (`.inkwright-item-equipped`, `.inkwright-status`); web `renderHud` `itemText`/`statusText`. Random runs: stack counts in `resources` (as `<id>_n`, no top), `SimulateResult.statuses` (`StatusTally`: appearances between steps, runs). Tests: `tests/game-gear.test.ts`, the web gear test.
- RPG R5 levels and sheets: `levels: LevelsDef` (`resource`, `at`; problems `levelsResource`, `levelsOrder`), `inkgen levelInk` (`VAR level`, `next_level_at`, `level_up_ready`, `level_up`; InkNames reserved only with levels), `hud().level` (`{ level, next, ready }`; panel `chipRow` + `.inkwright-level-ready`, web line). `CharacterDef.equipped/level/resources/statuses` (loaded by `pick_character`; `equipped` over the first carried item per slot; problems `characterLevel`, `characterResource`, `characterStatus`). `src/game/sheet.ts` (pure): `sheetOf(config, state, current)` (the played character as a `characters` entry; `GameEngine.sheet()`), `sheetName`, `sheetNote(yaml, oldBody, epilogue, title, date)` (frontmatter replaced, body kept, a section added), `characterFromNote` (uses `isCharacter` from config.ts). `main.ts`: `saveSheet(epilogue?)` (folder `sheets` relative to the story's, default `T().sheetsFolder`; refused outside the vault; the state read at once, the write queued with `runs.enqueue`; the character's sheet found by frontmatter id, else named by `sheetName`; `ownWrites` makes the change events of that file within `OWN_WRITE_MS` not trigger a recompile, since a camp reads the folder it writes; the engine still goes stale, which is right: the next play needs the new presets), the controller's `RunHost.afterChoose(paragraphs)` (called only after the player takes a choice, with the text it produced; a `#sheet` line there writes, so back/replay/load/language never do), command `save-sheet`, `api.saveSheet`. `characters: { from }` → `GameConfig.charactersFrom` (no `noCharacters` until resolved), `resolve.ts resolveCharacters` (first in `resolveConfig`; the folder and notes are dependencies; problem `charactersFolder`). Tests: `tests/campaign.test.ts`.
- RPG R6 packs: `packs/turn-battle` (no engine changes: party + the `foe` kind; `battle` knot: rounds, `ready_all` clears `acted`, `next_actor` = the fastest standing one not yet acted, heroes first on ties (recursive `fastest` over `nth_one`); a hero's options are threads per foe/ally, a foe acts in `foe_turn`; stun/guard/poison statuses; damage atk + 2d6 - 4 - def; `battle_result`, `battle_round`; balance by a strategy bot: 2026-11-10 numbers in its `说明.md`) and `packs/narrative-check` (dorm-302's rules: difficulties, five voiced skills, fear/hp, companion fear/trust, the fear modifier; `rules.ink` = `clamp`). dorm-302 vendors a copy in `packs/narrative-check/`; its check-ink output was compared before and after the switch. `tests/system.test.ts` plays every template and a 3 on 3 round order.
- RPG R7 install: a pack's `system.md` lists its files (`files:`, pack paths; the template's `_engine.ink` left out; `tests/install.test.ts` checks every bundled pack; `layerSystem` drops `files`). `src/templates/install.ts` (pure: `PACK_SOURCE` = ink-games `systems/` raw URL, `parseIndex` of `systems/index.json`, `isPackId`, `isPackPath` (relative, no `..`/hidden/odd characters), `packFiles`, `packUrl`, `downloadPack(fetchText, source, id, frontmatter)` = system.md then each listed file, all or nothing). `main.ts`: `availablePacks`, `installPack(id, { ask, source })` (`ConfirmModal`, then `requestUrl`, writes into the installed copy's folder or `<packs folder>/<id>`), command `install-pack` (`PackPickModal` shows the installed version); `packBundle()` = bundled packs plus vault-installed ones with a template (installed wins), used by `newGame`/`pickNewGame`. The packs in ink-games must match `packs/` (its build checks).
- Tabletop PRD: `docs/tabletop-prd.md` — solo TTRPG / board-game support on top of game mode: five primitives (free rolls, random tables, decks, `#input`, play log to a note), what qualifies, the order to build them in. Read it before adding any of those.
- Tabletop slice 1, dice and tables: `src/game/dice.ts` parses and rolls formulas (`parseFormula`, `rollFormula`; `d66` is two d6 read as tens and units); `src/game/tables.ts` is the table logic (ranges, the dice given or inferred, `rowAt`, `tableProblems` for gaps/overlaps/bad dice, `rowsFromMarkdown` for a note's first markdown table, `resolveTables` fills `from:` tables in and lists the notes read). The engine binds one more EXTERNAL, `roll_dice(formula, label)`, on the check's seed and roll counter; `roll(formula)`, `table_roll`, `table_text`, `table_id` and `table(name)` are generated ink: the lookups are plain ink, so a story reads the same row without the engine (the fallback `roll_dice` returns each table's average, 1 for other dice). `engine.rolls` is `CheckRecord | DiceRecord` (`kind`); the panel, the web player and the journal render both kinds of card. The explorer gives the engine a fixed rng, so table rolls repeat between walks; the config's `from:` notes are compile dependencies (`GameNoteRead.files`), and `main.ts` resolves them wherever it loads a config (`resolveConfig`; `gameConfigFor` is async; `check-ink` reads them from disk). Formulas may explode (`d6!`, `DiceFormula.explode`: a top face rolls another die, faces appended, at most 20 extra; `averageFormula` uses the exploding mean). Keep highest/lowest (`4d6kh3`, `2d20kl` = kl1; `DiceFormula.keep`, not with explode/pool/d66; ties keep the earlier die; `averageFormula` sums the expected order statistics, `keptMean`) and pools (`5d6>=5`, `DiceFormula.pool` = the target; total = hits + bonus; may explode). `rollFormula` returns `dropped` (indices of faces not kept or missed), copied to `DiceRecord.dropped` when non-empty; the panel (`.inkwright-die-dropped`), the web card (`.die.dropped`) fade them and the journal strikes them out (`~~2~~`). Table ranges may be open (`6+`, `≤0`/`<=0`: `Range` with ±Infinity; `tableProblems` clamps them to the dice span, the generated lookup treats an open top as the last row). Journal: `src/play/journal.ts` (`renderJournal`, pure) and `writeJournal()` in main.ts (command `write-journal`, `api.journal()`), path from the note's `journal.path`.
- Tabletop slice 2, decks: `decks:` in the config (`DeckDef`: id, name, `cards: CardDef[]`; deck and card ids share the id namespace, each deck also owns `<id>_pile`). The generated ink declares `LIST <deck>` with the cards and `VAR <deck>_pile` holding what is left; `draw(deck)` asks `roll_dice(LIST_COUNT(pile), "<deck>")` for a position and takes the k-th lowest card out (`nth_card`), `shuffle(deck)` is `LIST_ALL`, `deck_left(deck)` is `LIST_COUNT`. The engine recognises the deck by the label, reads the pile from the state to size the die and name the card (`DiceRecord.deck`), and `hud().decks` lists each pile; the fallback draws the lowest card. A hand is any list the story keeps.
Expand Down
3 changes: 2 additions & 1 deletion docs/rpg-engine-prd.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,7 @@ entities: # 开局就有的(固定的)
- 游戏的 `game.md` 写 `system: ../../系统/地城爬行`。引擎先读系统的配置,再叠上游戏自己的(同 id 的以游戏的为准)。生成的 `_engine.ink` 会 INCLUDE 系统的 `rules.ink`。
- **版本**:`system.md` 带 `version`。游戏可以写上自己要的版本;版本对不上时,面板和 `check-ink` 给出提示。
- **分发**:先是复制文件夹;之后在 ink-games 公开仓库放第一方的包,再做"安装系统包"命令(从网址下载到 vault,下载前要用户确认)。
- **R7 落地的做法(2026-11-11)**:每个包的 `system.md` 用 `files:` 列出自己的文件(模板生成的 `_engine.ink` 不列,装好后「新建游戏」会生成)。ink-games 的 `systems/index.json` 列出所有包(id、版本、名字、简介)。命令「安装规则包」的流程:读列表 → 选一个包 → 确认框(写明来源网址、装到哪个文件夹、会覆盖同名文件)→ 先下 `system.md`,再逐个下它列出的文件,全部成功才写进 `规则包/<id>/`。路径只认包里的相对路径(不能有 `..`、隐藏文件、怪字符),所以一个包写不到 vault 的别处。「新建游戏」除了插件自带的包,也列出 vault 里装好的、带模板的包;同 id 时用 vault 里那份,因为游戏实际用的就是它。ink-games 的构建会检查 `systems/` 和 inkwright 的 `packs/` 逐字相同,`files:` 列得对不对。
- **R3 落地的做法(2026-11-10)**:第一方的包放在 inkwright 仓库的 `packs/<id>/`,随插件打包(`virtual:packs`)。"新建游戏"把包装进 vault 的 `规则包/<id>/`(已有的不覆盖,作者可能改过),把包的 `template/` 复制到新文件夹,并把 `system:` 改成从游戏到包的相对路径。`system:` 写成 `路径` 或 `{ path, version }`;版本只比主版本号,所以 `system.md` 的 `version` 要加引号(`"1.0"`,否则 YAML 读成数字 1)。`system.md` 的 `pack: { name, description }` 是给选择器看的,和 `version` 一样不进游戏配置。包里的 `表/` 等 `from:` 路径相对于包写,叠加时改成相对于游戏。`check-ink` 跳过含 `system.md` 的文件夹本身的 ink,包的 `template/` 照常检查,仓库里有测试保证模板的引擎是最新的、两种语言都能玩到结局。
- **第一方的包**(原创):
- **叙事检定**:把宿舍游戏的检定、心声、恐惧整理出来;
Expand Down Expand Up @@ -185,7 +186,7 @@ entities: # 开局就有的(固定的)
| R4 | 背包数量、装备栏、状态效果 | 地城包用上:箭会用完、中毒每回合扣血。已做(2026-11-10):地城爬行 1.1,教程 10.4 |
| R5 | 成长和战役:经验、升级、天赋;角色卡笔记、`characters.from`、营地 | 一个英雄连续打两次冒险,升级和装备都带过去。已做(2026-11-10):教程 10.5 |
| R6 | 回合战斗包和示例;叙事检定包(宿舍游戏的规则整理出来) | 一场 3 对 3 的回合战斗;宿舍游戏改用这个包后行为不变。已做(2026-11-10):`packs/turn-battle`、`packs/narrative-check`,教程 10.6 |
| R7 | 公开:教程第十章、ink-games 上的包和示例、"安装系统包" | 一个没写过 Inkwright 的人照着教程做出一个能玩的小游戏(找人试) |
| R7 | 公开:教程第十章、ink-games 上的包和示例、"安装系统包" | 一个没写过 Inkwright 的人照着教程做出一个能玩的小游戏(找人试)。已做(2026-11-11):命令「安装规则包」;ink-games 的 `systems/`、`tutorial/rpg/` 和 10 个网页示例。还差找人试 |

**4AD 不改用实体(2026-11-10 决定)。** 读了 4AD 的代码以后,原定的 R1 验收不成立:4AD 一场遭遇是"一群同样的怪"——一个数量,按"每满几点打死几只"成批地杀——不是一只只有自己生命的个体,拆成实体只会更重、不会更短;那 43 个 `foe_*` 大多是这场遭遇的开关(不死、厌恶某职业、免疫魔法……),战斗里反复读,改成外部函数读取会更慢,正好和 R2 反着来;`foe_hates` 是职业的 LIST 值,实体只存数字;掷骰的先后也会变,没法和旧结果按种子对比。所以 4AD 保持扁平变量,改作 R2 性能的基准;动态实体的真实验收挪到 R6 的 3 对 3 回合战斗(那里每个敌人确实各有各的生命和行动)。

Expand Down
2 changes: 2 additions & 0 deletions packs/dungeon-crawl/system.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
version: "1.1"
# The pack's files besides this note, for "Install rule pack".
files: [rules.ink, template/game.md, template/main.ink, 说明.md]
pack:
name: { zh: 地城爬行, en: Dungeon crawl }
description: { zh: "四人小队一间一间往下走,最深处是深渊督军(2d6 战斗、火把、药水)", en: "A crew of four goes down room by room to the pit warlord (2d6 fights, torches, potions)" }
Expand Down
2 changes: 2 additions & 0 deletions packs/narrative-check/system.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
version: "1.0"
# The pack's files besides this note, for "Install rule pack".
files: [rules.ink, template/game.md, template/main.ink, 说明.md]
pack:
name: { zh: 叙事检定, en: Narrative checks }
description: { zh: "2d6 + 技能对难度的检定,五种技能各是一个内心的声音,恐惧和体力两条血条,同伴的恐惧和信任", en: "2d6 + skill against a difficulty, five skills that are inner voices, fear and stamina, companions' fear and trust" }
Expand Down
3 changes: 2 additions & 1 deletion packs/turn-battle/rules.ink
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
// random hero; a foe with venom 1 poisons a hero not yet poisoned instead. Damage = attack + 2d6 - 4 - defence, at
// least 1; 11 or 12 on the dice is a critical (+2). At the end of a round poison bites (-2) and statuses count down.
// Everything here works on the game's party (stats hp, mp, atk, def, spd, art, acted) and the "foe" kind (hp, atk,
// def, spd, venom, acted), so a game may change both in its own game.md.
// def, spd, venom, acted), so a game may change both in its own game.md. Who is a hero is told by art: every party
// member needs art 1, 2 or 3; one with art 0 (or none) would act and fall like a foe.

VAR battle_result = ""
VAR battle_round = 0
Expand Down
2 changes: 2 additions & 0 deletions packs/turn-battle/system.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
version: "1.0"
# The pack's files besides this note, for "Install rule pack".
files: [rules.ink, template/game.md, template/main.ink, 说明.md]
pack:
name: { zh: 回合战斗, en: Turn battle }
description: { zh: "三人小队对一群敌人,按速度轮流出手(攻击、技能、防御、药水,中毒和眩晕)", en: "A party of three against a band of foes, taking turns by speed (attacks, arts, guarding, potions, poison and stun)" }
Expand Down
2 changes: 1 addition & 1 deletion packs/turn-battle/说明.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ INCLUDE _engine.ink

## 改它

游戏笔记里写同 id 的条目就会替换包里的:换一支小队写 `party:`(每名队员要有 `hp`、`hp_max`、`mp`、`mp_max`、`atk`、`def`、`spd`、`art`、`acted`;`art` 1/2/3 决定技能),改敌人写同 id 的 `foe` 种类(整个种类替换)。包的 `system.md` 不用动。要改流程,把 `rules.ink` 里的段落复制到自己的故事里改名再用。
游戏笔记里写同 id 的条目就会替换包里的:换一支小队写 `party:`(每名队员要有 `hp`、`hp_max`、`mp`、`mp_max`、`atk`、`def`、`spd`、`art`、`acted`;`art` 1/2/3 决定技能。**`art` 必须是 1、2 或 3**:规则靠它分辨谁是队员,写成 0 或不写的队员会像敌人一样自动行动、倒下时直接消失),改敌人写同 id 的 `foe` 种类(整个种类替换)。包的 `system.md` 不用动。要改流程,把 `rules.ink` 里的段落复制到自己的故事里改名再用。

## 平衡(2026-11-10)

Expand Down
17 changes: 8 additions & 9 deletions scripts/export-web.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,10 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
import { basename, dirname, join } from "node:path";
import { compileStory } from "../src/compile/compile";
import { buildWebPage, storyTitle } from "../src/export/web";
import { readConfig } from "../src/game/config";
import { setLanguage, T } from "../src/i18n";
import { findLanguageVar } from "../src/play/session";
import { engineBundle } from "./engine-bundle.mjs";
import { gameNote } from "./game-note";
import { loadGameConfig } from "./game-note";

const [file, out] = process.argv.slice(2).filter((a, i, all) => !a.startsWith("--") && !all[i - 1]?.startsWith("--"));
const option = (name: string) => {
Expand All @@ -28,14 +27,14 @@ const r = await compileStory(basename(file), (p) => readFile(join(dir, p), "utf8
for (const d of r.diagnostics) console.error(`[${d.severity}] ${d.file}:${d.line ?? "?"} ${d.message}`);
if (!r.story) process.exit(1);

// Game mode when a usable game note sits next to the story.
const note = await gameNote(file);
// Game mode when a usable game note sits next to the story: its pack layered under it and its from: notes read, as
// check-ink and the plugin do.
const loaded = await loadGameConfig(file);
let game = undefined;
if (note?.error) console.error(`[warning] ${note.name}: ${note.error}`);
else if (note) {
const read = readConfig(note.frontmatter);
for (const p of read.problems) console.error(`[warning] ${note.name}: ${T().configProblem(p)}`);
game = read.config ?? undefined;
if (loaded?.note.error) console.error(`[warning] ${loaded.note.name}: ${loaded.note.error}`);
else if (loaded) {
for (const p of loaded.problems) console.error(`[warning] ${loaded.note.name}: ${T().configProblem(p)}`);
game = loaded.config ?? undefined;
}

// Same fallback as the plugin: main.ink is named after its folder.
Expand Down
Loading
Loading