reikhelm/deepfall/README.md

# DEEPFALL

> *Reikhelm, the deep hold, is sinking into the Maw. Delve fast, hold ground, and
> know when to die. The deepest grave is the brightest glory.*

A tabletop game design + a **balance-by-bot** simulator, built as a self-contained
experiment in the `reikhelm` repo (sibling to `combat/`). It mashes up nine games
the designer loves and tries to keep their best parts while filing off their worst.

The dungeon you delve is not invented — it is a real **reikhelm** dungeon
(`reikhelm-core`'s room/theme/graph model), so a physical printing could ship
seeded, reproducible boards straight out of the generator.

---

## The one-paragraph pitch

You are rival **delve-companies** racing into a collapsing megadungeon. Each company
is a **Lineage × Calling** smash-up (your race × your class/faction) that defines a
**bag of dice** you build mid-game. You push your luck rolling that bag to descend,
fight, crack vaults, and seize **rooms** — which score for whoever holds them **when
their floor collapses**. The **Maw** devours the dungeon from the bottom up, so the
richest deep rooms die *first* and the clock is brutal. Every party faces one
decision, over and over: **cash out** (send them "to ground" — they keep their
territory as silent dead and you draft a fresh party), **press on** (greedy, keep the
engine, risk the Maw), or **go for a Worthy End** (dive suicidally deep and let the
Maw take you in a blaze for the single biggest payout in the game). Most glory wins.

## The nine games, and what we took / what we fixed

| Game | What we **kept** | What we **filed off** |
|---|---|---|
| **Smash Up** | Two-half faction mashup; control rooms (bases) that score at a breakpoint | The "take-that" hand hate & swing — conflict here is *positional*, never "discard your stuff" |
| **Small World** | Race×Power combo drafting; **the Decline mechanic** (its single best idea) | Crowded-map turn-order tyranny — the Maw, not opponents, is the pressure |
| **Blood Rage** | Card-drafted strategy per age; **escalating doom (Ragnarök)**; **dying is glorious** | Coin-flip combat reveals — outcomes here are dice you *build* and *mitigate* |
| **Quarriors** | **Dice-bag building**; in-game engine growth; push-your-luck | "Dice gods hate me" whiffs — the Decline safety valve + Faith mitigation soften variance |
| **Dragon Rampage** | Push-your-luck **escape** tension; one escalating shared threat | Player elimination — nobody is ever out; a dead party becomes glory |
| **Catan** | Tile **production** when you hold ground; spatial placement | The robber feel-bad & resource starvation — the Maw is the only "robber," and it's fair to all |
| **EverQuest** | Holy-trinity **party comp** (Steel/Cunning/Faith); faction reputation; loot chase | The grind & downtime — turns are fast, simultaneous-ish, no camping |
| **Daggerfall** | **Custom class** via Lineage×Calling with advantages **and** disadvantages; procedural world; faction web | Sprawl & getting lost — bounded floors, a shared revealed board |
| **Eye of the Beholder** | Grid dungeon of room tiles; party of four; **mechanism puzzles** gate the best loot | Mapping tedium — the board is shared and revealed, not memorized |

The **load-bearing fusion**: *Small World's Decline + Blood Rage's glorious death.*
That one combination kills the runaway leader, abolishes player elimination, and
inverts loss-aversion — three of these games' worst problems, solved at once.

## Layout (mirrors `combat/`)

```
deepfall/
  README.md            — this file
  DESIGN.md            — the full rules + the simulation model (the spec the sim implements)
  Cargo.toml           — self-contained workspace (does not touch the root reikhelm graph)
  configs/default.json — the tunable balance table; editing it IS the balance act
  deepfall-core/       — pure, deterministic, headless game engine (ChaCha8, no I/O)
  deepfall-sim/        — batch harness: runs sweeps → CSV/JSON
  analysis/            — Python (pandas/matplotlib) over the exported data
```

## Build & run

```bash
cd deepfall
cargo test                                  # engine determinism + rules tests
cargo run -p deepfall-sim -- --out out      # run the balance sweeps → out/*.csv, out/*.json
python analysis/analyze.py out              # (optional) plots → out/plots/*.png
```

## What the simulator is for

It is not the game — it is a **truth serum** for the design. Bots play the three
exit strategies (Cash-Out, Press-On, Worthy-End) plus an adaptive Balanced bot,
across all 36 Lineage×Calling combos, thousands of seeded games. We read the data to
answer the only questions that matter for a design like this:

1. **Is there a dominant strategy?** (We want a rock-paper-scissors band, not a king.)
2. **Are any Lineage×Calling combos broken?** (Asymmetry should be *fair*, not solved.)
3. **Does the Maw end the game in a satisfying window?** (~8–14 rounds.)
4. **Is it a runaway?** (Margin of victory should be tight.)
5. **How often does a party die for *nothing*?** (The feel-bad rate — keep it low.)
6. **Is the Decline *decision* real?** (Do winners vary their cash-out timing, or is
   there one provably-correct moment?)

See `DESIGN.md` §"Simulation model" for exactly how the sim abstracts the rules, and
the committed sweep notes for what the data actually said.