hayao 0.4.0 → 0.4.2

package/design/30-systems/combat-model.md

@@ -0,0 +1,113 @@
+---
+id: system-combat-model
+title: Combat Model — the shape of a hit
+kind: system
+tags: [combat, damage, resolution, timing, real-time, turn-based, hit]
+summary: The spine every fight sits on — how damage is computed, when it resolves, and whether the clock is frames or turns.
+use-when: You have any fight — melee, ranged, tactical, brawler — and need to decide how a hit is computed and when it lands.
+composes-with: [system-telegraphs, system-status-effects, system-counter-systems, system-grace, system-enemy-ai]
+anchors: [anchor-into-the-breach, anchor-hades, anchor-slay-the-spire]
+verify-with: docs/FUN.md#4-top-down-action-adventure-zelda-like
+---
+
+# Combat Model — the shape of a hit
+
+**What it is.** The **resolution rule** underneath every fight: the function that
+turns *attacker + defender + context* into *a number and a moment*. Pick it before
+you design a single enemy — the model decides whether combat is read-and-react,
+plan-and-commit, or math-and-optimize, and every other combat system ([[system-telegraphs]],
+[[system-status-effects]], [[system-counter-systems]]) hangs off it.
+
+**Player fantasy / why it's fun.** A hit that *lands* — weight, consequence, a clean
+line from your input to the enemy's flinch. Fun combat is legible cause and effect;
+the model is where that legibility is either won or lost.
+
+## When to use / when NOT
+
+| Use a formal combat model when… | Skip / simplify when… |
+|---|---|
+| Damage varies by matchup, position, or state | One-hit-kill or binary contact (a pure platformer) |
+| The player makes per-hit decisions | Combat is a garnish, not a pillar |
+| You need counters, statuses, or crits to interact | The "fight" is really a puzzle ([[genre-grid-puzzle]]) |
+
+Don't bolt a deep damage formula onto a game whose fun is elsewhere. A Celeste-like
+spike is `contact → death`; that *is* the model, and it's correct.
+
+## Variants
+
+| Model | Clock | Damage shape | Anchor | Feels like |
+|---|---|---|---|---|
+| **Real-time reactive** | frames | fixed per-hit, telegraph-gated | [[anchor-shadow-of-mordor]], Zelda | read the tell, punish the gap |
+| **Real-time attrition** | frames | many small ticks, DPS math | [[anchor-vampire-survivors]] | the tide vs your build |
+| **Turn-based deterministic** | turns | shown = resolved, no rolls | [[anchor-into-the-breach]] | perfect-information chess |
+| **Turn-based stochastic** | turns | dice / hit-chance | XCOM, roguelikes | budgeted luck, hedged plays |
+| **Deckbuilt** | turns | numbers from cards + scaling | [[anchor-slay-the-spire]] | the deck *is* the weapon |
+| **Combo / string** | frames | escalating multipliers per chain | [[anchor-hades]], brawlers | flow and cancels |
+
+Blends are normal: Hades is reactive + combo; Slay the Spire is deckbuilt +
+deterministic. Satisfy each parent's verify pattern ([[process-composition]]).
+
+## Tuning levers
+
+| Lever | Does | Healthy range |
+|---|---|---|
+| **Time-to-kill (TTK)** | hits to drop a basic foe | 2–5 for reactive; the whole session for attrition |
+| **Time-to-death (TTD)** | hits *you* survive | ≥ 2 before a wound; instadeath only with heavy telegraph |
+| **Hit-stop** | freeze on impact — the weight | 3–8 frames; > 12 reads as a hitch (JUICE Part 2) |
+| **i-frames** | invulnerable window after a hit | specced in frames, proven edge-in/edge-out |
+| **Variance** | roll spread (stochastic only) | tight enough that plans hold; ≤ ±15% or shown-as-chance |
+| **Crit rate / mult** | spike layer | rare + big, or frequent + small — not both |
+
+Derive TTK/TTD from the fight length you want, not by eyeballing (FUN.md law 3).
+
+## How it wires to Hayao
+
+- **Pure resolution.** Combat is a function over `world.state`; all rolls through
+  `world.rng`. The sim resolves *instantly* and returns choreography for the view
+  to replay (FUN.md law 6) — hit-stop and flash are cosmetic, never in `world.hash()`.
+- **Reactive combat is telegraph-gated.** Every threat activation is preceded by a
+  tell; prove it with `telegraphIssues(timeline, minFrames)`. See [[system-telegraphs]].
+- **Feel is a contract.** Declare a `FeedbackContract` (in `@hayao`) for `hit`,
+  `land`, `death`; gate hit-stop/shake with `feedbackIssues` (docs/JUICE.md Part 3).
+- **Turn-based reuses the real-time stack** — an input edge is one world step
+  (FUN.md §10). Pure state gives clone-and-score bots for free: run the intended
+  line vs a null line and assert the gap (FUN.md law 2).
+- Reference wiring: [`examples/updrift`](../../examples/updrift) for reactive feel;
+  the top-down §4 pattern for hit-stop + i-frames buffering inputs through the freeze.
+
+## Fails when…
+
+- **Hit-stop eats inputs.** A freeze that doesn't buffer intent across it makes
+  attacks "randomly" vanish (FUN.md §4). Any pause must re-emit buffered input.
+- **TTK too low both ways.** If you and the foe both die in one hit, there's no
+  combat — there's a coin flip. Give the loop room to *be* a loop.
+- **Variance drowns skill.** Big rolls on top of a reactive read punish the correct
+  play. If it's stochastic, *show* the chance (intent honesty, FUN.md §11/§12).
+- **Damage numbers with no resolution moment.** A number that ticks with no impact
+  frame reads as a spreadsheet, not a hit. Answer every hit on ≥ 2 senses (JUICE).
+
+## Verify
+
+- Reactive: kiting-bot telemetry — win time, hp floor, 0 deaths; every threat
+  telegraphed → **[FUN.md §4](../../docs/FUN.md)**, `telegraphIssues`.
+- Skill-delta: intended combat beats null (do-nothing / flail) by a margin →
+  **[FUN.md law 2](../../docs/FUN.md)**.
+- Feel: `feedbackIssues` for hit/death; hit-stop ≤ 12 frames →
+  **[JUICE.md Part 3](../../docs/JUICE.md)**, **[VERIFICATION Channel 4](../../docs/VERIFICATION.md)**.
+- Determinism: golden hash of a scripted fight; view-on == view-off hash.
+
+## Composes with
+
+- [[system-telegraphs]] — reactive combat is *only* fair if threats announce; the
+  telegraph is half the model.
+- [[system-status-effects]] — DoT/buffs/debuffs are damage that resolves over time;
+  they layer on the resolution rule.
+- [[system-counter-systems]] — the matchup table that makes one hit mean more.
+- [[system-grace]] — i-frames, hit-stop buffering, wound-before-death live here.
+- [[system-boss-design]] — a boss is a combat model with phases and spectacle.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §4, §6, §12 — the mechanical truths per clock.
+- [`docs/JUICE.md`](../../docs/JUICE.md) — hit-stop/shake envelopes; the 2-senses contract.
+- [`sandboxes/juice-lab`](../../sandboxes/juice-lab) — easing/spring feel for impacts.

package/design/30-systems/coop-and-competition.md

@@ -0,0 +1,118 @@
+---
+id: system-coop-and-competition
+title: Co-op & Competition
+kind: system
+tags: [coop, pvp, competition, asymmetric, interdependence, rivalry, multiplayer, communication]
+summary: Co-op and PvP hooks — asymmetric co-op, interdependence, and rivalry that make other players the most interesting system in the game.
+use-when: The design has more than one player and you need to shape how they cooperate, compete, or depend on each other.
+composes-with: [system-faction-asymmetry, system-encounter-design, genre-coop-chaos, pattern-emergence]
+anchors: [anchor-overcooked, anchor-it-takes-two]
+verify-with: docs/FUN.md#part-1--universal-laws
+---
+
+# Co-op & Competition
+
+**What it is.** The design of **other players** as a system. Two engines: **co-op**
+(players pursue a shared goal) and **competition** (players pursue opposed goals) —
+and the richest designs make players **interdependent** (co-op) or **rivalrous**
+(PvP) rather than merely co-located. Overcooked forces *communication* by making one
+person's job depend on another's; It Takes Two gives each player a *different verb*
+so neither can proceed alone.
+
+**Player fantasy / why it's fun.** *You needed me / I beat you.* Co-op's pull is
+shared triumph and the panic-laughter of a plan under pressure; competition's is the
+sharp joy of a read that beat a real mind. Both put the most reactive, least
+predictable system in the room — a *person* — at the center.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Two+ players share a screen/session | A solo experience — don't bolt on multiplayer |
+| Interdependence or rivalry is the *point* | "Multiplayer" that's just two solo games side by side |
+| Communication-under-pressure is the fun | Turn-based async where presence adds nothing |
+
+> **Interdependence is the design, not the player count.** Two players who could
+> each finish alone are playing *near* each other, not *with* each other. Force the
+> dependency — split the verbs, split the resources, split the information — and
+> co-op becomes a conversation ([[anchor-overcooked]], [[anchor-it-takes-two]]).
+
+## Variants
+
+| Variant | Structure | Feels like | Anchor |
+|---|---|---|---|
+| **Symmetric co-op** | same abilities, shared goal | "divide the work" | most horde co-op |
+| **Asymmetric co-op** | different verbs, shared goal | "I can't do your job" | [[anchor-it-takes-two]] |
+| **Forced-comms co-op** | one's task gates another's | "TALK to me" | [[anchor-overcooked]] |
+| **Symmetric PvP** | mirror match | "pure skill read" | fighting/RTS |
+| **Asymmetric PvP** | different roles/goals | "hunter vs. hunted" | 1-vs-many |
+| **Shared-world rivalry** | indirect competition | "I beat your score/ghost" | leaderboards, ghosts |
+
+## Tuning levers
+
+| Lever | Effect | Watch for |
+|---|---|---|
+| **Interdependence depth** | how much players *need* each other | too much = one weak link stalls all; too little = parallel play |
+| **Communication pressure** | how hard they must coordinate | time pressure forces talk (Overcooked); own it in [[genre-coop-chaos]] |
+| **Asymmetry balance** | different roles, comparable impact | one role feeling like a passenger kills it |
+| **Rivalry stakes** | what winning takes from the loser | too harsh = griefing; too soft = no bite |
+| **Solo-fallback** | can one carry a struggling partner? | none = brittle; total = interdependence lost |
+
+## How it wires to Hayao
+
+- **Multiple players = multiple input streams into one deterministic sim.** Each
+  player's intent flows as input *actions* on the shared `world.state`; because the
+  sim is pure and rolls through `world.rng`, a co-op or PvP session is one
+  deterministic, replayable artifact — the same seam Studio records
+  ([`docs/STUDIO.md`](../../docs/STUDIO.md), FUN.md law 7). *(Grep `docs/API.md`
+  before assuming any specific netcode primitive — Hayao's guarantee is the
+  deterministic sim, not a bundled transport.)*
+- **Rollback-with-carryover is already here.** The knob-change / hot-swap
+  "snapshot → restore → `attach`" contract is the *same* contract rollback netplay
+  uses (STUDIO knob-change semantics) — the determinism you need for co-op is the
+  determinism the engine already enforces.
+- **Asymmetric roles reuse faction design.** "Different but fair" is exactly
+  [[system-faction-asymmetry]] applied to players — assert each role's viability the
+  way you'd assert a faction's.
+- **Shared encounters** are still [[system-encounter-design]] — pockets and exit
+  lanes now serve two bodies, not one.
+
+## Fails when…
+
+- **Parallel play.** Players who never need each other are two solo games sharing a
+  screen — no co-op fun (interdependence missing).
+- **A passenger role.** In asymmetric designs, a role with no real impact benches a
+  player — balance the roles like factions.
+- **Griefing headroom.** PvP stakes so harsh (or tools so one-sided) that winning
+  means ruining someone's session.
+- **Coordination with no pressure.** Co-op that *permits* silence rarely *creates*
+  talk — pressure (time, scarcity, split info) is what forces the conversation.
+- **Non-determinism across clients.** Any wall-clock, `Math.random`, or
+  iteration-order drift and the shared sim desyncs (CLAUDE.md invariant 2).
+
+## Verify
+
+- **Determinism across streams:** golden-hash a scripted two-player session; the
+  shared sim replays bit-exactly regardless of which player acted when
+  ([FUN.md law 7](../../docs/FUN.md#part-1--universal-laws)).
+- **Every role viable (asymmetric):** assert each role's contribution clears a
+  floor — the faction-viability check applied per player
+  ([[system-faction-asymmetry]]; FUN.md law 2 skill-delta shape).
+- **Interdependence proof:** a scripted "one player idles" run *fails* the shared
+  objective — if solo-carry always works, the dependency isn't real (FUN.md law 4
+  null-strategy shape).
+- **Shared encounter fairness:** pockets/exit-lanes hold for the group
+  ([[system-encounter-design]], FUN.md §4/§5).
+
+## Composes with
+
+- [[genre-coop-chaos]] — the genre where forced-comms co-op is the whole game.
+- [[system-faction-asymmetry]] — asymmetric roles are player-side factions.
+- [[system-encounter-design]] — fights now serve multiple bodies.
+- [[pattern-emergence]] — the most emergent system in any game is another person.
+
+## See also
+
+- [`docs/STUDIO.md`](../../docs/STUDIO.md) — deterministic sessions + the rollback-with-carryover contract.
+- [`docs/FUN.md` law 7](../../docs/FUN.md#part-1--universal-laws) — pure state makes multiplayer replayable.
+- [[anchor-overcooked]] · [[anchor-it-takes-two]] — forced communication and asymmetric interdependence.

package/design/30-systems/counter-systems.md

@@ -0,0 +1,115 @@
+---
+id: system-counter-systems
+title: Counter Systems — the duel matrix
+kind: system
+tags: [counters, rock-paper-scissors, matchup, duel, near-hard, balance]
+summary: Rock-paper-scissors with teeth — NEAR-HARD counters that stay decisive under scaling, so the answer to a threat is a choice, not a bigger number.
+use-when: You have unit types, weapons, or tools that should beat each other, and you need the matchups to actually matter.
+composes-with: [system-unit-rosters, system-faction-asymmetry, system-build-diversity, system-combat-model, system-status-effects]
+anchors: [anchor-starcraft, anchor-age-of-empires]
+verify-with: docs/FUN.md#8-tower-defense
+---
+
+# Counter Systems — the duel matrix
+
+**What it is.** The **matchup table**: the rule that pikes beat cavalry, air beats
+ground, fire beats ice. A counter system makes the *right tool* a decision instead
+of the *bigger stack* — it's what turns [[system-unit-rosters]] and
+[[system-faction-asymmetry]] into a game of composition rather than accumulation.
+
+**Player fantasy / why it's fun.** "I read your army and I built the answer." A
+counter is a puzzle you solve with production, not reflexes — scouting, reacting,
+and the small triumph of the hard counter arriving just in time.
+
+## When to use / when NOT
+
+| Use counters when… | Skip when… |
+|---|---|
+| Multiple unit/weapon types coexist | There's one avatar and one attack |
+| Composition should beat brute force | The fun is execution, not selection |
+| Factions/rosters need internal tension | You have < 3 types (no matrix to speak of) |
+
+## Variants
+
+| Shape | Counter strength | Anchor | Note |
+|---|---|---|---|
+| **Hard RPS** | A auto-beats B | fighting games, some RTS | decisive, can feel arbitrary |
+| **Near-hard** | A *strongly* favored vs B | [[anchor-starcraft]], [[anchor-age-of-empires]] | the sweet spot — see below |
+| **Soft resist** | A takes ~15% less from B | many RPGs | **erased by scaling** — avoid as the whole system |
+| **Tag / type** | fire > ice > … cyclic | Pokémon | legible, teachable |
+| **Positional** | flank/backstab/height | tactics | counter is *where*, not *what* |
+
+## The near-hard doctrine
+
+FUN.md §8/§9 is blunt: **soft resists get erased by count-scaling.** A 15% resist
+vanishes the moment the player fields ten of the resisting unit — the matchup stops
+mattering, and the "counter" is decorative. Counters must be **near-hard**: strong
+enough that the *right* unit meaningfully wins the duel even before you out-mass.
+
+The design target is a duel you can prove:
+
+> The counter unit wins its NvN duel at equal or lower cost; the countered unit,
+> even with a *bigger budget*, loses it. (FUN.md §8: "mono build with a bigger
+> budget fails; mixed build survives.")
+
+Near-hard, not *hard*, because a pure auto-win removes the micro/positioning layer —
+you want "strongly favored, still winnable with skill," not "the fight is decided
+by the build screen."
+
+## Tuning levers
+
+| Lever | Does | Healthy range |
+|---|---|---|
+| **Counter multiplier** | how much the favored unit wins by | near-hard: the duel flips outcome, not just shaves HP |
+| **Matrix density** | how many pairs have a counter | every unit both counters and is countered — no pure winner |
+| **Reveal cost** | how hard to scout the enemy comp | information *is* the counter game; make scouting real |
+| **Reaction lead time** | build-time to answer a threat | long enough to punish greed, short enough to recover |
+| **Cyclicity** | RPS loop closes (no dominant) | assert no unit sits outside all counters |
+
+## How it wires to Hayao
+
+- **The duel is the test.** Pure state + `world.rng` means you clone the world, run
+  an NvN fight, and read the result (FUN.md law 7). Assert each counter edge wins its
+  duel from *both sides* (FUN.md §8/§9). RTS-lite exports arrival/tolerance constants
+  as API so the test shares the sim's constants (FUN.md §9).
+- **Coverage is geometry** for ranged counters — range × distance-to-lane = the
+  fire-window chord (FUN.md §8). Draw the ring; it's the genre's key UI.
+- **Mass pathing** for RTS counters uses cached flow fields (one BFS per goal,
+  *outside* state) — see [[system-unit-rosters]] and FUN.md §9. Grep [`docs/API.md`](../../docs/API.md)
+  for `astarGrid`/`floodFill` before citing a pathing call.
+- Reference: FUN.md §9 RTS-lite (counter-edge NvN duels) and §8 tower-defense
+  (mixed beats mono).
+
+## Fails when…
+
+- **Soft resists only.** Scaling erases them; the "counter system" evaporates by
+  midgame (the canonical §8/§9 failure).
+- **A dominant unit.** One type outside the RPS loop becomes the answer to
+  everything — [[system-build-diversity]] and the whole matrix collapse.
+- **Invisible matchups.** Counters the player can't scout or read are just
+  memorization tax. Surface the matrix (a range ring, a type icon).
+- **Hard auto-wins everywhere.** Removes micro — the fight is settled off-screen.
+  Aim near-hard, keep a skill margin.
+
+## Verify
+
+- **[FUN.md §8](../../docs/FUN.md)** — mixed build survives 10/10; mono build (bigger
+  budget) fails; bare lane falls early; counter duels from both sides.
+- **[FUN.md §9](../../docs/FUN.md)** — every counter edge wins its NvN duel; the
+  intended composition beats attack-move.
+- **[FUN.md law 2](../../docs/FUN.md)** — the countering strategy beats the null (mono)
+  strategy by a margin.
+- Determinism: golden hash of a scripted duel set.
+
+## Composes with
+
+- [[system-unit-rosters]] — the roster is the set of pieces the matrix connects.
+- [[system-faction-asymmetry]] — factions counter *across* the mirror, not just within.
+- [[system-build-diversity]] — near-hard counters are what keep multiple builds alive.
+- [[system-status-effects]] — cleanse/resist/immunity are the status-layer counters.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §8, §9 — the duel-from-both-sides proofs.
+- [[anchor-starcraft]] — three rosters, near-hard counters, one balance.
+- [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo) — `astarGrid`/`floodFill` for mass counters.

package/design/30-systems/crafting.md

@@ -0,0 +1,115 @@
+---
+id: system-crafting
+title: Crafting — Recipes & Combinatorial Depth
+kind: system
+tags: [crafting, recipes, combination, discovery, lookup, depth, materials]
+summary: Combining inputs into outputs by recipe; combinatorial depth as content, and the discovery-vs-lookup axis that decides how the player learns it.
+use-when: The design lets players combine materials/items into new ones and you need the recipe space to be deep, legible, and worth exploring.
+composes-with: [system-resource-loops, system-economy, system-build-diversity, system-collectibles, system-tech-tree]
+anchors: [anchor-factorio, anchor-stardew-valley]
+verify-with: docs/FUN.md#1-grid-puzzle-sokoban
+---
+
+# Crafting — Recipes & Combinatorial Depth
+
+**What it is.** A **recipe system**: inputs (materials, items, ingredients) combine
+by rule into outputs. The depth is combinatorial — a modest set of inputs and
+recipes yields a large possibility space. The design choice is how the player
+*learns* the space: handed the recipe (**lookup**) or finding it (**discovery**).
+
+**Player fantasy / why it's fun.** "I turned these scraps into *that*." Crafting
+rewards planning and packrat instinct; discovery crafting adds the "what if I
+combine…" curiosity. The pull is the recipe you don't have yet — and the hunch
+about what makes it.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Combining things is a core verb (survival, sim, alchemy) | Items are found whole; no combination step |
+| You want depth from few pieces via combinatorics | A flat shop ([[system-economy]]) covers acquisition |
+| Recipe *discovery* can carry curiosity | Recipes would just be an inventory tax |
+
+Crafting is the **convert** node of a **[[system-resource-loops]]** made
+*combinatorial*. If there's exactly one useful recipe per material, you don't have
+crafting — you have a conversion. Crafting earns its name when *choices between
+recipes* exist.
+
+## Variants
+
+| Variant | How the player learns | Depth from | Example |
+|---|---|---|---|
+| **Recipe list (lookup)** | Given the recipe book | Resource management | Minecraft (known), Stardew |
+| **Discovery** | Experiment to find combos | Curiosity, "what if" | Little Alchemy; Doodle God |
+| **Grid/shape** | Spatial arrangement matters | Pattern puzzles | Minecraft crafting grid |
+| **Modifier/affix** | Base + modifiers roll | Build optimization | Diablo runewords; PoE crafting |
+| **Emergent (systemic)** | Rules interact, no explicit recipes | Second-order surprise | Breath of the Wild elixirs; Noita |
+
+The **discovery** and **emergent** variants trade legibility for wonder — powerful,
+but they need a fallback so the player is never *stuck* (a hint, a partial reveal).
+
+## Tuning levers
+
+| Lever | What it controls | Healthy range / rule |
+|---|---|---|
+| **Recipe count** | Breadth of the space | Enough to explore; each recipe must *do* something distinct |
+| **Combinatorial fan-out** | Outputs per input set | High fan-out = deep from few pieces (the whole point) |
+| **Discovery vs lookup** | How recipes are learned | Discovery for wonder; lookup for planning games. Mixing: teach basics, hide the exotic |
+| **Ingredient scarcity** | Cost of a craft | Ties crafting to the economy — scarce inputs make recipes decisions |
+| **Legibility** | Can the player *plan*? | Show what a recipe needs before they commit ingredients |
+| **Dead-end density** | Useless recipes | Keep low — a discovered recipe that does nothing punishes curiosity |
+
+## How it wires to Hayao
+
+- **Recipes are pure data + pure logic.** A recipe is `{inputs, output}`; crafting
+  is a **pure function** over inventory state in `world.state`, invoked by an
+  **input action**. This makes the recipe space *machine-checkable*: it's the same
+  shape as a `Puzzle<State, Move>` — you can solver-search "is item X craftable
+  from starting materials?" the way the grid-puzzle solver proves reachability
+  (**[[FUN.md §1]]**).
+- **Prove reachability.** Assert every *intended* output is craftable from
+  obtainable inputs — a connectivity proof over the recipe graph, mirroring the
+  roguelike "all loot reachable" sweep (**[[FUN.md §10]]**). No orphan recipes.
+- **The crafting UI is chrome.** The recipe book / bench menu is `showScreen()`
+  DOM; inventory *counts* are sim state, the panel is `cosmetic` (CLAUDE.md
+  invariant 4, **[[FUN.md law 6]]**).
+- **Generate the recipe set as content.** Lean on `src/content/` to *generate*
+  balanced recipe trees and prove them reachable, rather than hand-authoring a
+  hundred recipes and hoping.
+
+## Fails when…
+
+- **Orphan recipes.** An output nothing reaches, or an ingredient nothing uses —
+  dead weight. Prove the graph connected.
+- **One true recipe.** If every craft has a single obvious answer, it's conversion
+  cosplaying as crafting. Add meaningful alternatives.
+- **Discovery with no floor.** Pure discovery + no hints = players stuck, guessing.
+  Always give a nudge before frustration.
+- **Illegible cost.** Committing ingredients before seeing the recipe wastes scarce
+  materials — feels like a trap.
+- **Inventory tax.** Crafting that's mandatory busywork (craft to progress, no
+  choice) — cut it or make it optional.
+
+## Verify
+
+- Recipe reachability as a connectivity/solver proof (every intended output
+  craftable): **[[FUN.md §10]]** (connectivity) and **[[FUN.md §1]]** (solver over
+  a `Puzzle`-shaped state).
+- Determinism: same inputs → same output, replay-hash identical: **[[FUN.md law 7]]**.
+- Ingredient economy stays in a pacing window: **[[FUN.md §14]]**.
+
+## Composes with
+
+- [[system-resource-loops]] — crafting is the combinatorial *convert* step.
+- [[system-economy]] — ingredients are currency; recipes are structured sinks.
+- [[system-build-diversity]] — modifier/affix crafting is a build engine.
+- [[system-collectibles]] — a recipe book is a set to complete.
+- [[system-tech-tree]] — research unlocks new recipes.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §1 (solver over pure state) · §10
+  (connectivity) — recipe reachability rides both.
+- `src/content/generate.ts` — generate & prove a recipe/level space instead of
+  hand-authoring it.
+- **[[anchor-factorio]]** — recipes as the production spine.

package/design/30-systems/difficulty-and-dda.md

@@ -0,0 +1,114 @@
+---
+id: system-difficulty-and-dda
+title: Difficulty & Dynamic Difficulty
+kind: system
+tags: [difficulty, dda, curve, spikes, breathers, ai-director, assist, ramp, pacing]
+summary: Difficulty curves that breathe — spikes and breathers, an AI director that authors pressure, and assist modes that never shame.
+use-when: You need to shape challenge over a session, react to a player's skill, or offer honest difficulty options.
+composes-with: [system-encounter-design, system-onboarding, system-accessibility, pattern-pacing-and-tension]
+anchors: [anchor-rimworld, anchor-celeste]
+verify-with: docs/FUN.md#8-tower-defense
+---
+
+# Difficulty & Dynamic Difficulty
+
+**What it is.** How hard the game is, *over time* and *per player*. Three tools:
+a **difficulty curve** (a designed sequence of spikes and breathers), a **director**
+(a system that spawns pressure in response to state), and **assist modes** (honest
+knobs that let anyone find their edge). The goal is the **flow channel** — challenge
+tracking skill, never far above or below ([[pattern-mastery-and-flow]]).
+
+**Player fantasy / why it's fun.** Being *tested at exactly your level*. A curve
+that breathes lets tension land — a boss hits harder after a quiet corridor. A
+director makes a run feel *authored to you*. Assist modes let the humane version of
+the fantasy exist (Celeste): the game meets you, it doesn't gate-keep you.
+
+## When to use / when NOT
+
+| Tool | Reach for it when | Don't when |
+|---|---|---|
+| **Authored curve** | linear/campaign content; you control order | fully procedural — shape the *generator's* band instead |
+| **Director (DDA)** | survival, colony sim, replayable runs; you want reactive pressure | tight puzzles — perfect information forbids hidden dials (§12) |
+| **Assist modes** | any single-player skill game | competitive PvP where fairness is symmetry |
+
+> **Two ditches.** Static difficulty leaves half your players bored and the other
+> half walled out. A *hidden* rubber-band that punishes doing well ("do better,
+> get punished") betrays trust the moment it's noticed. DDA must nudge, never lie.
+
+## Variants
+
+| Variant | How it decides | Feels like | Anchor |
+|---|---|---|---|
+| **Authored curve** | fixed schedule of encounters | a designed rollercoaster | most campaigns |
+| **Threat-budget director** | spends a rising budget on spawns | escalating siege | [[anchor-rimworld]]'s storyteller |
+| **Performance DDA** | reads hp/deaths/time, adjusts spawns | "the game read me" | Left-4-Dead-style |
+| **Player-chosen tiers** | difficulty menu | honest self-selection | Doom, most action games |
+| **Assist toggles** | per-axis mercy (speed, i-frames, skip) | "I set my own edge" | [[anchor-celeste]] assist mode |
+
+## Tuning levers
+
+| Lever | Effect | Watch for |
+|---|---|---|
+| **Spike/breather rhythm** | tension arc | monotone-rising = exhausting; flat = dull |
+| **Director budget slope** | how fast pressure grows | superlinear needed to outpace build growth (§6) |
+| **DDA sensitivity** | how sharply it reacts | too twitchy = visibly rubber-bandy |
+| **DDA bounds** | floor/ceiling on adjustment | unbounded = trivializes or walls |
+| **Assist granularity** | per-axis vs. one slider | one slider forces all-or-nothing |
+
+## How it wires to Hayao
+
+- **The director already exists.** `initDirector(waves)` +
+  `pollDirector(waves, state, world.time, world.rng)` (grep `docs/API.md`,
+  [`src/content/dsl.ts`](../../src/content/dsl.ts)) is a deterministic pressure
+  authorer: waves fire on sim time, weighted spawns roll through `world.rng`, and
+  catch-up after a restore never drops spawns. Keep `DirectorState` in
+  `world.state` so pressure is hashed and replayable.
+- **Performance DDA reads the probe.** The same numbers `world.probe()` exposes
+  (hp floor, time alive, deaths) are the DDA inputs — bounded, ordered, and part of
+  `world.hash()` so difficulty can't silently escape determinism.
+- **The curve is checkable.** `assertRamp(difficulty, opts)` / `rampIssues` (grep
+  `docs/API.md`) assert the *shape* — a designed ramp with breathers, not
+  monotonicity. Author the sequence, then prove it breathes.
+- **Assist modes are tuning.** Model them as declared `tuning:` knobs
+  ([`docs/STUDIO.md`](../../docs/STUDIO.md)); their resolved values live in
+  `world.hash()` via `world.tune(key)`, so an assisted run is still a first-class,
+  replayable artifact — not a second-class cheat path.
+
+## Fails when…
+
+- **Monotone difficulty.** Always-harder with no breather has no arc — tension
+  can't spike without a valley (FUN.md §8, [[pattern-pacing-and-tension]]).
+- **Visible rubber-band.** Players who notice they're punished for playing well
+  stop trying — the trust cost outweighs the smoothing.
+- **Unbounded DDA.** No floor/ceiling and the director either trivializes the game
+  or spirals it out of reach.
+- **Assist as shame.** Locking achievements or nagging on assist turns a humane
+  tool into a punishment. Assist is a *setting*, not a confession (Celeste).
+- **Sublinear survival pressure.** In hordes, linear spawn loses to multiplicative
+  build growth — the ramp must be superlinear (§6).
+
+## Verify
+
+- **Curve breathes:** `assertRamp`/`rampIssues` on the difficulty series — each
+  wave ≥ ~55% of prior, finale peaks ([FUN.md §8](../../docs/FUN.md#8-tower-defense)).
+- **Win-rate window, not a point:** a competent bot should land *inside* a band
+  (e.g. 11–19 of 20) — both edges break CI ([FUN.md §11](../../docs/FUN.md#11-roguelike-deckbuilder)).
+- **Null loses at every tier:** the do-nothing/undefended run fails on easy too
+  (FUN.md law 4).
+- **Determinism under DDA:** golden-hash a scripted run at each setting; tuning
+  values are in `world.hash()` (STUDIO knob-change semantics).
+
+## Composes with
+
+- [[system-encounter-design]] — the units a curve or director sequences.
+- [[system-onboarding]] — the first ten minutes are the gentlest slope; the curve starts here.
+- [[system-accessibility]] — assist modes are the accessible face of difficulty.
+- [[pattern-pacing-and-tension]] — spikes/breathers are pacing made mechanical.
+- [[pattern-mastery-and-flow]] — the flow channel is the target the curve tracks.
+
+## See also
+
+- [`docs/FUN.md` §6/§8/§11](../../docs/FUN.md) — superlinear pressure, breathing waves, win-rate windows.
+- [`src/content/dsl.ts`](../../src/content/dsl.ts) — the director primitive.
+- [[anchor-rimworld]] — the AI storyteller as difficulty *and* narrative.
+- [[anchor-celeste]] — assist mode as the humane difficulty floor.