Metadata-Version: 2.4
Name: anyzork
Version: 0.2.0
Summary: Deterministic Zork-style text adventure authoring and runtime CLI
Project-URL: Homepage, https://github.com/oobagi/anyzork
Project-URL: Repository, https://github.com/oobagi/anyzork
Project-URL: Issues, https://github.com/oobagi/anyzork/issues
Project-URL: Changelog, https://github.com/oobagi/anyzork/releases
Author: AnyZork contributors
License-Expression: MIT
License-File: LICENSE
Keywords: cli,interactive-fiction,llm,sqlite,text-adventure,zork
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: catalog
Requires-Dist: fastapi>=0.115; extra == 'catalog'
Requires-Dist: python-multipart>=0.0.9; extra == 'catalog'
Requires-Dist: uvicorn>=0.30; extra == 'catalog'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: narrator
Requires-Dist: anthropic>=0.39; extra == 'narrator'
Requires-Dist: google-genai>=1.0; extra == 'narrator'
Requires-Dist: openai>=1.0; extra == 'narrator'
Description-Content-Type: text/markdown

      AnyZork
  
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](https://pipx.pypa.io/), which gives you an isolated environment and puts the `anyzork` command on your PATH:

```bash
pipx install anyzork
```

To enable [Narrator Mode](docs/guides/NARRATOR.md) (optional LLM-powered prose), install with the narrator extra:

```bash
pipx install 'anyzork[narrator]'
```

**Upgrade** to the latest release:

```bash
pipx upgrade anyzork
```


Alternative: install with pip

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

```bash
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:

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

Make your own:

```bash
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](docs/guides/CLI.md)** — Generate a prompt, paste it into any LLM to get [ZorkScript](docs/dsl/ZORKSCRIPT.md), then compile and play. A guided wizard or a one-liner gets you started.

**[Playing Games](docs/guides/CLI.md)** — Play local files or library games, manage named save slots, and list your collection.

**[Narrator Mode](docs/guides/NARRATOR.md)** — An optional live-LLM layer that rewrites room descriptions and event text without touching game state. Supports Claude, OpenAI, and Gemini.

**[Sharing Games](docs/server/SHARING.md)** — Publish games to the official catalog, browse community submissions, and install with a single command.

## Docs

| Doc | What it covers |
|---|---|
| [Game Design Document](docs/engine/GDD.md) | Mechanics, design constraints, and motivation |
| [System Architecture](docs/engine/SYSTEM-DESIGN.md) | Components, commands, and runtime model |
| [World Schema](docs/engine/WORLD-SCHEMA.md) | `.zork` database reference |
| [ZorkScript Spec](docs/dsl/ZORKSCRIPT.md) | Authoring language reference |
| [Command DSL Spec](docs/dsl/COMMANDS.md) | Runtime rule vocabulary |
| [Author Tooling](docs/design/AUTHOR-TOOLING.md) | Lint and import diagnostics design |
| [CLI Reference](docs/guides/CLI.md) | All commands, flags, and options |
| [Configuration](docs/guides/CONFIGURATION.md) | Config file, env vars, and provider setup |
| [Narrator Mode](docs/guides/NARRATOR.md) | Optional LLM prose layer |
| [Sharing Games](docs/server/SHARING.md) | Publishing, browsing, and installing |
| [ADR-001: SQLite Storage](docs/adrs/ADR-001-SQLITE-GAME-STORAGE.md) | Original SQLite rationale (superseded — `.zork` files are now zip archives) |
| [Roadmap](ROADMAP.md) | 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](docs/dsl/ZORKSCRIPT.md) — 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](docs/guides/NARRATOR.md) 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:

```bash
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
