reikhelm/deepfall/DESIGN.md

# DEEPFALL — Design & Simulation Spec

This is two documents in one:

- **Part A — The Game.** A playable tabletop design (the rulebook in prose).
- **Part B — The Simulation.** The faithful abstraction the Rust engine implements,
  so the balance numbers mean something. Where the sim simplifies the tabletop rules,
  it says so explicitly.

The vocabulary (room **themes**, depth, connectivity, doors) is borrowed straight
from `reikhelm-core` so a printed board is a real generated dungeon.

---

# Part A — The Game

## 1. The fantasy & the arc

Reikhelm is a vertical megadungeon of stacked **Floors**. Floor 1 is the
**Threshold** (the surface mouth, safe, poor). The deeper the floor, the richer and
deadlier it is. Beneath the deepest floor waits **the Maw** — a rising hunger that
devours the hold one floor at a time, **from the bottom up**. The richest plunder is
therefore the most doomed: a deep Vault is worth a fortune and will be eaten *first*.

Rival **delve-companies** (players) descend to plunder before it's all gone. You don't
win by surviving — you win by **Glory**, and the surest way to bank a fortune is to
spend a party deliberately: send them quietly *to ground* with their loot, or hurl
them into a **Worthy End** at the bottom and let the Maw take them gloriously.

The game lasts until the Maw eats Floor 1. Most Glory wins. Nobody is ever eliminated.

## 2. Your delve-company: Lineage × Calling

At the start, and **every time you bring in a fresh party**, you draft two halves that
smash together (Smash Up / Small World / EverQuest / Daggerfall). Each half grants an
**advantage** and a **cost** — there are no free builds (Daggerfall's custom-class
trade-off).

### Lineages (the "race" — sets your starting **dice bag** + a passive)

| Lineage | Advantage | Cost (disadvantage) | Bag leans |
|---|---|---|---|
| **Dvergar** | +1 Steel resolved each turn (sturdy) | −1 Move (slow) | Warrior |
| **Wisp** | +1 die drawn each hand (nimble) | Setbacks hit double (fragile) | Scholar |
| **Revenant** | Ignore the first Dread each roll (fearless dead) | Faith −1 (no living soul) | Balanced, dread-proof |
| **Gnoll** | +Loot from combat rooms (Den/Forge) (scavenger) | Cunning −1 (clumsy at locks) | Warrior/Rogue |
| **Sylphid** | +1 Move (fleet) | Steel −1 (frail) | Scholar/Rogue |
| **Golem-born** | Setback-resistant (rarely loses dice) | Cannot recruit Relic dice (rigid) | Big, balanced, slow to grow |

### Callings (the "class/faction" — special ability + recruit pool + scoring lean)

| Calling | Special | Recruits | Scoring lean |
|---|---|---|---|
| **Reaver** | Pillage: extra loot from every room you claim | Warrior dice (cheap) | Loot |
| **Lorekeeper** | Open Vaults **solo** (no trinity needed); +Cunning at locks | Scholar dice | Deep vaults |
| **Wardancer** | Worthy-End payout **+50%**; cheap Moves | Rogue dice | Glorious death |
| **Hierophant** | Cancel extra Dread; heal Setbacks; cheap denizen rep | Priest dice | Longevity (persist) |
| **Warden** | Your control markers count **double** for majority | Champion dice | Area control |
| **Prospector** | Cheaper recruits, bigger hand, can find **Relic** dice | Relic dice | Engine / snowball |

6 × 6 = **36 companies.** Natural synergies emerge (Dvergar Reaver = smash-and-grab;
Wisp Lorekeeper = vault cracker; Sylphid Wardancer = fast martyr; Golem-born Warden =
the immovable wall) — the simulator's job is to confirm none of them is *solved*.

## 3. The dice bag (Quarriors) & the six faces

Your bag is a pile of six-sided **delve dice**. Each face shows one symbol:

| Symbol | Meaning |
|---|---|
| ⚔ **Steel** | Combat power — clear a room's threat |
| 🜏 **Cunning** | Wits — open mechanisms / locks; buy extra Moves |
| ✚ **Faith** | Spirit — cancel Dread; heal Setbacks; appease denizens |
| 💰 **Greed** | Loot — turns into banked Glory |
| ✦ **Mettle** | Wild currency — recruit new dice; pay for actions |
| ☠ **Dread** | Peril — accumulates; too much triggers a **Setback** |

Different **die kinds** weight these faces differently. Starting bags are mostly
*Recruit* dice (balanced, one of each). You grow your bag in play by **recruiting**
stronger kinds (Warrior/Scholar/Priest/Rogue/Champion/Relic) from the dungeon's offer.

### A turn

1. **Draw** a hand from your bag (default 4 dice; modified by Lineage/Calling).
2. **Roll** them.
3. **Resolve Dread** — cancel Dread with Faith (and Lineage dread-resist). If Dread
   still standing ≥ the **Dread threshold**, suffer a **Setback** (lose a die to your
   bag's wound slot, or lose unbanked loot).
4. **Act** with your symbols — Move between floors, clear & claim a room, take loot,
   recruit a die.
5. **Press On?** (push-your-luck) — you may draw & roll *another* hand for more symbols
   this turn. Every press nudges the Maw and stacks more Dread risk. Stop whenever you
   like; greed is punished by the dice and by the clock.
6. **Exit decision** — see §6.

## 4. The dungeon: rooms, themes, mechanisms (EotB / Catan / reikhelm)

Each Floor holds several **rooms**, each with a **theme** from reikhelm's palette. A
room's base Glory and its threat/lock scale with its theme and its **depth**:

| Theme | Base value | Threat (Steel) | Lock (Cunning) | Note |
|---|---|---|---|---|
| Threshold | 1 | 0 | 0 | safe mouth |
| Stone | 2 | 1 | 0 | plain |
| Cistern | 3 | 1 | 1 | flooded |
| Den | 3 | 3 | 0 | monster lair (Gnoll loot bonus) |
| Crypt | 3 | 2 | 1 | undead |
| Hall | 4 | 1 | 1 | pillared |
| Library | 4 | 1 | 2 | Cunning-gated, loot-rich |
| Forge | 5 | 4 | 1 | lava, produces Steel |
| Vault | 6 | 2 | 3 | **needs the trinity** (Steel+Cunning+Faith present) unless Lorekeeper |
| Throne | 7 | 5 | 2 | boss; deepest |

A room's collapse Glory = `base_value × depth`. A Vault on Floor 6 is worth `6 × 6 =
36` to whoever holds the majority when Floor 6 falls. **Holding** a room also makes it
**produce** each turn you roll its matching symbol (Catan): a held Forge throws extra
Steel, a Library extra Cunning, a Vault extra Greed — your engine grows on the ground
you keep, right up until the Maw takes it.

**Claiming** a room: spend Steel ≥ threat (fight through) and Cunning ≥ lock (crack the
mechanism). Vaults additionally require **trinity presence** (you produced at least one
Steel *and* one Cunning *and* one Faith this turn) — the EverQuest holy-trinity made
literal — unless your Calling is **Lorekeeper**. Claiming drops a **control marker**.

## 5. The Maw: the doom clock (Blood Rage / Dragon Rampage)

The Maw begins below the deepest floor and **rises**. Each round it advances; its speed
**ramps up** over the game and is **pushed faster by the total Dread** everyone rolled
that round (your collective greed feeds it). When the Maw reaches a floor:

1. **The floor collapses and scores.** For each room, the **majority** marker-holder
   takes its Glory (`base × depth`). Ties split, rounding down. A **Warden's** markers
   count double here; a party that went **to ground** leaves silent **Fallen** markers
   that still count.
2. **Anything still on that floor is Taken by the Maw** (see §6).

Because collapse runs **bottom-up**, the deep treasure has the *shortest* window. The
game ends when Floor 1 collapses.

## 6. The three exits (the heart of the game)

Every party, every turn, faces the same triangle. This is the design's core, fusing
Small World's Decline with Blood Rage's glorious death:

- **Cash Out / "Go to Ground"** *(Small World Decline).* End this party's adventuring.
  **Bank** their unbanked loot + a **depth dividend** (deepest floor reached × factor).
  Their control markers become permanent **Fallen** markers — still counted at every
  future collapse, but they can't move or act. Then draft a **fresh** Lineage×Calling
  and re-enter at the Threshold. Safe, repeatable, keeps your territory working for you
  from beyond the grave.

- **Press On / Persist** *(Catan/Quarriors engine).* Keep the party active: keep
  recruiting, keep holding rooms, keep producing. More upside, but the Maw is climbing
  and a party caught flat-footed loses *everything* unbanked **and** its territory.

- **Worthy End** *(Blood Rage Valhalla).* Declare a **Last Stand** (free if you hold a
  Throne or Vault, or via Wardancer). Now, when the Maw **Takes** your active party, you
  score a huge **Worthy End** bonus = `deepest_floor × worthy_factor` + held room
  values (×1.5 for Wardancer). This is the single biggest payout available — and it's
  all-or-nothing: you lose the party and its unbanked loot. Sometimes you *want* the
  Maw to eat you, as deep as possible, in a blaze.

Getting Taken **without** a Last Stand is the one true feel-bad in the game (lose loot
+ territory for nothing). The simulator measures how often bots fall into it — a
healthy design keeps that rare, because the exits above are always offered.

## 7. Denizen reputation (Daggerfall / EverQuest — light)

A few **denizen** factions live in the deep (the Deep Cult, the Gnoll Warrens, the
Revenant Court). Clearing their themed rooms angers them (reputation down → they raise
the threat of their rooms against you); making **offerings** (spend Greed/Faith) raises
reputation → unlocks premium recruit dice and safer passage. One short track per
denizen, two or three thresholds. *(Kept deliberately light; the sim models it as a
small threat modifier so it doesn't dominate the balance picture.)*

## 8. Why this fixes the originals' worst parts

- **No runaway leader.** A trailing player dives recklessly, takes a Worthy End or a
  deep Cash-Out for a glory spike, and resets — catch-up is *built into* the core loop,
  not bolted on. Leaders who over-persist feed the Maw and lose territory.
- **No elimination, no downtime.** A dead party is glory and silent territory, not a
  removed player. Turns are short; you're always choosing.
- **Variance with a floor.** The dice can betray you, but Faith mitigates Dread and
  Cash-Out lets you lock in value before luck turns — Quarriors' whiff is defanged.
- **Conflict without spite.** You fight for *majorities at collapse*, never to destroy
  an opponent's hand. The shared "robber" is the Maw, and it is perfectly fair.

---

# Part B — Simulation model

The engine in `deepfall-core` is a **faithful abstraction** of Part A, not a literal
table simulator. It keeps everything that drives the six balance questions (the dice
faces, the bag-building, the three exits, the bottom-up Maw, the area-control scoring,
the Lineage×Calling asymmetry) and abstracts the fiddly bits (exact board geometry,
turn-by-turn movement pathing, denizen micro-management) into clean numeric rules. Each
abstraction is called out below.

## B1. State

- **Dungeon**: `floors[1..=D]`, default `D = 6`. Floor `f` has `R` rooms (default 4),
  drawn from the theme table weighted toward richer themes at greater depth. Each
  `Room` has `theme, base_value, threat, lock, produces(symbol), markers: Vec<Marker>`.
  *(Abstraction: rooms are an unordered set per floor; we don't model intra-floor
  pathing or the corridor graph — only "which floor are you on" matters for the Maw.)*
- **Maw**: `accum: f64`, `frontier: u32` = deepest uncollapsed floor (starts at `D`).
- **Players**: `glory`, and an optional active `Party`.
- **Party**: `lineage, calling, bag: Vec<DieKind>, floor (starts at 1), unbanked_loot,
  deepest_reached, last_stand: bool, held: Vec<RoomRef>`.
- **Marker**: `{ owner, strength, fallen }`. Active strength = 1 (×2 for Warden);
  Fallen strength = 1.

## B2. Round structure

Each round, in player id order, every player takes a **turn** (B3). After all turns,
the **Maw advances** (B4) and any collapses resolve (scoring + Takes). Repeat until the
frontier passes Floor 1. Then **final scoring** (B5).

## B3. A turn (the engine's core resolution)

1. **Decide intent** from the controller (B6): a *target floor* and a *risk appetite*.
2. **Move**: `moves = 1 + lineage_move + calling_move`; optionally spend Cunning/Mettle
   for extra moves if the bot wants to dive. Step `floor` toward the target (clamped to
   `[1, frontier]` — you cannot stand on an already-eaten floor). Update
   `deepest_reached`.
3. **Roll** the hand: draw `hand_size` dice (`+lineage/calling`), roll each to a face,
   summing the six symbol totals. The controller may **Press On** (B6) to draw & roll
   additional hands, each appending to the totals and adding `press_dread_push` to the
   round's Maw pressure.
4. **Dread**: `dread -= faith_cancel` (Faith spent to cancel, plus Hierophant bonus
   and Revenant's "ignore first"). If remaining `dread ≥ dread_threshold`, a **Setback**:
   lose one die from the bag (Golem-born resists; Wisp loses two) **or**, if the bag is
   minimal, lose `setback_loot` unbanked loot. Count it.
5. **Claim**: among rooms on the current floor not already held by this party, pick the
   highest-value one the party can afford this turn (Steel ≥ threat, Cunning ≥ lock,
   trinity-or-Lorekeeper for Vault). Place/strengthen a marker; add to `held`.
   *(Abstraction: one claim attempt per turn; "contest" = simply adding your own marker,
   majority resolved at collapse.)*
6. **Loot**: `unbanked_loot += greed × loot_per_greed × depth_factor(floor)
   + production(held) + reaver/gnoll bonuses`.
7. **Recruit**: if `mettle ≥ recruit_cost` and the controller wants to grow, add a die
   of the Calling's recruit kind to the bag (Prospector discount; Golem-born can't take
   Relics).
8. **Exit decision** (B6): Cash Out, set Last Stand, or persist.

## B4. The Maw

After all turns in a round `r`:
```
speed   = base_rate + accel * r + dread_push * total_dread_this_round
accum  += speed
while accum >= 1.0 and frontier >= 1:
    accum -= 1.0
    collapse(frontier)          // score rooms (B5) + Take parties on this floor
    frontier -= 1
```
`collapse(f)`: for each room on `f`, the owner with the greatest summed marker strength
takes `base_value × f` Glory (ties split, floor-divided). Then every **active** party
whose `floor == f` is **Taken**: if `last_stand`, score the **Worthy End** bonus
(`f × worthy_factor + held_value`, ×1.5 Wardancer); else lose unbanked loot + all its
active markers (a **feel-bad** event, counted). The party is removed; the player may
draft a new one next round at the Threshold.

## B5. Scoring

Glory accrues from: room majorities at collapse, Cash-Out banks (loot + depth
dividend), and Worthy-End bonuses. At game end (frontier < 1), any still-active party is
force-Taken under the same B4 rule (Last Stand pays; otherwise unbanked loot is lost).
Highest total Glory wins; we also record the **margin** (winner − runner-up).

## B6. Controllers (the bots under test)

Each is a pure function of the public game view. Risk appetite and exit timing are the
levers that distinguish them.

- **CashOut (Cautious).** Targets a moderate depth; presses on rarely; **Cash-Out** as
  soon as banked-worthy loot clears a small bar *or* the Maw is within `safe_margin`
  floors. Rarely sets Last Stand. Models the safe Decline player.
- **PressOn (Greedy/Engine).** Recruits hard early; targets rooms to hold; presses
  aggressively; **persists**, fleeing upward only when the Maw is one floor away; Cashes
  Out only when forced. Models the engine-builder who risks the clock.
- **WorthyEnd (Martyr/Diver).** Rushes to the deepest reachable floor; sets Last Stand
  as soon as it holds a Vault/Throne (or is Wardancer); presses hard; rides the floor
  into a **Worthy End**. High variance, high ceiling.
- **Balanced (Adaptive).** Reads `collapses_until_my_floor` vs. banked value: Cash-Out
  when the Maw is close *and* it has a worthwhile bank; opportunistically converts to a
  Worthy End when deep and doomed; otherwise presses moderately and grows. The
  "good human" baseline.

## B7. What we measure (written to CSV/JSON; see `analysis/`)

- **Win rate by strategy** (mixed tables) → dominance check (target: no strategy >
  ~40% in 4-player, none < ~12%).
- **Win rate by Lineage and by Calling** → asymmetry fairness (flag any > ~1.6× the
  mean).
- **Game length** (rounds) → pacing (target band ~8–14).
- **Victory margin** as a fraction of the winner's score → runaway check (lower = tighter).
- **Feel-bad rate**: Takes-without-Last-Stand per game → keep low.
- **Cash-Out timing spread**: distribution of the depth/round at which winners cashed
  out → is the Decline decision genuinely live, or is there one correct moment?

---

# Part C — Revisions after adversarial review (v2, what the engine implements)

Two independent reviewers (a "fun/decisions" lens and a "balance/exploits" lens) tore
into v1 before any code was written. They converged on the same structural flaw, so v2
folds the high-leverage fixes in. **The engine implements v2.** The deltas:

1. **Value rises with the Maw (the big one).** *Problem:* `glory = base×depth` +
   bottom-up collapse correlated value with time — the climax landed mid-game, the
   endgame fizzled on cheap floors, and the Worthy-End catch-up valve closed in the
   back half (no deep floors left to dive into) → a back-half runaway, contradicting
   the whole pitch. *Fix:* on collapse, a fraction (`value_rise_frac`) of each room's
   **unclaimed** value rises to the floor above as "refugee plunder." The Maw's
   frontier is therefore always the swelling hot zone, all the way up — the **final
   Floor-1 collapse is now the biggest scoring event**, the arc crescendos, and a
   trailing player can always dive into the (now-shallow) frontier for a real comeback.

2. **Re-entry near the frontier.** *Problem:* a fresh party from the Cash-Out loop
   starts at Floor 1 and can never reach the deep live floor before it collapses →
   Cash-Out self-limited to shallow farming; deep game decided once, early. *Fix:*
   re-entering parties insert at `max(1, frontier − reentry_gap)` — the upper floors
   are eaten anyway, so new delvers drop in near the action. Keeps every party relevant.

3. **One collapse per round (carry the remainder).** *Problem:* `while accum ≥ 1.0`
   could eat two floors in a round late-game, Taking "I'll flee next turn" parties with
   no Last Stand — a systematic feel-bad. *Fix:* at most `max_collapses_per_round`
   (default 1) collapses per round; the overflow carries in `accum`. "One floor away"
   is now an honest promise.

4. **Worthy End = burst + denial, not a bigger Cash-Out.** *Problem:* Cash-Out did
   almost everything Worthy-End did, safely and repeatably, so the triangle was a
   binary and Worthy-End read as the loser's button; also a `held_value` double-count
   risk. *Fix:* the two exits now have **non-overlapping** upside. **Cash-Out = the long
   game** (loot + depth dividend + Fallen markers that keep earning). **Worthy-End =
   burst + denial**: a guaranteed `worthy_factor × deepest_floor` spike *and the Maw
   consumes your held rooms clean* — their value is removed from the board so no rival
   inherits it. Now a *leader* takes a Worthy-End to deny a chaser a 36-point Vault.
   `worthy_held_bonus` is **0 by default** (no double-count); it's a separate knob.

5. **Variable-strength claims + assault progress.** *Problem:* contest-by-marker-visit
   was solitaire and un-reactable; deep claims were a ~5% one-turn lottery with no
   floor. *Fix:* a claim's marker **strength = 1 + symbols invested** (Warden ×2), so
   majority is a live bid; and unmet Steel/Cunning **accumulates as assault progress**
   on the room across turns, so a near-miss is never a total zero.

6. **Lineages get behavioral hooks; dead cells fixed.** *Problem:* Lineages were flat
   stat tweaks (no "two halves surprise you"), and some combos negated themselves
   (Golem-born Prospector locked out Relics; Gnoll Reaver / Revenant Hierophant stacked
   the same axis). *Fix:* Dvergar **ignores room threat** on its claim (smash-through —
   now Dvergar Lorekeeper cracks guarded Vaults); Revenant **converts Dread→Mettle**
   (peril as fuel, a decision, not redundant immunity); Golem-born's cost is now **−1
   hand size** (orthogonal — and it *cancels* Prospector's +hand, no dead cell).
   See `content.rs` for the final tables.

7. **Sub-linear depth + comeback rubber-band, both as knobs.** Room glory is
   `base × (1 + depth_coeff × (depth−1))` (`depth_coeff` tunes the cliff), and
   `comeback_bp` optionally scales a trailing party's exit payouts by its glory deficit.
   Both default conservatively and are what the sweeps actually move.

These are the hypotheses the sim must now confirm: that the triangle is live (no exit
> ~45% of winners' choices), that deep rooms are *contestable but not free*, that the
runaway is dead (tight margins; real comeback rate), and that the feel-bad is rare.

---

## B8. What the sim deliberately does *not* model

Intra-floor geometry & corridors; denizen reputation as a full subsystem (folded into a
threat modifier); trading/negotiation (no table talk to simulate); the exact card/draft
UI. These don't move the six questions above, and adding them would trade clarity for
false precision. The balance levers that *do* matter all live in `configs/default.json`
and in the Lineage/Calling tables in `deepfall-core/src/content.rs`.