anyzork 0.1.0

Deterministic Zork-style text adventure authoring and runtime CLI

AnyZork

A Zork-style text adventure generator. Describe a world to any LLM, get back a complete game, and play it on a fully deterministic engine — no AI needed at runtime.

Quickstart · Docs · Contributing

---

Install

Requires Python 3.11+

The recommended way to install AnyZork is with pipx, which gives you an isolated environment and puts the anyzork command on your PATH:

pipx install anyzork

To enable Narrator Mode (optional LLM-powered prose), install with the narrator extra:

pipx install 'anyzork[narrator]'

Upgrade to the latest release:

pipx upgrade anyzork

Alternative: install with pip

If you prefer a regular pip install into a virtual environment:

pip install anyzork            # core only
pip install 'anyzork[narrator]'  # with narrator providers

Homebrew: A Homebrew formula is not available yet. We want to prove out the Python packaging path first and will revisit Homebrew support once the release cadence is stable.

Quickstart

Browse and play a community game:

anyzork browse                        # see what's available
anyzork install haunted-lighthouse    # add it to your library
anyzork play haunted-lighthouse       # start playing

Make your own:

anyzork generate "haunted lighthouse on a cliff" -o prompt.txt
# paste prompt.txt into any LLM, save the response as lighthouse.zorkscript
anyzork import lighthouse.zorkscript -o lighthouse.zork
anyzork play lighthouse.zork

Features

Make Your Own Game — Generate a prompt, paste it into any LLM to get ZorkScript, then compile and play. A guided wizard or a one-liner gets you started.

Playing Games — Play local files or library games, manage named save slots, and list your collection.

Narrator Mode — An optional live-LLM layer that rewrites room descriptions and event text without touching game state. Supports Claude, OpenAI, and Gemini.

Sharing Games — Publish games to the official catalog, browse community submissions, and install with a single command.

Docs

Doc	What it covers
Game Design Document	Mechanics, design constraints, and motivation
System Architecture	Components, commands, and runtime model
World Schema	.zork database reference
ZorkScript Spec	Authoring language reference
Command DSL Spec	Runtime rule vocabulary
Author Tooling	Lint and import diagnostics design
CLI Reference	All commands, flags, and options
Configuration	Config file, env vars, and provider setup
Narrator Mode	Optional LLM prose layer
Sharing Games	Publishing, browsing, and installing
ADR-001: SQLite Storage	Original SQLite rationale (superseded — .zork files are now zip archives)
Roadmap	Ordered plan and milestone tracking

How It Works

 You describe a world        Any LLM writes           AnyZork compiles it       You play it
 ───────────────────   ──>   ZorkScript code   ──>    into a .zork file    ──>  deterministically
 "haunted lighthouse         (rooms, items,           (zip archive)             No AI at runtime.
  on a cliff"                 NPCs, puzzles)                                    Pure engine.

1. Generate — anyzork generate builds a structured prompt from your idea (freeform or wizard-guided).
2. Author — You paste that prompt into any LLM. It returns ZorkScript — a human-readable DSL for rooms, items, NPCs, puzzles, dialogue trees, and commands.
3. Compile — anyzork import compiles ZorkScript into a .zork file (a game archive). Lint and validation catch errors before you play.
4. Play — The deterministic engine evaluates commands, preconditions, and effects with no LLM involved. Game state is always consistent and reproducible.

The optional Narrator Mode adds an LLM prose layer on top — it rewrites descriptions for atmosphere but never touches game state.

Contributing

MIT-licensed, solo-maintained. Issues and PRs welcome — small focused changes and clear bug reports are easiest to review.

Development

For contributors working on AnyZork itself:

git clone https://github.com/oobagi/anyzork.git
cd anyzork
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,narrator,catalog]"
ruff check .
pytest -q

License

MIT