Skip to main content

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)

Source distribution for addventure 2.1.1
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)

Table of built distributions (wheels) for addventure 2.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page