escape-the-valley 1.2.1

English | 日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

A survival game where the trail is the teacher and the ledger keeps you honest.

---

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

pip install escape-the-valley

# Zero-prerequisite npm launcher (v1.2.0+ GitHub binaries; 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.

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:

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):

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.

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 for the full threat model.

License

MIT

Built by MCP Tool Shop