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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Release notes for each version; the GitHub release carries the same text and the

## Unreleased

- Counted items, equipment and statuses (RPG R4). An item marked `stack: true` has a count: `give(arrow, 3)`, `take(arrow, 1)` (gives back how many it took), `inv_count(arrow)`; it is in the inventory while its count is above 0, and a character starts with `counts: { arrow: 12 }`. `slots:` and an item's `slot:` give `equip(sword)` / `unequip(sword)` (one item per slot, `{equipped ? sword}`); an item with a slot adds its modifiers only while equipped (items without a slot work as before). `statuses:` (name, description, skill modifiers, `rest: true`) are put on the character (`"me"`), a party member or an entity: `add_status(who, "poison", 3)`, `has_status`, `status_turns`, `clear_status`, `tick_statuses()`, `rest_statuses()`. The panel shows counts (×12), worn items (◆) and statuses as tags on the cards; the web page lists them; `check-ink --random` reports each stack's count at the end and how often each status was put on. The dungeon-crawl pack is 1.1: arrows run out, cave spiders and ghouls poison.
- Rule-system packs (RPG R3): a game note can name a pack with `system: <folder>` or `system: { path: <folder>, version: 1 }`. The pack's `system.md` frontmatter goes under the game's (lists joined by id, the game's entry wins; anything else the game sets replaces the pack's), its `from:` notes are read relative to the pack, and the generated engine INCLUDEs the pack's `rules.ink`. A pack that is missing, or of another major version than the game asks for, is reported. Markdown tables take `spawn`/`生成` and `count`/`数量` columns. First pack: **Dungeon crawl** (original rules): a crew of four goes down room by room, 2d6 fights, torches, potions, traps, shrines, a warlord in the last room; the story only calls `-> crawl ->` and reads `crawl_result`. New command "New game" (pick a rule pack or the journal template): it installs the pack into `规则包/` / `Rule packs/` unless it is there already, copies its template into a new folder with `system:` pointing at the pack, and generates the engine. `api.newGame(pack, folder?)`.
- Faster long games (RPG R2): the engine looks table rows up itself (`table_text`/`table_id`; the generated ink stays as the fallback and gives the same text), a session parses the story JSON once instead of on every restart, back and load, and one of inkjs's per-step checks is done without a helper call per output item. New engine-side reads for parties: `member_get(who, "var")` (by number or id, any per-member variable; nobody gives the zero of the variable's type) and `party_count("var", value)`. On the 4AD port, with its helpers rewritten on top of these, a random run takes half the ink steps and half the time. Writing advice in `docs/ink-performance.md`. Games with tables or a party need their engine file regenerated.
- Entities (the RPG engine's first piece): `kinds:` in the game note declares kinds of things that come and go during play (monsters, summons), with stats and templates. The story spawns and fights them with `spawn("foe", "goblin")`, `stat(id, "life")`, `set_stat`, `add_stat`, `despawn`, `alive("foe")`, `pick_one("foe", "random" | "lowest:life" | …)`, `nth_one`, `name_of`. A kind's `remove` stat takes an entity out at 0. They are kept in the run like everything else (back, saves, replays). The panel shows them as cards above the choices, one foldable row per kind; the web page lists them in its status lines. A table row can spawn them (`spawn: goblin`, `count: d3`, `stats:`), rolled with `spawn_from("lair")`. With kinds, party members answer the same functions by id, and `alive`/`pick_one`/`nth_one` take `"party"` for the standing members. `check-ink --random` and `api.simulate` count each kind: how many of each template came, how many were taken out and after how many choices, how many were left, the most at once, and stats pushed past their max (a warning).
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ PRD: `docs/game-engine-prd.md` — TTRPG-style rules engine on top of Inkwright
- RPG R1 entities: `kinds:` (`KindDef`: id, name, `stats` like party stats, `templates` with starting stats, `down`, `remove`), validated (`kindStat`, ids and `<kind>_n` in the namespace; the entity InkNames are reserved only with kinds). `src/game/entities.ts` (pure, tested in `tests/entities.test.ts`): a kind's store is `id|template|stat=v,…;…`; `entSpawn/Has/Get/Set/Drop/Count/At/Pick/Label`. `inkgen entityInk`: `VAR <kind> = ""`, `VAR <kind>_n`, pure EXTERNALs (`ent_*`; fallbacks keep stores empty, so no fight happens without the engine), wrappers `spawn(kind, template)` (id = `<template>_<serial>`, so ids never collide; template ids are unique across kinds), `stat`, `set_stat` (passes the kind's `remove`), `add_stat`, `despawn`, `alive`, `pick_one(kind, how)` (random rolls `roll_dice("1d"+n, "pick:<kind>")`, else `ent_pick`: first/last/lowest:<stat>/highest:<stat>), `nth_one`, `name_of`. `GameEngine.bindEntities`, `hud().kinds` (`EntityView`: name numbered among the same template), drawn by `status.ts renderKinds` above the choices (`details.inkwright-kind` per kind, folded ones kept in `PlayView.foldedKinds`) and as lines in the web page's `renderHud`. Table rows that spawn: `TableRow.spawn` (a template; it names its kind, since templates are unique across kinds), `count` (number or formula), `stats` (set after spawning); problem `rowSpawn`; `inkgen spawnRowInk` (plain ink: `spawn_from(table)` → the total, `spawn_row`, `spawn_row_one`, `spawn_times`), the lookup branches shared with the table lookups (`rowBranches`). Party as fixed entities (only with kinds): `partyEntity` adds branches to the wrappers, member ids read/write `<stat>_<id>`, `despawn` zeroes `present`, the kind name `party` (`InkNames.partyKind`, zh `小队`) counts/picks the standing members (present and not down) in order; member ids that read like `<template>_<n>` and a kind named like the party are reported as duplicates. Random runs: `SimulateResult.kinds` (`KindTally` diffs `hud().kinds` after each step; an entity spawned and gone within one step is not seen), printed by check-ink, `overMax` a warning. Tests: `tests/game-entities.test.ts`, the web rats test.
- 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.
- 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 @@ -103,12 +103,14 @@ entities: # 开局就有的(固定的)
- 装备栏:`slots: [weapon, armor, ring]`,物品写 `slot: weapon`。只有装备着的物品,`modifiers` 才生效(现在是"带着就生效",老游戏不受影响)。
- 实体也能带物品和装备(现在小队已经有 gear)。
- 商店不做新原语:价格是物品的属性,买卖是 ink 的选项。教程里给一个写法。
- **R4 落地的做法(2026-11-10)**:`give`/`take`/`equip` 的参数是 LIST 的项(`give(arrow, 3)`),不是字符串,写错名字编译时就报错,和 `inv ? arrow` 一个写法。数量存在 `<物品>_n`,数量大于 0 时物品也在 `inv` 里;`take` 返回实际拿走几个;对不堆叠的物品,`give` 放进背包、`take` 拿走一个、`inv_count` 是 0 或 1。角色的起始数量写 `counts: { arrow: 12 }`。装备栏只做主角的(`VAR equipped`,`equip` 换下同一栏的另一件,开局每栏装上第一件带着的);小队成员的装备栏等有游戏要用再加。

### 4.3 状态效果

- `statuses:` 声明名字、`modifiers`、持续方式(几回合、直到休息、永久)。
- `add_status(who, "poison", 3)`、`has_status(who, "poison")`、`tick_statuses()`(回合结束时扣回合数)。
- 状态挂在实体或主角上,显示成卡片上的小标签。检定加值走现有的 `collectModifiers`。
- **R4 落地的做法**:所有人的状态存在一个字符串变量 `statuses` 里(`谁|状态|回合;…`),引擎绑定纯函数读写(和实体、记录一样);谁 = 实体或队员的 id,主角写 `"me"`(zh 预设 `"我"`)。回合数 ≤ 0 表示一直有效;再加一次取较长的。持续方式只分两种:按回合(`tick_statuses()` 由故事在它认为"过了一回合"时调用)和 `rest: true`(`rest_statuses()` 清掉)。"每回合扣血"这种效果写在规则的 ink 里,不进引擎。没有引擎时状态加不上(保守回退)。`check-ink --random` 统计每种状态上身几次、出现在多少局;可堆叠物品结束时的数量和资源一样给分布。

### 4.4 成长

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