addventure

Addventure

Write interactive fiction played with pencil, paper, and addition.

Players solve games by looking up a Verb ID and an Object ID, adding them together, finding the sum in a potentials list, and reading the corresponding ledger entry. No electronics needed at the table.

How It Works

A game compiles down to a printable PDF with these pages:

• Title Page — intro text, cue checks, and the master potentials list (maps every valid sum to a ledger entry)
• Actions & Inventory — verb IDs, inventory tracking slots, and signal codes
• Room Sheets — one per location, listing objects and their IDs
• Story Ledger — numbered narrative entries with instructions ("cross out X, write Y")
• Fragments — sealed text passages, revealed during play (if the game uses them)

The player's loop: pick a verb, pick a target, add the IDs, look up the sum in the potentials list. If it's there, read the ledger entry and follow the instructions (state changes, item transfers, room transitions).

Quick Start

Python 3.10+. Uses uv as the runner. PDF output requires Typst installed on your system.

uv run addventure build                     # compile example game to PDF (example.pdf)
uv run addventure build games/example       # same thing, explicit path
uv run addventure build path/to/game        # your own game
uv run addventure build --md                # markdown output instead of PDF
uv run addventure build -o output.pdf       # custom output path
uv run addventure new my-game               # scaffold a new game directory

Writing Games

A game is a directory of .md files. You need one index.md for metadata, verbs, and items; all other .md files define rooms and are loaded alphabetically.

index.md

---
title: The Facility
author: Example
---

# Verbs
USE
TAKE
LOOK

# Inventory
CROWBAR
KEYCARD
KNIFE

The frontmatter metadata (title, author) is used in PDF sheet titles and page footers.

Room files

# Control Room
LOOK: Fluorescent lights buzz. Banks of dead equipment line the walls.

TERMINAL
+ LOOK: A dusty CRT. A keycard slot sits beside it.
+ USE + KEYCARD:
  You slide the keycard. The screen floods with data.
  - TERMINAL -> TERMINAL__UNLOCKED
    + LOOK: Scrolling text. A map shows the facility layout.
  - KEYCARD -> trash
  - room -> room__POWERED
    + LOOK: The room hums with energy. A hatch has opened in the floor.
    + HATCH -> room
      + LOOK: A dark opening, just wide enough to squeeze through.
      + USE:
        You lower yourself into the darkness.
        - player -> "Basement"

CRATE
+ LOOK: A heavy wooden crate, nailed shut.
+ USE + CROWBAR:
  You pry it open. A keycard glints inside.
  - CRATE -> CRATE__OPEN
    + LOOK: A splintered crate, lid hanging off.
  - KEYCARD -> room
    + LOOK: A small keycard among the splinters.
    + TAKE:
      You pocket the keycard.
      - KEYCARD -> player
  - CROWBAR -> trash

Example Output

Running uv run addventure build generates a PDF with sheets like:

THE FACILITY — ACTIONS & INVENTORY
========================================

  USE                  [ 32 ]
  TAKE                 [ 21 ]
  LOOK                 [ 51 ]

ROOM: CONTROL ROOM
Room ID: 144

Objects in this room:
  TERMINAL                 951
  CRATE                    963
  WALL_PANEL               662
  BINDINGS                 949

The potentials list maps sums to ledger entries (e.g., LOOK + TERMINAL = 51 + 951 = 1002 → Entry #5), and the story ledger contains the narrative with physical instructions for updating your sheets.