Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 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), `sheetAfterMove` in the controller's `afterMove` (a `#sheet` line among the text of a new choice; `sheetSeen` per session, so back/replay/load never write), 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