Metadata-Version: 2.3
Name: escape-the-valley
Version: 1.3.0
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: MIT
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.md">English</a> | <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

**1.3.0** — Four endings you can actually hit, including weathered. Wagon is a threat, not the whole game. Early Winter slows a tagged year. Desert fords stay off the sand. Hunt names who got hurt. `npx @mcptoolshop/escape-the-valley` launches the v1.3.0 binary (it had been stuck on the dead v1.1.1 GitHub artifact).

**1.2.1** — PyPI wheel actually uploads (Metadata-Version 2.3). Same product as 1.2.0.

**1.2.0** — GitHub Release binaries launch (event library + stylesheet bundled; smoke asserts `--help` and ≥200 events). `trail ledger proof` audits the loaded save. TUI shows seed/doctrine/twists/morale; `c` cycles pace; ledger menu `R` proofs this save. HUD readable at 80×24 and 120×30.

**1.1.1** — `pip install "escape-the-valley[voice]"` actually installs (the extra had pinned an unpublished package). The PyInstaller binary no longer pulls in the voice extra.

**1.1.0** — streaming narration, graded endings, events that can wound, on-ledger reconciliation proof, run artifacts.

Binaries attached to the v1.1.0 and v1.1.1 GitHub Releases do not launch (a relative import in the frozen entrypoint). Use `pip install escape-the-valley` or the v1.2.0+ GitHub binary / `npx` launcher.

## Quick Start

```bash
pip install escape-the-valley

# Zero-prerequisite npm launcher (GitHub v1.3.0 binary; v1.1.0 and v1.1.1
# artifacts do not start):
#   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

# Spoken voice (opt-in; needs pip install "escape-the-valley[voice]").
# AI narration is already on by default when Ollama is running;
# pass --gm-off to disable the GM. --voice does not turn the GM on.
trail tui --seed 42 --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
trail ledger proof      # PASS / FAIL / INCONCLUSIVE on this save
```

In the TUI, **L** opens the ledger menu; with the backpack on, **R** proofs this save (same verdicts). It does not Rest.

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 proof` | Proof the loaded save (PASS/FAIL/INCONCLUSIVE) |
| `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. GM narration is on by default (HTTP to local Ollama); pass `--gm-off` to disable. XRPL is off until `trail ledger enable` (Testnet only). Voice is opt-in (`--voice`). 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>
