Skip to content

0.5.0

Choose a tag to compare

@github-actions github-actions released this 10 Nov 00:34
· 37 commits to main since this release
af49a92

Solo play and tabletop games: runs that pick up where you left off, a dice tray and oracle, clocks, records and a live journal; dice formulas, random tables, decks and hands, maps, a chaos bag, a growing dungeon and a party of several characters. Requires Obsidian 1.13.0 or later.

Breaking

  • The generated ink no longer uses temps called c, none and before (a card, item or place with such an id broke the story), and a game with two decks no longer fails to compile (the draw function declared its temp once per deck). Regenerate the engine ink of your games.
  • A game with items now always declares played (for #use): a game that declared its own played VAR (出牌 with ink: zh) must drop it, then regenerate the engine ink.
  • Saves move to a folder in the vault (Inkwright/存档/ or Inkwright/Saves/, set in the settings) on first start; the panel keeps a run and replays it instead of starting over.

Solo play

Runs that carry on, and the tools of a solo game (docs/solo-prd.md).

  • The player picks up where you left off (solo PRD, slice 1a). The panel no longer starts over on every recompile or restart: it keeps the run as the choices made since the start (with their text, language and the run's seeds) and replays them on the current story, so the text, ink's RANDOM and shuffles, the dice and back all come out as they were. Edits after the point you reached go unnoticed; when a choice you took changed or is gone, the panel stops there and says so, keeps the steps it could not take, and saves the whole run as "Progress before the stop" before a new choice there drops them. A start point or character the story no longer has stops it too. Runs are saved in a vault folder (Inkwright/存档/ or Inkwright/Saves/, set in the settings), one file per device so no sync can overwrite another device's progress; a run moved on elsewhere is picked up when its file syncs in; two devices that went different ways at once keep both runs (the other as a conflict copy); the sync mode setting (iCloud by default, Obsidian Sync, git / Syncthing, this device only) decides how conflicts are handled. Saves are runs too: "Save" keeps a snapshot, "Load" plays it on. Old saves move over on first start. Renaming a story takes its runs along. api.run() / api.runs(); panel() reports replay and stopped.
  • Picking a run up after an edit is less strict (solo slice 1b): a choice you took is also found when it moved (its text is unique on the screen), and by a guess when only a number in it changed or it was reworded while the rest of the screen stayed the same; the panel says how many steps were guessed. When a step's outcome changed (its rolls, or the choices that came after it) the panel says from which step, and "Stop at step N" stops the run there. Where a run stops, "Go on by index" takes the remaining steps by their position, and "Back to before the edit" plays the run on the version of the story it was last played on (each version a run was played on is kept in the save folder, the newest three per story), until "Use the new version".
  • Player mode (solo slice 1c): a button on the player's bar (and the command "Toggle player mode") hides the author's controls (lock, start from a knot, variables), folds the story's problems into a badge and locks the main story. Edits to the story no longer interrupt the run: it plays on the version it was on, with "The story was updated · Apply". Restarting (or picking another character) starts a new run and keeps the one so far in the saves list. A run picked up after more than an hour shows a line where you left off. Long runs draw their latest 200 paragraphs, the earlier ones behind a button. Commands "Export this run to a file" and "Import a run from a file" (api.exportRun(), api.importRun(path)) back a run up or move it.
  • The dice tray (solo slice 2): under the choices, ask the oracle a yes/no question at one of five odds (d100 against 90/75/50/25/10; the lowest fifth of the yeses is "yes, and", the top fifth of the nos "no, and"), roll a formula or a common die, or roll a table marked oracle: true in the game note (an inspiration table). Answers and rolls show as cards where they were asked, are part of the run (saved, synced, replayed, written to the journal) and change no story variable; back takes the latest one back, and asking again gets the same answer. oracle: in the game note changes the thresholds and can name a chaos resource that moves them (chaosStep per point from its middle). Works without a game note too (oracle and formulas). Tutorial chapter 9 starts with it.
  • Clocks, tracks and changes by hand (solo slice 3): a resource can be drawn as a clock (display: clock, max−min slices) or a track (display: track, boxes of four ticks; its span must be whole boxes), in the panel and the exported page. A resource marked manual: true gets −/+ buttons on the status bar: the player is the game master. A change is part of the run (kept as how much was added, so a replay on an edited story adds it to the value there; shown in the text and the journal, ticks in a row as one line), within the resource's range, undone by back, and takes effect from the next choice. Tutorial 9.2.
  • Write a paragraph and a live journal (solo slice 4): #write:<var> is #input with several lines (Enter for a new line, Ctrl/Cmd+Enter to go on), in the panel and the exported page; the story prints it as one paragraph with its lines. journal: { live: true } in the game note (or the "Live journal" setting for stories without one) writes the run into a journal note as it is played: the note is made on the first move, then each action is appended (a choice with the text it brought and a paragraph written with it, quoted; rolls; the tray's questions; changes by hand), never rewritten; back appends a line saying so. The run records how far the note was written, so it carries on across days and devices and makes up a write that did not happen. When the note is open in the editor, the text is inserted there. Tutorial 9.3.
  • Records (solo slice 5a): records: in the game note keeps lists of short entries (clues, people, threads). The generated ink gives record_add, record_remove, record_count, record_pick (a random entry, rolled with the run's seed and shown as a card) and record_list; each record is a string VAR (escaped by the engine) and a counter. The status bar lists the entries with a × each and a box to add one: the player keeps them too, as part of the run. Without the engine (Inky) entries can be added and counted. Tutorial 9.4.
  • when: <variable> on a resource or a record shows it on the status bar only while that story variable is true, not 0 or not empty, so one game can have modes (a countdown only in its story mode, a list of people only once there are any to meet).
  • The player writes (#input:<var> on a choice): the panel and the exported page put a text field above that choice's button; the line typed goes into the string VAR just before the choice runs, so a story can ask for a name, an oath or a line of a diary. It works in any story, game or not. Like a card played, the text is part of the choice: back, save, load and the language replay carry it, and the turn line and the journal show it ("Name it · Soot"). check-ink --all and --random type a placeholder ([var]); api.play takes { choice, text } and api.choose(choice, text) types into the panel. Writing to a variable the story does not declare is reported in Chinese too.

Tabletop

Dice, tables, cards, maps and parties for porting and writing solo board games (docs/tabletop-prd.md).

  • Game mode, tabletop slice 1 (docs/tabletop-prd.md): free dice and random tables. {roll("2d6+3")} (also d20, d%, d66) rolls outside a check. tables: in the game note lists random tables, rows with a dice range and bilingual text, written inline or read from: the first markdown table of another note (a 1d6/d66 column header names the dice; zh/en columns the text; an id column the row ids); {table("encounter")} rolls one and reads the row, table_roll/table_text/table_id serve stories that branch on the result. Every roll shows as a card in the text and in the dice log, in the panel and the exported page, and follows the run's seed, so back, load and language replay roll the same; the generated ink keeps a story playable without the engine (flat dice). The explorer and check-ink roll tables from a fixed seed; the game note's table problems (no rows, bad dice, gaps or overlaps in the ranges, a note without a table) are reported like the other config problems.
  • Exploding dice and open table ranges: roll("d6!") rolls a die again whenever it shows its top face and adds it (the card shows every face; the fallback uses the exploding average). A table row's range can be open, 6+ or ≤0, so a roll with a modifier that goes past the dice still lands on a row; the checks treat the open end as covering the rest of the dice.
  • Keep highest / lowest and dice pools: roll("4d6kh3") adds the three highest of four dice, 2d20kh / 2d20kl is advantage / disadvantage (one die when the number is left out); roll("5d6>=5") counts the dice showing 5 or more (a bonus adds to the count; 5d10!>=8 explodes, and the extra dice count too). The faces that do not count are faded and struck out on the roll card, in the panel and the exported page, and struck out in the journal. Tables can use them as their dice; the fallback without an engine uses the exact average.
  • Decks (tabletop slice 2): decks: in the game note (id, name, cards with id, name, desc). The generated ink declares LIST <deck> and VAR <deck>_pile; draw("clues") takes a random card out of the pile without replacement (an empty list once it is empty), shuffle("clues") puts every card back, deck_left("clues") counts the pile, and a hand is any list the story keeps (~ hand += draw("clues")). The draw rolls through the engine's seeded dice, so back, load and replay draw the same; it shows as a card in the text (deck and card, description on hover) and in the dice log, and the HUD lists each pile (hud().decks).
  • Hands and card play (tabletop slice 3): hands: in the game note names the list variables that hold cards ({ id: hand, name }; the generated ink declares VAR hand = () and VAR played = (), the story still adds and removes). The panel and the exported page draw each hand as a row of cards between the text and the choices: tap a card to pick it (its description shows under the row), tap again to put it back; the row scrolls sideways on a phone. A choice tagged #play:hand waits for a card from that hand, reads "Play a card · Torch" once one is picked, and is taken with it: the engine writes the card into played just before the choice runs (~ hand -= played, { played == torch: … }); with no card to play the choice is locked like a missing item. The card is part of the choice, so back, save, load and the language replay play it again; the journal and the turn line name it. The explorer plays a #play choice once per card in the hand (出一张 ▸ 手电 in the paths), the random player picks one at random, and a #play naming a hand the note does not have is a warning. api.choose(choice, cardId) plays a card; panel().game.plays and hud().hands list them.
  • Several cards at once: #play:hand:2 takes exactly two cards, #play:hand:1-3 one to three; they go into played together (one list). The panel and the exported page let as many be picked (the oldest gives way when full) and say how many; a hand short of the minimum locks the choice; the explorer plays each card alone (when one may go) and the most that may go at once, as a sample; the random player picks a random set. api.choose(choice, [ids]). Tutorial 9.5.
  • Board-game bits (solo slice 5b): #use on a choice lets the player pick something carried (shown as a row of cards while such a choice is on screen); it goes into played like a card, which a game with items now always declares (a game that declared its own played VAR — 出牌 with ink: zh — must drop it and regenerate the engine ink); locked when nothing is carried, and the explorer tries each thing. turn: { round, phase, phases } in the game note declares a round counter and a phase variable and shows "Round 3 · Enemy phase" on the HUD (panel and exported page).
  • Map (tabletop slice 4): map: in the game note gives an image (optional; width/height are its pixel size, percentages when left out) and named places (x/y, links drawn as lines, hidden until revealed, counter showing a story variable's number) plus tokens with a colour and a starting place. The generated ink declares LIST places, VAR here, VAR revealed and VAR <token>_at; the story moves things by assigning them. The panel and the exported page draw the map under the HUD (the image, the lines, each place as a question mark until revealed, a ring where the player stands, counters, tokens side by side), and a choice tagged #go:<place> makes that place a pulsing button that takes the choice. The export carries the image along as a data URI. panel().game.map.
  • Cards with numbers and art, decks from notes, maps from a canvas (tabletop slice 5). A card can carry numbers (cost: 2, nested ones flattened to icons_combat) and an image; the generated ink reads them with card_<key>(card) (0 when a card has none), attributes: names them for the player, and card faces show the art and the numbers as badges, in the panel and the exported page (which carries the art as data URIs). A deck can come from: a folder: one note per card, the file name its id, the frontmatter its name, desc, image and numbers, the body its description; the notes are compile dependencies. A map can come from: a canvas: the image node is the background, each text node a place (first line the id, ? first marks it hidden), each edge a link; the note's places add names and counters. Problems: deckFolder, cardAttr, mapFile, mapCanvasPlace. check-ink reads folders and canvases from disk.
  • Chaos bag (tabletop slice 5½): a third check rule, rules: { kind: bag, tokens: [...] }. A check draws one token and puts it back; skill plus modifiers plus the token's value against the difficulty, auto: fail tokens are a critical failure whatever the numbers, auto: success tokens a critical success, partialBelow gives the partial band; count repeats a token, name names it for the player. The roll card and the dice log show the token as a chip (the panel, the exported page and the journal), the odds on a choice enumerate the bag, and the generated fallback judges by the bag's average token. The draw follows the run's seed like dice. Problems: tokens (an empty bag).
  • Growing dungeon (tabletop slice 6a): dungeon: { width, height, from, shapes } in the game note gives a sheet of squares and a set of room shapes (rows of #/. with doors: top:1 right:2, entry: and kind:; kept in a note, one ### section per shape, or written inline). The generated ink declares VAR dungeon (the layout as text), VAR room and begin_dungeon(shape), add_room(shape, from, door) (returns the new room's number, or 0 when the door led into a wall), mark_room(room, text), dungeon_doors(dungeon, room), dungeon_rooms, dungeon_shape, dungeon_corridor. A new room is hung on a free door, turned until it fits, and cut off when nothing fits whole. The layout is story state, so back, save, load and the language replay keep the map. The panel and the exported page draw it (floor squares, walls, doors with the free ones lit, the party's room highlighted, a room's note). Problems: dungeonSize, dungeonShape, dungeonFile; panel().game.dungeon.
  • Growing dungeon: secret doors and the way back. secret_room(shape, room) puts a new door in a wall of a room (where empty sheet is behind it) and hangs a room on it; dungeon_steps(dungeon, from, to) counts the rooms walked into on the shortest way through used doors; dungeon_nearest(dungeon, from) is the nearest room with a free door; dungeon_via(dungeon, from, to, k) the k-th room walked into on that way. Room notes keep what the map does not (who lives in a room, what was left there): set_room_note(room, "field", value) and room_note(room, "field") on VAR room_notes. Secret doors are kept in the layout text (+row.col.side among the used doors), so older layouts read as before. Two optional rules from the same game: stretch: 2 lengthens a corridor by up to two squares when all its other doors face a wall (kept as shape*k), and passages: true makes a room's door that touches an earlier room's wall an open passage into it.
  • Party (tabletop slice 6b): party: { name, stats, members, down } in the game note plays several characters at once. Each member gets VAR <stat>_<member> per stat, VAR title_<member> (a line the story sets, shown under the name) and, when the game has items, VAR gear_<member> (an items list). A stat with max (a number, or another stat such as life_max) is drawn as a bar; hidden: true keeps it out of sight; a member whose down stat is 0 or less is drawn faded. The panel shows a card per member at the top of the status area; the exported page a line each. Problem: partyStat; panel().game.hud.party.
  • Party: present: <stat> leaves a member out of the cards while that stat is 0 or less, so a game can keep empty slots (a solo hero with room for others, a member who has not joined yet) without drawing them.

Play panel

  • The player can open in the main area (command "Open player in the main area (full screen)", or the button on its bar that moves it between the sidebar and the main area); on a phone that is the whole screen. When the panel is wide enough the status (party, resources, map, the growing dungeon, the dice log) gets its own column beside the text and stays in view while the text scrolls; narrow, it sits above the text as before and a button on the bar folds it away.
  • "Write this session to a note" (command inkwright:write-journal, api.journal()): the panel's run so far, text, choices and roll cards, as a markdown note. journal.path in the game note says where ({dir}, {story}, {date}, {time}, {character}; default {dir}日志/{date} {time}.md); an existing note is never overwritten.

Web export

  • Exported pages keep the player's progress when you re-export an updated story (solo slice 1b): instead of starting over, the page replays the player's run on the new version with the run's seeds (ink's RANDOM and shuffles, the game's dice come out the same) and finds each choice the way the panel does; where one is gone it stops and says so. Progress saved by older pages (choices by index) is replayed by index.

Checking stories

  • check-ink --random N (and api.simulate) counts what the dice did, for balancing a game: each resource at the end gets its median, p10 and p90 and how many runs ended on its lowest or highest value; each table how often it was rolled and how often each row came up (a row that never did says never); each deck how often each card was drawn (and which never were); each check (skill and difficulty) how often it was rolled and how often it succeeded.
  • check-ink --novelty 2 (and api.explore(path, { novelty: 2 })): the explorer judges novelty again within each value of a gate (a variable some choice condition reads), so a branch that needs two things to agree (a door opened in one place, hours or a reading kept from another) is reached where the one-at-a-time rule had already seen each piecewise. Slower; --novelty alone is unchanged. api.explore also returns steps, the choices made, and check-ink prints it.
  • npm run gen-engine -- <main.ink> [--check]: the command-line twin of "Generate game engine ink", for game repos that commit _engine.ink and want CI to fail when it is stale.

Tutorial

  • Chapter 8, tabletop games (8.1–8.9: dice and tables, decks, card play, maps, cards from notes and canvases, the chaos bag, the growing dungeon, the party, the player writes), and chapter 9, solo games (9.1–9.5: the dice tray and oracle, clocks and tracks, the live journal, records, board-game bits), each with an example game, in the ink-games vault.
  • Tutorial (ink-games vault): chapter 7, game mode, in five lessons with example games (configuration and engine, checks and voices, resources and companions, items and effects, checking and export); lesson 6.1 notes the tags game mode reads.