Metadata-Version: 2.4
Name: anyzork
Version: 0.2.2
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

<div align="center">
      <img src="https://anyzork.com/static/anyzork-header.png" alt="AnyZork" width="520">
  <p><strong>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.</strong></p>
  <p>
    <a href="https://pypi.org/project/anyzork/"><img src="https://img.shields.io/pypi/v/anyzork?label=pypi" alt="PyPI" /></a>
    <a href="https://github.com/oobagi/anyzork/blob/main/LICENSE"><img src="https://img.shields.io/github/license/oobagi/anyzork" alt="License" /></a>
    <a href="https://github.com/oobagi/anyzork/stargazers"><img src="https://img.shields.io/github/stars/oobagi/anyzork" alt="Stars" /></a>
    <a href="https://github.com/oobagi/anyzork/issues"><img src="https://img.shields.io/github/issues/oobagi/anyzork" alt="Issues" /></a>
  </p>
  <p>
    <a href="#quickstart"><strong>Quickstart</strong></a>
    ·
    <a href="#features"><strong>Features</strong></a>
    ·
    <a href="#how-it-works"><strong>How It Works</strong></a>
    ·
    <a href="#docs"><strong>Docs</strong></a>
    ·
    <a href="#contributing"><strong>Contributing</strong></a>
  </p>
</div>

---

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

<details>
<summary>Alternative: install with pip</summary>

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

```bash
pip install anyzork            # core only
pip install 'anyzork[narrator]'  # with narrator providers
```
</details>

> **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"
# prompt is copied to your clipboard — paste it into any LLM
# paste the LLM's full response back into the terminal
# AnyZork auto-compiles and adds it to your library
anyzork play haunted-lighthouse-on-a-cliff
```

## 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

1. **Generate** — `anyzork generate` builds a structured prompt from your idea and copies it to your clipboard.
2. **Author** — Paste the 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** — Paste the LLM's response back into the terminal. AnyZork compiles ZorkScript into a `.zork` archive automatically. 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
