Metadata-Version: 2.4
Name: escape-the-valley
Version: 1.1.1
Summary: Oregon Trail-style survival game powered by Ollama GM with XRPL ledger-backed inventory
Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: game,ollama,survival,terminal,xrpl
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.70
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: voice
Requires-Dist: voice-soundboard[kokoro]>=2.5; extra == 'voice'
Provides-Extra: xrpl
Requires-Dist: xrpl-py>=3.0; extra == 'xrpl'
Description-Content-Type: text/markdown

<p align="center">
  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/escape-the-valley/readme.png" width="400" alt="Ledger Trail: Escape the Valley">
</p>

<p align="center">
  <a href="https://github.com/mcp-tool-shop-org/escape-the-valley/actions"><img src="https://github.com/mcp-tool-shop-org/escape-the-valley/workflows/CI/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/escape-the-valley/"><img src="https://img.shields.io/pypi/v/escape-the-valley" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License">
  <a href="https://mcp-tool-shop-org.github.io/escape-the-valley/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
</p>

<p align="center">
  <em>A survival game where the trail is the teacher and the ledger keeps you honest.</em>
</p>

---

## What Is This?

Escape the Valley is an Oregon Trail-style survival game that runs in your terminal. Lead a party of settlers through a procedurally generated wilderness. Manage food, water, wagon condition, and morale while navigating events, hazards, and hard choices.

An optional AI Game Master (powered by Ollama) narrates your journey with three distinct storytelling voices. An optional XRPL Testnet ledger backpack tracks your supply changes as on-chain receipts — proof that you survived, or proof that you tried.

## What's New in 1.1.0

- **Streaming narration** — the GM writes token-by-token, composing each beat live instead of dropping a finished block after a pause.
- **Graded endings** — runs end with a graded epilogue (triumphant, weathered, pyrrhic, or lost) read from who survived, how long it took, and what the trail cost you — not a one-line cause of death.
- **Real stakes** — events can now wound or kill the party. A bad choice can cost a life, and the death is attributed to its real cause.
- **On-ledger reconciliation proof** — an audit mode that replays a run's settlement receipts and verifies them against the XRPL Testnet, so the supply history can be independently checked.
- **Run artifacts** — every finished run leaves a keepsake: an XRPL postcard, your stats, and an export/share path.

## Quick Start

```bash
pip install escape-the-valley

# Or, zero-prerequisite (no Python setup) via the npm launcher — downloads a
# verified binary and runs it:
#   npx @mcptoolshop/escape-the-valley tui --seed 42

# Launch the full-screen TUI (recommended)
trail tui --seed 42

# Resume a saved game
trail tui --continue

# With AI narration (requires Ollama running locally)
trail tui --seed 42 --voice

# Spoken voice narration needs the voice extra:
#   pip install "escape-the-valley[voice]"

# With voice pacing control
trail tui --seed 42 --voice --voice-pace slow

# Without AI narration (deterministic mode)
trail tui --seed 42 --gm-off

# Use a specific Ollama model
trail tui --seed 42 --model mistral
```

## How to Play

Each turn you choose an action from camp:

| Action | What It Does |
|--------|-------------|
| **Travel** | Move toward the valley exit. Costs food and water. Risk of breakdown and events. |
| **Rest** | Heal the party, recover morale. Costs supplies but no progress. |
| **Hunt** | Spend ammo for a chance at food. Better in forests and plains. |
| **Repair** | Spend a spare part to fix the wagon. Critical for survival. |

**Events** interrupt travel with choices (A/B/C). Cautious choices are safer but cost time. Bold choices are faster but risky. There's no always-right answer.

**The wagon is everything.** If it breaks with no parts, the run is over. Keep it above half condition and do maintenance windows (rest then repair) for temporary breakdown resistance.

**Pace** controls speed vs. safety. Steady is the default. Hard pace covers more ground but burns more supplies and breaks wagons faster.

**Escape valves** (hard ration, desperate repair, abandon cargo) exist for emergencies. They have side effects and cooldowns — last resorts, not strategies.

For deeper tips, see the [Survival Guide](https://mcp-tool-shop-org.github.io/escape-the-valley/handbook/survival-guide/).

## GM Profiles

The AI narrator shapes the tone, not the mechanics. All three profiles play the same game.

- **Chronicler** — Grounded, practical, spare. Minimal folklore. Reports what happened.
- **Fireside** — Serious campfire narrator. Subtle uncanny moments. The default.
- **Lantern-Bearer** — Uncanny and liminal, but still grounded in consequences. The weird one.

Set with `--gm-profile`: `trail tui --gm-profile lantern`

## Supplies

The game tracks 12 resource types across two categories:

**Consumables:** food, water, firewood, meds, salt, ammo, lantern oil, cloth

**Gear:** parts, rope, tools, boots

The 5 core supplies (food, water, meds, ammo, parts) are the most critical. Extended supplies like firewood, salt, lantern oil, and cloth add depth: firewood fuels night camps, salt prevents food spoilage, lantern oil enables safer night travel, and cloth patches gear and wagon cover.

## Ledger Backpack (Optional)

The Ledger Backpack tracks your 5 core supplies (food, water, meds, ammo, parts) as tokens on the XRPL Testnet. Every town checkpoint records a settlement receipt on-chain. At the end of your run, your trail ledger includes transaction IDs anyone can verify.

Completely optional. The game plays identically with it off (the default). Enable it from the L menu in the TUI or via CLI:

```bash
trail ledger enable
trail ledger status
trail ledger reconcile  # retry failed settlements
```

Requires `pip install -e ".[xrpl]"` for the `xrpl-py` dependency.

## Commands

| Command | Description |
|---------|-------------|
| `trail tui` | Launch the full-screen Textual UI |
| `trail new` | Start a new run (classic CLI mode) |
| `trail play` | Continue a saved run (classic CLI mode) |
| `trail status` | Show party, wagon, and supplies |
| `trail journal` | Show recent journal entries |
| `trail self-check` | Check game environment health |
| `trail version` | Show version |
| `trail ledger status` | Show backpack status |
| `trail ledger enable` | Enable XRPL backpack |
| `trail ledger disable` | Disable XRPL backpack |
| `trail ledger settle` | Manually settle a checkpoint |
| `trail ledger reconcile` | Retry failed settlements |
| `trail ledger wallet` | Show wallet details |
| `trail stats` | Show run statistics (supports `--json`) |
| `trail parcel send <addr> <supply> <amount>` | Send supplies to another traveler |
| `trail parcel list` | List received parcels |
| `trail parcel accept <id>` | Accept a pending parcel |
| `trail parcel sent` | List parcels you have sent |
| `trail wallet share` | Print your wallet address for trading |

## Warning Callouts

By default, the game shows verbose warnings to help new players spot danger early. Experienced players can switch to minimal mode, which only shows cliff-edge warnings (last-moment, critical threats):

```bash
trail tui --callouts minimal
trail new --callouts minimal
```

## Troubleshooting

**If anything looks wrong, run `trail self-check` first.** It reports whether Ollama is reachable, whether your save loads, and which model is installed. The three things that go wrong:

| Symptom | Cause | Fix |
|---------|-------|-----|
| **Generic / no narration** | Ollama isn't running (the GM is optional and falls back, never bricks) | Start Ollama (`ollama serve`), or play deterministically with `--gm-off`. Run `trail self-check` to confirm. |
| **Ledger pending / settlement failed** | XRPL Testnet is a public test network and is sometimes flaky | `trail ledger reconcile` retries the failed settlements; run it again when the network recovers. Supplies are correct locally either way. |
| **Save won't resume** | `run.json` was truncated or corrupted mid-write | The engine quarantines it as `run.json.corrupt-<timestamp>` before refusing it, so your next save can't clobber the evidence. Recover from that backup, or start a fresh run from a seed. |

The first narrated turn loads the model and can take 10-30s — that's normal, not a hang. Full details: [Troubleshooting handbook](https://mcp-tool-shop-org.github.io/escape-the-valley/handbook/troubleshooting/).

## Requirements

- Python 3.11+
- Ollama (optional, for AI narration)
- xrpl-py (optional, for ledger backpack)

## Security

No telemetry. No accounts. All network features (Ollama, XRPL) are opt-in and disabled by default. XRPL operations use Testnet only. See [SECURITY.md](SECURITY.md) for the full threat model.

## License

MIT

Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
