reikhelm/.dev/2026-06-02-combat-system/spec/design.md

# Combat System — Design Spec

**Status:** draft for review · **Date:** 2026-06-02 · **Experiment folder:** `combat/` (to be created)

> A standalone experiment in the reikhelm sandbox. **No dependency on `reikhelm-core`** — it
> only borrows the same conventions (pure deterministic core, serde config, ChaCha8 RNG,
> headless-first, front-ends as consumers). Lives in its own top-level folder per the
> repo's one-experiment-per-folder convention.

---

## 1. Thesis

A real-time (tick-based) combat system in the EverQuest / Daggerfall lineage — auto-attack +
skills + magic — built on one deliberately unusual idea: **a single combined resource pool**
that replaces separate HP / mana / stamina. Everything you do *and* everything done to you
draws on the same bar. Offense literally spends your survival.

It is **a deterministic simulation first, a playable game second.** The "feel" is not
eyeballed — it is *measured* across thousands of simulated fights and tuned to target
durations and difficulty curves. The engine is pure and headless; a batch sim harness and
(later) a real-time visual front-end are both just consumers of it.

### The two-axis model (the spine)

Every combatant has one pool, **Vigor**, with three derived quantities:

| Term | Meaning |
|------|---------|
| **Vigor (fill)** | Current value of the pool. Also **= your absorb capacity** (see §4). |
| **Vigor Cap (ceiling)** | `max_vigor − fatigue`. The highest your fill can regen to *right now*. |
| **Fatigue** | Accumulated, fight-scoped reduction of the cap. Recovers only out of combat or via recovery abilities. |

Every combat verb is a point on **two axes** — cost to *fill* and cost to *ceiling*:

| Verb class | Δ fill | Δ ceiling | Example |
|------------|--------|-----------|---------|
| Offense (skills/spells) | `+cost` | `+cost` | kick = (5, 1) |
| Auto-attack & defensive reactions (block/parry/evade) | `0` | `+small` | swing = (0, 1) |
| Recovery (spells/skills/potions) | `+cost` | `−restore` | second wind = (8, −5) |
| Damage taken | `−mitigated` | `+fatigue_share` | — |

The entire combat vocabulary is different numbers in that grid. **Balancing the game is editing
a table.** This is both the design elegance and the core requirement (§10–12).

---

## 2. Goals & Non-Goals

**Goals**
- A combined-pool, mitigation-and-recovery combat model that *feels* tense and fair.
- Fully data-driven: every number is config; nothing balance-relevant is hardcoded.
- Deterministic and headless: a fight is reproducible from `(config, seed, loadouts)`.
- Instrumented: emits a structured event/metric stream; exports CSV/JSON for analysis.
- Batch-simulatable: run 10⁴–10⁶ fights across matchup/parameter sweeps to tune balance.
- Symmetric: players and monsters run the *identical* model; only their controller differs.
- Composable abilities: skills and spells are one system built from effect primitives.
- Emergent role identity **without classes and without training points**.

**Non-Goals (this experiment)**
- Rendering / animation / art. (A visual front-end comes later, as a consumer.)
- Movement & real positioning. Range is abstracted to a scalar/band for now.
- Loot, XP curves, character creation, networking, persistence.
- The crafting / discovery / reagent economy that *produces* abilities — separate experiment.
- The progression system that *grows* competency — separate experiment.

---

## 3. The Resource Model

### Vigor, Cap, Fatigue
- `vigor` (current fill), `max_vigor` (level/stat-derived constant), `fatigue` (starts 0).
- `fatigue` is clamped to `[0, max_vigor]`; `cap = max_vigor − fatigue` (so `cap ∈ [0,
  max_vigor]`). `vigor` is clamped to `[0, cap]`.
- **Regen**: each tick, `vigor += regen_per_tick`, clamped to `cap`. Regen restores *fill toward
  the ceiling only* — it never touches `fatigue`. Config carries an idle and a (lower) in-combat
  rate, and a **non-zero floor**: regen is reduced when dazed and by regen-sabotage effects but
  never reaches 0 *except when unconscious* — so an actor can always claw back toward affording an
  action (no soft-lock; see §6).
- **Fatigue ("spend leaves a mark")**: any point that *leaves* the pool generates fatigue.
  Default `fatigue += fatigue_ratio × amount_spent` for damage taken and unlabeled spend;
  abilities may override with an explicit authored `fatigue_cost`. Fatigue only decreases via
  **recovery abilities** (in combat) or **rest** (out of combat). It does *not* regen.
- **Ceiling collapse is the real loss condition.** Because every incoming hit adds fatigue,
  even pure defense erodes your ceiling over time — *turtling is not viable*. When `fatigue`
  reaches `max_vigor`, `cap = 0`, capacity is 0, and the actor collapses (→ unconscious → dead per
  §4). Attrition kills by collapsing the ceiling, not by a single drain.

### Damage in
- An attack's landed damage is **a percentage of the target's `max_vigor`**, set by the **con
  curve** (§7) and reduced by the **mitigation pipeline** (§8). Even-con, unarmored ≈ 10%;
  +5 levels ≈ 30%; −5 levels ≈ 2% (illustrative anchors; the curve is config).
- Applying damage: `vigor −= landed`; `fatigue += fatigue_ratio × landed` (a share of every hit
  becomes permanent-for-the-fight ceiling loss). Then resolve stagger (§4).

### The squeeze
You don't lose by emptying your fill once — you lose because **attrition grinds your ceiling
down**, a lower ceiling means a lower fill, and a low fill means the next big hit overruns your
capacity and triggers the stagger cascade. Everything points at the same death.

---

## 4. Stagger Cascade (the death model)

There is no instant "vigor = 0 → dead". **Capacity = current `vigor`.** A landed hit is compared
to capacity *at the moment it lands*:

| Landed hit vs. capacity | Result |
|-------------------------|--------|
| `hit ≤ vigor` | Absorbed normally. `vigor −= hit`. |
| `vigor < hit < 1.5 × vigor` | **Dazed / knocked down** (temporary status). Regen rate reduced. |
| `hit ≥ 1.5 × vigor` | **Unconscious.** Regen zeroed until recovered. |

Once unconscious, regen can't save you and follow-up hits grind you to 0 → **dead**. The
thresholds (`1.0×`, `1.5×`) and the dazed regen penalty are config.

**Reconciling with "no instant death":** "no instant `vigor = 0` → dead" means a single *fill*
subtraction never kills you outright. You are lost only when (a) a burst **overruns capacity**
(the cascade above) or (b) **attrition collapses your ceiling** (§3: `fatigue → max_vigor`, so
`cap → 0`). When `cap = 0`, capacity is 0 and the next hit trivially clears `1.5 × 0` →
unconscious — that *is* the intended attrition-death path, fully consistent with the rule.
**Reaching `cap = 0` is itself the collapse trigger** (treated as an instantaneous self-overrun →
unconscious), so an actor who self-fatigues to zero in a lull collapses immediately without waiting
for an incoming hit — the §3 state-threshold and this §4 mechanism describe the same moment.

**Consequence that makes it sing:** spending offense lowers your fill, which lowers your
capacity, which raises your stagger risk *on the very next hit*. "Fire the kick at 60%, eat an
add's swing, get staggered" is a real mechanical cascade, not flavor.

---

## 5. Actors & Symmetry

**Every combatant is the same `Actor`** — same Vigor/Cap/Fatigue, same stagger cascade, same
ability resolution. Variety comes from two independent dials:

- **Stat block** → archetype. Golem = huge `max_vigor`, big hits, *slow* regen, long attack
  delay. Rat = tiny pool, fast cheap pecks. Same model, different numbers.
- **Controller** → *intent*. A pluggable decision layer that emits actions (`attack / use
  ability / wait / recover`). The Actor doesn't know who drives it:
  - **Player controller** — driven by input (interactive front-end) or a scripted policy (sim).
  - **AI controllers** — v1: swing-on-cooldown. Later: *hold-and-punish* (wait, watch the
    target's fill, unload the haymaker exactly when they've spent low to overrun capacity),
    kite, heal. The AI plays the same timing meta-game the player does.

Controllers are swappable with zero changes to combat math — critical for the sim (scripted
policies of varying skill let us measure the gradual→brutal difficulty curve).

---

## 6. Abilities — Unified Skills + Spells

**Skills and spells are one thing: an `Ability`.** "Kick" = melee delivery + physical effect +
potency. "Fireball" = projectile delivery + fire effect + potency. Both resolve through the same
two-axis cost + effect grid.

### Composition
An ability is composed from:
- **Delivery / shape** — `self / touch / melee / projectile / beam / aoe(n)`. Sets targeting and
  a base cost.
- **Effect(s)** — one or more, drawn from the **effect library** (§6.1). Each adds cost.
- **Potency** — scalar multiplier on effect magnitude *and* cost.
- **Target count** — 1..N. Multiplies cost.

`cast_cost = f(delivery, Σ effects, potency, targets)` → an **absolute** `(fill_cost,
fatigue_cost)`. Higher potency / more effects / more targets ⇒ more expensive. The 6-target,
potency-10 AoE "cosmic nuke" costs ~90% of a *full* bar — leaving you at ~10%, one swing from the
cascade. **Power is paid in vulnerability.**

### Cost is absolute; pay-at-start
- **Affordability gate:** you cannot begin an ability whose `fill_cost > current vigor`. Heavy
  abilities are gated behind a healthy bar; as your ceiling grinds down over a fight, you
  progressively **lose access** to your big hitters.
- **Pay at cast-start; fizzle or interruption = paid for nothing.** One rule covers both fizzle
  risk (§9) and getting staggered mid-cast: you spent the cost and the ability never fired.
- **No soft-lock.** Auto-attack is always affordable (`0` fill), so an actor is never fully
  action-locked — at worst reduced to auto-attack-and-regen (a *losing* position, not a frozen
  one). Recovery abilities are authored **cheap (low or zero `fill_cost`)** so they stay reachable
  when you most need them; together with the regen floor (§3), pay-at-start/fizzle can put you in
  danger but cannot strand you in a permanently unrecoverable state.

### Cast time
- The only structural axis separating "skill" from "spell": skills are mostly instant; spells
  have a **wind-up** (cast time in ticks) during which you are exposed and interruptible. Cast
  time is per-ability config.

### 6.1 Effect library (both axes)
Effects target *either* fill *or* ceiling — and the ceiling-attacking ones are the most on-thesis
content the system can have:

- **Fill damage** — % of target `max_vigor` (con + mitigation applied).
- **Ceiling damage / curse** — *raises* target `fatigue` directly, lowering their cap (attacks the
  real life total). The inverse of Recovery, below.
- **Regen sabotage** — reduces target regen for a duration.
- **Fatigue amplification** — raises target's fatigue-per-spend for a duration.
- **DoT / HoT** — fill drain / restore over ticks.
- **Mitigation debuff / buff** — feeds the mitigation pipeline (§8).
- **Recovery** — `−fatigue` (raises ceiling) at a `+fill` cost; the inverse verb.

Effect types are a small enum/registry; adding one is a library entry, not an engine change.

### 6.2 Defensive abilities
Block / parry / evade are abilities with `(0 fill, +fatigue)` and a brief **active window**:
incoming hits landing during the window are mitigated/negated (they feed the §8 pipeline). They
cost endurance, never your guard. (Reactive timing vs. the attacker's wind-up is the defensive
counterpart to timing your offense — see Designed-For §14.)

---

## 7. The Con Curve (shared level-delta mapping)

A single config-driven curve maps **level delta** to a magnitude multiplier, reused in *both*
directions:
- **Incoming damage %**: `delta = attacker_level − defender_level` → base damage % of pool.
- **Outgoing effect resist/effectiveness**: `delta = caster_effective_level − target_level`
  (caster_effective_level folds in competency, §9) → fraction of the effect that lands.

Anchors (config, illustrative): even-con baseline; ≈3× at +5; ≈0.2× at −5; roughly monotonic.
Represented as a parametric function or a small lookup table — TBD in tuning.

**Caveat on the "double duty":** the curve takes a **delta**, but its two callers feed
differently-shaped domains — incoming damage uses raw `attacker_level − defender_level` (bounded
by the level range), while outgoing effectiveness uses a *competency-inflated* effective-level
delta (potentially wider). Keep the curve's input domain explicit and range-check the
competency-derived delta against it; if competency inflation pushes the effective range past where
the damage-tuned curve behaves, the two callers may need to **split into separate curves**. v1 has
no competency (§14), so this won't surface until the progression layer lands — write the curve call
so a later split is cheap, not a rewrite.

---

## 8. Mitigation Pipeline

All "how much of this hit actually lands" reduction flows through **one ordered pipeline** so new
sources are additive contributors, never reworks:
- **Armor** — passive attrition reduction (shrinks the damage %). Does *not* protect against
  stagger; it just makes you bleed fill slower so you stay in the safe band longer.
- **Con** — the level-delta curve (§7).
- **Active defenses** — block/parry/evade windows (§6.2).
- **Stances** *(designed-for)* — toggled mitigation trades.
- **Buffs/debuffs** — temporary contributors from effects.

Player skill = *which* abilities and *when*, not gear stat-checks. Armor and con set the
backdrop; timing decides the fight.

---

## 9. Progression & Identity

### Competency (soft gates)
Each Actor has a **competency value per school** (e.g., Invocation, Fire). Competency is mostly
*not* a hard cast wall; it drives two independent checks:
- **Fizzle — "does it go off?"** `f(competency, ability difficulty)`, where difficulty is driven
  by the same factors as cost (potency, #effects, #targets). Low competency vs. high difficulty ⇒
  frequent fizzle (and per §6, a fizzle means you *paid for nothing*).
- **Resist / effectiveness — "how much lands?"** the con curve (§7) with caster competency folded
  into effective level. Even a sneaked-off potency-10 cast gets shrugged off by an over-con
  target.

A few **hard school gates** are allowed for structure (e.g., a school locked until competency ≥ X).

### Two independent brakes on power
- **Cost** gates *affordability* (can you pay it?).
- **Competency** gates *reliability + effectiveness* (will it fire, will it land?).

You cannot craft a god-spell at level 1 and skip the game: you'll mostly fizzle, and what lands is
resisted to a trickle. Progression is *earned*, not bought.

### No classes, no training points — three-layer emergent identity
1. **Competency = who you are over time.** Your per-school profile *is* your identity; earned by
   use, never allocated.
2. **Loadout / memorization = who you are this fight.** Your known set can be large, but you commit
   a *limited slotted set* per encounter (re-slot only on rest / out of combat). Even an
   omni-competent veteran must choose a role for this pull — breadth of knowledge ≠ breadth of
   power.
3. **Shared pool = who you are this second.** One bar means you can't be nuker *and* healer at
   once; the resource economy forces a moment-to-moment role with no extra rules.

Pure classes are rigid and fight the composable model; pure à-la-carte waters down because
everyone converges on one optimal kit. The loadout commitment + competency lag keep roles sharp
with zero class definitions and zero skill points.

**Optional knob (ship OFF):** gentle competency **atrophy** — unused schools drift toward a floor —
as a firmer long-term brake *if* veterans start homogenizing.

### Seam
**Combat consumes competency values and emits "used <school> successfully" events.** *How*
competency grows (use-based skill-ups, etc.) is a separate progression experiment. We build the
hook, not the leveling curve.

---

## 10. Time Model & Determinism

- **Fixed tick** (default 10 ticks/s, config). *Every* duration — attack delay, cast time, regen,
  status durations, active windows — is expressed in **ticks**. Headless: ticks advance as fast as
  the CPU allows. Real-time front-end: ticks advance on a wall clock.

### Reproducibility (load-bearing for all analysis)
A fight = `(config, seed, loadout_A, loadout_B)` → a *bit-reproducible* outcome + event log.
"Change one knob, observe the isolated delta" only holds if unrelated rolls don't reshuffle and
arithmetic doesn't drift. Two hard requirements — neither is satisfied by "ChaCha8" alone:

- **Order-independent, version-stable RNG forking.** Reuse `reikhelm-core`'s `Rng::fork` contract
  *verbatim* (vendor `reikhelm-core/src/rng.rs` as a module): a hand-rolled integer mix (splitmix64
  + FNV-1a), **`&self` (non-mutating) and order-independent** — explicitly **not**
  `std::collections::hash_map::DefaultHasher`, whose output is version-unstable. Sub-streams are
  keyed by a stable string, e.g. `fork("actor{id}:{roll_kind}:tick{t}")`, so adding an effect to
  one ability never shifts another actor's or another tick's stream. *This property* — not
  ChaCha8 itself — is what makes the isolated-delta guarantee true.
- **Integer fixed-point internal state.** `vigor`, `cap`, `fatigue`, and all magnitudes are stored
  as scaled integers (e.g. milli-units); every formula (con %, potency multiply, `fatigue_ratio ×
  amount`, each mitigation stage) is evaluated in integer arithmetic with **documented rounding at
  each pipeline stage**. This mirrors reikhelm-core's integer-space discipline and gives bit-exact
  results across compilers / opt-levels / machines — IEEE-754 `f64` *multiply chains* do **not**
  (ChaCha8 gives a portable random *stream*, not portable *arithmetic*). All **magnitude**
  arithmetic stays integer; `f64` is otherwise confined to config parsing. **One deliberate
  exception:** the vendored `Rng::chance(p: f64)` does its roll as a `u64 → f64` unit-interval
  divide-and-compare (`rng.rs:106-117`) — a single division + compare, which *is* IEEE-deterministic
  across platforms — so probabilistic checks (fizzle, §9) may use it. That single compare is the
  only f64 allowed in the hot path; if even that's unwanted, add an integer-threshold `chance`
  variant (compare the raw `u64` bits against `p` scaled to `u64`). Either way, no f64 ever touches
  a magnitude. Avoid iteration-order-dependent containers (`HashMap`) in the hot path; use
  ordered/`BTreeMap` or `Vec` keyed by actor-id.

### Canonical within-tick resolution order (a determinism invariant)
Several things resolve on one tick and the order changes outcomes (regen-before-damage yields
fewer staggers than regen-after; sequential hits differ from batched), so it is **fixed**, not an
implementation detail:

0. **Controllers decide**, in ascending actor-id order, *before* anything else resolves. Starting a
   cast or auto-attack pays its cost **here** (cast-start payment, §6) and opens cooldowns/windows;
   instant abilities enqueue their effects for step 2. Pinning this first, by actor-id, is what
   makes the affordability gate and stagger checks see a deterministic state.
1. **Expire** finishing statuses and active-defense windows (a window covering tick *t* is
   *inclusive* of hits landing on tick *t*).
2. **Resolve completing casts** → enqueue their hits/effects for steps 3–4.
3. **Apply incoming hits sequentially in ascending actor-id order** (sequential, not batched: hit 1
   lowers `vigor`, raising hit 2's stagger odds), each followed immediately by its **stagger check**
   (§4) and its **fatigue add** (§3).
4. **Tick** DoT/HoT and other per-tick effects.
5. **Apply regen** (clamped to `cap`).

Determinism is part of the contract — any reordering (including controller-decision timing, step 0)
is a breaking change to recorded data.

---

## 11. Configuration — the "table"

A single serde-(de)serializable `CombatConfig` holds **all** tunables, loadable from JSON.
Categories:
- Tick rate; regen rates (idle vs in-combat); dazed regen penalty.
- `fatigue_ratio`; stagger band thresholds.
- Con curve (parameters or table).
- Mitigation: armor tiers, stance values.
- Cost formula coefficients (delivery base costs, per-effect cost, potency scaling, per-target
  multiplier); auto-attack `(0, small)` default.
- Fizzle & resist curve parameters.
- Actor stat blocks & ability/effect library definitions (data, not code).

Nothing balance-relevant is hardcoded. Editing config is the primary balancing act; structural
rule changes are the only thing requiring a recompile.

---

## 12. Instrumentation, Metrics & Balancing

### Event stream
The engine emits a structured event per meaningful tick. Outcomes alone can't tell you *why* a
config feels bad, so the schema records **causes**, not just results:
`{tick, actor, action, fill_before, fill_after, ceiling, fatigue, stagger_state, target,
damage_pre_mitigation, mitigation_by_stage[armor, con, defense, buff], landed,
fail_reason ∈ {none, competency_fizzle, interrupted}, action_blocked_reason?, outcome?}`.
A **recorder** rolls events into per-fight summary metrics. Each added field is load-bearing for
tuning:
- **Pre-mitigation damage + per-stage mitigation deltas** — you cannot tune the con curve (§7, the
  balance lever) from the final `landed` number alone; you need each stage's contribution.
- **`action_blocked_reason`** (`cant_afford` / `on_cooldown` / `dazed` / …) — a "wanted to act but
  couldn't" signal. Without it, a fight where an actor spent 40% of ticks unable to afford anything
  is indistinguishable from one where it chose to wait, and the soft-lock/turtle modes are invisible.
- **`fail_reason` splits competency-fizzle from interruption** — otherwise "competency too low" and
  "wind-ups too long" collapse into one signal you can't separate.

### Per-fight metrics (export to CSV/JSON)
Time-to-resolution (ticks & seconds); outcome (win/loss/draw/timeout); #staggers, #dazes,
#unconscious; #competency_fizzles, #interruptions; blocked-actions by reason; total fill damage
dealt/taken; total ceiling damage; min fill reached; ceiling-decay curve; near-death recoveries;
effective DPS; **fill-flow accounting (gained-by-regen vs. spent-on-actions vs. lost-to-damage)** —
§15 names regen-vs-drain-vs-spend as the make-or-break co-tuning, so the sums must be visible;
vigor/ceiling time series (optional, sampled).

### Anti-turtle guardrail
Absorbed hits still erode the ceiling (§3), so passive-forever loses — but **auto-attack-only** can
still dominate if abilities aren't *efficient enough* (favorable damage-per-resource, or utility
auto-attack lacks). Track it explicitly: **fraction of fights won by an auto-attack-only policy.**
If that's high, the interesting verbs are a tax players opt out of — contradicting the thesis — and
the fix is a damage-per-resource/utility edge, not a tuning nudge.

### Batch harness & "feel" as acceptance criteria
A harness runs **N fights across a matchup/parameter sweep** (level-delta × armor tier × loadout ×
controller-skill) and exports the aggregate. The user's "feel" failure modes become *measurable
guardrails*:
- *"slow player knocked every 2s quits"* → **stagger-frequency ceiling**: from a full bar, an
  even-con opponent must not stagger-lock you in under *N* hits.
- *"gradual but scales to brutally difficult"* → a **target time-to-kill curve by con-tier**:
  under-con trivial, even-con a satisfying ~X-second fight, +5 winnable only with skilled play,
  +8 lethal. Sweep parameters until the curve matches the intended shape.

### Analysis layer
A Python package (`combat/analysis/`, own `.venv`) consumes the exported CSV/JSON via pandas:
sweep orchestration, difficulty-curve plots, parameter search toward target durations.

---

## 13. Architecture & Layout

```
combat/                      # own Cargo workspace — independent of root reikhelm workspace
  Cargo.toml                 # [workspace] so the parent workspace never absorbs it
  combat-core/               # pure deterministic engine: Actor, Ability, tick loop, RNG, events
                             #   no I/O, no rendering, no real-time. The single source of truth.
  combat-sim/                # binary: load config + scenarios, run batch sweeps,
                             #   record metrics, export CSV/JSON
  analysis/                  # Python: pandas/plots over exported data (own .venv, own .gitignore)
  configs/                   # JSON configs / sane defaults
  README.md
  # (later) combat-wasm/ + a web playable, mirroring the reikhelm-web pattern
```

- **Decoupling:** root `Cargo.toml` uses explicit `members` (no globs), and `combat/Cargo.toml`
  declares its own `[workspace]`, so `combat/` is a self-contained experiment that neither
  pollutes nor depends on the existing crates.
- **Deps (to be created):** `combat-core` → `rand_chacha = "0.10"`, `serde = { "1", features =
  ["derive"] }`; `combat-sim` → `serde_json`, plus a CSV writer (e.g. `csv`). Edition 2021,
  Rust 1.96.
- **gitignore additions:** `combat/target/`, `combat/analysis/.venv/`, exported data
  (e.g. `combat/**/out/`, `*.csv` under combat output dirs).

---

## 14. Scope — v1 Vertical Slice vs. Designed-For

The full vision above is the *design*. To find the fun before building all of it, **v1 proves the
core loop and the balancing capability** — which, for a data-first build, means the headless sim
matters more than visuals.

**v1 vertical slice (build this first):**
- `combat-core`: Actor + Vigor/Cap/Fatigue + stagger cascade + regen + mitigation (armor + con) +
  fixed-tick loop + seeded RNG + event emission.
- **3–4 hardcoded abilities** (auto-attack, a cheap skill, a heavy skill, a recovery) — not the
  composer yet; just enough to exercise the two-axis grid.
- **One dumb-AI controller** (swing-on-cooldown) + a scripted player policy.
- `combat-sim`: run a matchup sweep, export per-fight metrics CSV.
- `analysis`: a first notebook plotting TTK and stagger-frequency by con-tier.
- **Success = the duration/difficulty curves are tunable via config to the intended shape.** If
  managing one pool against the stagger cascade is tense in the data, we layer the rest on.

**Designed-for / explicitly deferred (nothing dropped):**
- The **ability composer** + data-driven effect library (v1 hardcodes; the model is built so this
  slots in).
- **Competency / fizzle / resist** as data-driven progression inputs.
- **Loadout / memorization** mechanic.
- **Telegraphs & reactive defense** (block/parry/evade timed vs. wind-up) — nearly free once
  abilities have cast-time windows.
- **Stances** (mitigation knob), **ceiling-attacking effect content**, DoT/HoT/buff/debuff breadth.
- **WASM build + real-time visual playable** (another consumer of `combat-core`).
- **Crafting / discovery / reagents** (separate experiment) and **competency advancement**
  (separate experiment) — combat exposes the seams.
- Smarter AI controllers (hold-and-punish, kite, heal).

---

## 15. Open Questions / Risks

- **Con curve shape** is the balance lever the whole feel rides on; it will need real sweep data
  to settle. Start parametric, validate against target curves.
- **Regen vs. drain vs. spend rates** must be co-tuned, or even-con fights are either un-loseable
  (regen dominates) or stagger-locked (drain dominates). The sim exists precisely to find this
  balance; treat default numbers as placeholders.
- **Fizzle-cost severity**: pay-at-start + fizzle-for-nothing is brutal by design; verify it
  doesn't make low-competency casting *never worth attempting* (which would stall progression).
- **Scripted "player skill" policies** for the sim are themselves a modeling choice — the
  difficulty curve is only as meaningful as the policies are representative. Document the policies
  used for any published balance numbers.
- **Auto-attack-only dominance** (see §12 guardrail) — the deepest balance risk: if abilities don't
  beat auto-attack on damage-per-resource or bring utility it lacks, the optimal policy is to never
  use the interesting verbs. Structural, not a number; watch the guardrail metric from day one.
- **Fixed-point rounding bias** (§10) — integer rounding at each pipeline stage can accumulate a
  systematic skew (e.g. always-floor quietly favors the defender). Pick a rounding rule
  deliberately and confirm it isn't biasing outcomes over long fights.
```