diff --git a/.dev/2026-06-02-combat-system/spec/design.md b/.dev/2026-06-02-combat-system/spec/design.md index 4be950d..6792266 100644 --- a/.dev/2026-06-02-combat-system/spec/design.md +++ b/.dev/2026-06-02-combat-system/spec/design.md @@ -69,15 +69,22 @@ a table.** This is both the design elegance and the core requirement (§10–12) ## 3. The Resource Model ### Vigor, Cap, Fatigue -- `vigor` (current fill), `max_vigor` (level/stat-derived constant), `fatigue` (≥0, starts 0). -- `cap = max_vigor − fatigue`. `vigor` is clamped to `[0, cap]`. +- `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`. (Optional config: reduced regen rate while in - combat vs. idle.) + 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 @@ -107,6 +114,15 @@ to capacity *at the moment it lands*: 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. @@ -157,6 +173,11 @@ cascade. **Power is paid in vulnerability.** 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 @@ -168,7 +189,8 @@ Effects target *either* fill *or* ceiling — and the ceiling-attacking ones are content the system can have: - **Fill damage** — % of target `max_vigor` (con + mitigation applied). -- **Ceiling damage / curse** — drains target `fatigue` directly (attacks the real life total). +- **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. @@ -194,8 +216,16 @@ directions: (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, but it is *one* -curve doing double duty. +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. --- @@ -265,10 +295,54 @@ hook, not the leveling curve. - **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. -- **Determinism:** seeded **ChaCha8** RNG with per-roll sub-streams (mirrors `reikhelm-core`), so - tweaking one parameter doesn't reshuffle unrelated rolls. A fight = - `(config, seed, loadout_A, loadout_B)` → a *reproducible* outcome + full event log. This - reproducibility is what makes the analysis valid: change one knob, observe the isolated delta. + +### 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. --- @@ -293,15 +367,35 @@ rule changes are the only thing requiring a recompile. ## 12. Instrumentation, Metrics & Balancing ### Event stream -The engine emits a structured event per meaningful tick: `{tick, actor, action, fill_before, -fill_after, ceiling, fatigue, stagger_state, fizzle?, target, landed, outcome?}`. A **recorder** -rolls events into per-fight summary metrics. +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; #fizzles; total fill damage dealt/taken; total ceiling damage; min fill reached; -ceiling-decay curve; near-death recoveries; effective DPS; vigor/ceiling time series (optional, -sampled). +#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 × @@ -389,4 +483,10 @@ matters more than visuals. - **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. ```