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.
Metadata
Release files for addventure 2.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| addventure-2.1.1.tar.gz | 2.3 MB | With provenance | Details for addventure-2.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| addventure-2.1.1-py3-none-any.whl | Python 3 | none | any | Details for addventure-2.1.1-py3-none-any.whl |
Total release size: 2.9 MB
Release files / addventure-2.1.1.tar.gz
| Download URL | addventure-2.1.1.tar.gz |
|---|---|
| Size | 2.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fe1805feb8306457aa365549cd36a823b7e5ac3704fb3b86eacd66fd1d776a7f
|
|
BLAKE2b-256 checksum How to use checksums |
e96e6abacffef2998ec1b6a7e8cf1074fa870da2f5405510ccc73ed3424a4bf7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 5, 2026.
Transparency logRelease files / addventure-2.1.1-py3-none-any.whl
| Download URL | addventure-2.1.1-py3-none-any.whl |
|---|---|
| Size | 585.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
537c2c4b96cf764a54f6c553b8d7129b2f5b4199aa1d80436aa35063927d1953
|
|
BLAKE2b-256 checksum How to use checksums |
8d51d3402bbd4300b8ba6802ca6cc2479306acc6194d36b67dc253aeba61ca6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 5, 2026.
Transparency logSecurity for addventure 2.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for addventure-2.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.