Skip to content
Merged
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
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

Release notes for each version; the GitHub release carries the same text and the built plugin.

## Unreleased

- 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`.

## 0.6.0 — 2026-11-10

The RPG engine's first pieces: entities (monsters and other things that come and go), faster long games, rule-system packs with a first pack (Dungeon crawl) and a "New game" command, counted items, equipment slots and statuses. Requires Obsidian 1.13.0 or later.
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ PRD: `docs/game-engine-prd.md` — TTRPG-style rules engine on top of Inkwright
- RPG R2 performance (`docs/ink-performance.md`: how to measure, costly ink patterns, numbers): `GameEngine.bindTables` answers `table_text`/`table_id` (declared EXTERNAL; the generated chains are the fallback) through `tables.ts lookupOrder`/`lookupRow`, shared with inkgen's `rowBranches`, and `inkText`/`inkId` (the same escaping); `tests/table-lookup-engine.test.ts` compares both for every total and language. Party: `member_get(who, var)` / `party_count(var, value)` (`InkNames.memberGet/partyCount`, reserved only with a party; `bindParty`; nobody → the zero of the variable's type; ink fallbacks over stats, title and gear). `PlaySession` keeps the story JSON parsed (`parsed`) for new Stories; `src/play/inkjs-speed.ts` replaces StoryState's `inStringEvaluation` getter with an equivalent one (tested step by step against the original). Reusing a Story with `ResetState` for restart was tried and dropped: inkjs keeps `_prevContainers` on the Story, so the next run's visit counts differ.
- RPG R3 rule-system packs: `src/game/system.ts` (`systemRef`, `layerSystem`: lists keyed by id joined, the game's entry wins, other values replaced, the pack's `from`/image paths moved relative to the game, `version` and `pack` dropped; `withSystem` reads `<pack>/system.md`, problems `systemMissing`/`systemVersion` (major version), finds `rules.ink` → `GameConfig.systemRules`, which `generateInk` INCLUDEs as line 2; `joinPath` keeps leading `..`, as does `normalizePath` in compile/paths). Loaded by `scripts/game-note.ts loadGameConfig` and `obsidian.ts loadGameNote` (returns the pack files as dependencies). `check-ink` skips the ink of a folder holding `system.md` (its `template/` is checked). First-party packs live in `packs/<id>/` (`system.md` with a quoted `version` and `pack: { name, description }`, `rules.ink`, `template/` with a committed `_engine.ink`, `说明.md`); `tests/system.test.ts` keeps each template's engine current and plays it. `scripts/packs-bundle.mjs` → `virtual:packs` (template engines left out); `src/templates/packs.ts` (pure: `packList`, `relativePath`, `packGame`); `main.ts createGame` (shared with the journal template) / `newGame(pack, folder?)`, command `new-game` (`NewGameModal` → `FolderModal`), `api.newGame`. The dungeon-crawl pack: `-> crawl ->`, `crawl_result` won/left/fallen, `crawl_rooms`, `depth`; balance measured with a fixed-strategy bot (always strike, potion at life ≤ 2): 68% wins.
- 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`.
- 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
4 changes: 3 additions & 1 deletion docs/rpg-engine-prd.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@ entities: # 开局就有的(固定的)
- 经验是一个资源。`levels:` 写每级的门槛,`level_up_ready(who)` 告诉剧本该升级了。
- 升级给什么由剧本决定:加属性,或者从"天赋"里挑一个。天赋是一种物品(带 `modifiers`,`slot: perk`),所以不用新机制。
- 状态栏在可以升级时给一个提示。
- **R5 落地的做法(2026-11-10)**:`levels: { resource, at }`,`at[0]` 是 1 级;生成 `VAR level`、`next_level_at()`(到顶为 0)、`level_up_ready()`、`level_up()`(返回升没升)。只做主角的等级。天赋是不带 `slot` 的普通物品:装备栏一栏只放一件,天赋要能有好几个,所以不用 `slot: perk`。

### 4.5 引擎侧计算(性能)

Expand All @@ -131,6 +132,7 @@ entities: # 开局就有的(固定的)
- 冒险结束时(剧本调用 `end_adventure()`,或者用一个命令),把主角或队伍写成一篇**角色卡笔记**,放在 `角色/` 文件夹:frontmatter 是属性、物品、经验、状态,正文是这一局的结语和日志链接。
- 下一个冒险的 `game.md` 写 `characters: { from: 角色/ }`,开局时选人就从这个文件夹里挑。读进来的角色卡是这一局 run 的一部分(存进 seeds 旁边),所以重放不会因为角色卡后来又变了而走样。
- 冒险之间的事(养伤、买东西、升级)可以是一个很短的"营地"剧本,也是普通的 ink。
- **R5 落地的做法**:写角色卡的时机是剧本里一行带 `#sheet`(点了选项后第一次出现时写,回退、读档、重放都不写;和 `#fx` 同一个规矩),或命令「保存角色卡」/`api.saveSheet()`;不做 `end_adventure()` 函数:ink 函数会被 lookahead 反复调用,写文件只能放在界面这一侧。文件夹是 `sheets:`(相对于游戏文件夹,默认 `角色`),文件名是角色名;再写一次时 frontmatter 整个换成新的,正文保留,加一段这次的结语(冒险名和时间做标题)。角色卡里多了 `level`、`resources`、`statuses` 三个字段,`characters` 手写时也能用。"读进来的角色卡存进 run"没有另做:角色卡变了要重新生成引擎,而玩到一半的局有 1b 的 build 保留旧版本,效果相同。只写主角,小队的角色卡以后再说。网页导出不写角色卡。

### 4.7 关系和 NPC

Expand Down Expand Up @@ -180,7 +182,7 @@ entities: # 开局就有的(固定的)
| R2 | 引擎侧计算和性能写法文档 | 4AD `--random 300` 的耗时降到现在的一半以下 |
| R3 | 规则系统包的格式、叠加、版本、"新建游戏"按系统选模板;第一个包:地城爬行(原创) | 用这个包从零做一个小地城,不写战斗代码。已做(2026-11-10):`packs/dungeon-crawl`,"新建游戏"命令,教程 10.3 |
| R4 | 背包数量、装备栏、状态效果 | 地城包用上:箭会用完、中毒每回合扣血。已做(2026-11-10):地城爬行 1.1,教程 10.4 |
| R5 | 成长和战役:经验、升级、天赋;角色卡笔记、`characters.from`、营地 | 一个英雄连续打两次冒险,升级和装备都带过去 |
| R5 | 成长和战役:经验、升级、天赋;角色卡笔记、`characters.from`、营地 | 一个英雄连续打两次冒险,升级和装备都带过去。已做(2026-11-10):教程 10.5 |
| R6 | 回合战斗包和示例;叙事检定包(宿舍游戏的规则整理出来) | 一场 3 对 3 的回合战斗;宿舍游戏改用这个包后行为不变 |
| R7 | 公开:教程第十章、ink-games 上的包和示例、"安装系统包" | 一个没写过 Inkwright 的人照着教程做出一个能玩的小游戏(找人试) |

Expand Down
1 change: 1 addition & 0 deletions packs/dungeon-crawl/template/_engine.ink
Original file line number Diff line number Diff line change
Expand Up @@ -278,6 +278,7 @@ EXTERNAL check(skill, difficulty)
~ wits = 0
~ inv = (arrow)
~ arrow_n = 12
~ statuses = ""
}

// A skill's current level, by name.
Expand Down
7 changes: 7 additions & 0 deletions src/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ export interface ApiHost {
importRun(path: string): Promise<{ id: string; name: string } | null>;
newJournalGame(folder?: string): Promise<{ path: string | null }>;
newGame(pack: string | null, folder?: string): Promise<{ path: string | null }>;
saveSheet(epilogue?: string): Promise<{ path: string | null }>;
}

export interface ApiDiagnostic {
Expand Down Expand Up @@ -170,6 +171,8 @@ Visible play panel (the user sees what you do):
newGame(pack, folder?) a game on a bundled rule-system pack ("dungeon-crawl"; null = the journal template): the pack
goes to 规则包/<id> / Rule packs/<id> unless already there, its template to the new folder (default:
the pack's name), system: pointing at the pack, engine generated -> { path }
saveSheet(epilogue?) game mode: write the character being played as a sheet note in the game's sheets folder
(default 角色/Characters next to the story); a line tagged #sheet does it after a choice -> { path }

Export:
exportWeb(path?) write the story as one standalone .html next to it (main.ink -> <folder>.html)
Expand Down Expand Up @@ -354,6 +357,10 @@ export class InkwrightApi {
return this.host.newGame(pack, folder);
}

saveSheet(epilogue?: string): Promise<{ path: string | null }> {
return this.host.saveSheet(epilogue);
}

async runs(): Promise<{ id: string; name: string; draft: boolean; updatedAt: string; actions: number; conflictOf?: string }[]> {
return (await this.host.runsForRoot()).map((r) => ({ id: r.id, name: r.name, draft: r.draft, updatedAt: r.updatedAt, actions: r.actions.length, ...(r.conflictOf ? { conflictOf: r.conflictOf } : {}) }));
}
Expand Down
3 changes: 2 additions & 1 deletion src/export/web.ts
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ export function buildWebPage(o: WebPageOptions): string {
return {
restart: t.restart, back: t.back, ended: t.ended, language: t.storyLanguage, loop: t.infiniteLoop(LOOP_SECONDS),
character: t.character, status: t.status, diceLog: t.diceLog, bands: t.bands, redCheck: t.redCheck, unknownSkill: t.unknownSkill,
inventory: t.inventory, nothingCarried: t.nothingCarried, statuses: t.statuses, needs: t.needs, decks: t.decks, pickCard: t.pickCard, autoFail: t.autoFail, autoSuccess: t.autoSuccess, typeHere: t.typeHere, writeHere: t.writeHere, pickItem: t.pickItem, turnRound: t.turnLine("{r}", "{p}"), pickN: t.pickCardsN, pickRange: t.pickCardsRange, updatedStop: t.webUpdatedStop("{n}"),
inventory: t.inventory, nothingCarried: t.nothingCarried, statuses: t.statuses, levelLine: t.levelLine("{n}"), levelNext: t.levelNext("{n}"), levelReady: t.levelReady, needs: t.needs, decks: t.decks, pickCard: t.pickCard, autoFail: t.autoFail, autoSuccess: t.autoSuccess, typeHere: t.typeHere, writeHere: t.writeHere, pickItem: t.pickItem, turnRound: t.turnLine("{r}", "{p}"), pickN: t.pickCardsN, pickRange: t.pickCardsRange, updatedStop: t.webUpdatedStop("{n}"),
};
};
// "<" only occurs inside JSON strings, where \u003c is equivalent.
Expand Down Expand Up @@ -516,6 +516,7 @@ const PLAYER = `(function () {
function itemText(i) { return (i.equipped ? "◆ " : "") + i.name + (i.count !== undefined ? " ×" + i.count : ""); }
function statusText(list) { return list.map(function (st) { return st.turns > 0 ? st.name + " " + st.turns : st.name; }).join(", "); }
if (h.items && !(h.party && h.items.length === 0)) line(s.inventory, h.items.length ? h.items.map(itemText).join(" · ") : s.nothingCarried);
if (h.level) line(s.levelLine.split("{n}").join(String(h.level.level)), (h.level.next > 0 ? s.levelNext.split("{n}").join(String(h.level.next)) : "") + (h.level.ready ? " · " + s.levelReady : ""));
if (h.statuses && h.statuses.length) line(s.statuses, statusText(h.statuses));
if (h.decks) line(s.decks, h.decks.map(function (d) { return d.name + " " + d.left + "/" + d.total; }).join(" · "));
(h.records || []).forEach(function (r) { line(r.name, r.entries.length ? r.entries.join(language() === "en" ? ", " : "、") : "—"); });
Expand Down
Loading
Loading