hayao 0.4.0 → 0.4.2

package/design/20-genres/tower-defense.md

@@ -0,0 +1,120 @@
+---
+id: genre-tower-defense
+title: Tower Defense
+kind: genre
+tags: [tower-defense, td, waves, towers, counters, lanes, build-order]
+summary: Build decisions that matter — near-hard counters, range-ring geometry, and wave curves that breathe.
+use-when: You want a spatial build-and-defend loop where placement and counter-picks decide the run, not tower count.
+composes-with: [system-counter-systems, system-enemy-archetypes, system-difficulty-and-dda, system-economy, system-encounter-design]
+anchors: [anchor-into-the-breach]
+verify-with: docs/FUN.md#8--tower-defense
+---
+
+# Tower Defense
+
+**What it is.** Enemies walk a path; you spend a shared economy building
+**towers** that fire on them. The whole game is *where you place what* — a
+spatial optimisation puzzle that plays out in real time across escalating waves.
+
+**Player fantasy / why it's fun.** *"I read the wave, I built the counter, I
+watched my machine hold the line."* The satisfaction is a plan surviving contact
+— then the finale wave that almost breaks it and doesn't.
+
+## Pillars
+
+1. **Counters must bite.** A counter is near-*hard*, not a soft resist. Soft
+   resists get erased by tower-count scaling — if stacking one tower beats
+   everything, there are no build decisions.
+2. **Coverage is geometry.** range × distance-to-lane = the fire-window chord. A
+   tower's worth is *how long it can shoot each enemy*. The **range ring is the
+   genre's most important UI**.
+3. **Waves breathe.** Pressure then relief. Runner waves are breaks; the curve
+   ramps in envelope, not monotone HP. A wall of ever-bigger numbers is a
+   spreadsheet, not tension.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Place/upgrade a tower; watch its ring cover the lane; a leaker slips and you patch the gap. |
+| **Encounter** | A wave: read its archetype mix → the economy you saved buys the counter → it holds or leaks. |
+| **Session** | A map, ~10 waves: opening eco vs defence tension, a midwave spike, a finale that peaks. |
+| **Meta** | Unlock towers, maps, difficulty tiers; carry a build-order intuition between runs. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-counter-systems]] | The duel matrix. Each enemy archetype has a near-hard answer; picking it is the decision. |
+| [[system-enemy-archetypes]] | The alphabet a wave is spelled from — fast/armored/flying/swarm/shielded. |
+| [[system-difficulty-and-dda]] | The wave curve: ramp, breathers, finale peak — gate on shape, not raw HP. |
+| [[system-economy]] | The spend that makes placement a *choice* — build now vs save for the counter. |
+| [[system-encounter-design]] | Composing archetypes into a wave that demands a mixed build. |
+
+## Content & difficulty model
+
+- **Wave = an archetype recipe.** Author waves as mixes (8 fast + 2 armored),
+  not HP totals. Difficulty is the *mix* forcing a broader build, plus tighter
+  timing.
+- **Gate the curve on shape.** Assert "each wave ≥ 55% of the previous, finale
+  peaks" — not monotone HP. Runner waves are intentional dips.
+- **The bare-lane baseline.** A lane with no towers must fall early (null-strategy
+  proof, FUN.md law 4). A "threat" a do-nothing survives isn't a threat.
+- **Mixed beats mono.** The intended mixed build survives 10/10; a mono build on
+  a *bigger* budget fails. That gap is the proof the counters matter.
+
+## Signature-mechanic seeds
+
+- **TD but you also walk the path** *(perspective)* — a hero unit you steer
+  between builds; placement and positioning share your attention.
+- **TD but the towers are the enemies' path** *(mechanic-swap)* — every tower
+  you place reshapes the maze; maze-building becomes the core decision.
+- **TD but the wave is a deck you drafted** *(structure)* — you *build the
+  attack* for a rival lane and defend theirs. Pairs [[system-build-diversity]].
+- **TD but ammo is a shared resource that runs dry** *(constraint)* — towers
+  compete for a finite magazine; over-building starves the finale.
+- **TD but towers age and crack** *(theme + tonal)* — Kentō stonework that
+  weathers each wave; repair vs expand becomes the economy tension.
+
+The strongest TD twist bends the *decision*, not the theme: change what the
+player builds against (a rival's drafted wave), what the towers cost (a shared
+magazine), or where the path goes (maze-building). See [[process-the-twist]].
+
+## Common pitfalls
+
+- **Soft counters.** A 20% resist vanishes under stacking. Make the counter
+  near-hard or the build collapses to "spam the best tower."
+- **Monotone HP ramp.** Waves that only grow read as a slog. Breathers and a
+  peaked finale are the pacing.
+- **Invisible range.** Without a visible ring, placement is guesswork and
+  coverage-as-geometry is illegible.
+- **Economy with no tension.** If you can always afford everything, placement
+  isn't a decision — starve the player enough to force priorities.
+- **Global upgrades over placement.** If flat "+damage" buttons beat clever
+  positioning, coverage-as-geometry is dead. Keep the map the puzzle.
+
+## Anchors
+
+- [[anchor-into-the-breach]] — perfect-information spatial threat-reading; TD is
+  the real-time cousin. Steal its "read the telegraph, answer with placement."
+- [[system-counter-systems]]'s duel matrix is the balance skeleton — treat each
+  tower↔archetype pair as a proven duel.
+
+## Verify
+
+Prove it in **[FUN.md §8 · Tower defense](../../docs/FUN.md#8--tower-defense)**:
+mixed build survives 10/10, a bigger-budget mono build fails, the bare lane
+falls early, and counter duels resolve from both sides.
+
+## Composes with
+
+- [[system-counter-systems]] — the near-hard duel matrix the whole game rests on.
+- [[system-enemy-archetypes]] — the archetype alphabet waves are written in.
+- [[system-difficulty-and-dda]] — the breathing wave curve.
+
+## See also
+
+- [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo) — lane/path and
+  flow-field wiring for enemy movement.
+- [`examples/sokoban`](../../examples/sokoban) — the logic/view split reference:
+  keep wave resolution pure, the range rings and hit sparks cosmetic (law 6).

package/design/30-systems/README.md

@@ -0,0 +1,69 @@
+# 30-systems/ — The Modular Systems Library
+
+The **parts bin**. Where [`20-genres/`](../20-genres/) gives you a whole
+skeleton, this section gives you the *organs* — progression, economy, combat,
+factions, AI, rewards — each a self-contained module you bolt onto a design and
+tune. The [COMPOSE step](../README.md) of the pipeline lives here: pick the genre
+template, then pull the `system-*` modules it needs and wire them together. Every
+module says **what it is · when to use / when NOT · variants · tuning levers ·
+how it wires to Hayao · fails when… · verify** — so you compose the known, then
+bend it, and hand off proofs to [`docs/FUN.md`](../../docs/FUN.md).
+
+Each entry links `verify-with` into FUN/JUICE/VERIFICATION rather than restating
+the proof. Cross-link with `[[system-id]]`; follow `composes-with`.
+
+## Progression · economy · rewards
+
+| id | title | summary |
+|---|---|---|
+| [[system-progression]] | Progression | XP / levels / the power curve; pacing power gain, vertical vs horizontal |
+| [[system-skill-trees]] | Skill Trees | Branching unlocks; builds; meaningful exclusivity; respec as grace |
+| [[system-meta-progression]] | Meta-Progression | Roguelite persistent unlocks; power-creep vs options; "always earn something" |
+| [[system-mastery-curve]] | Mastery Curve | Learnable depth; skill ceiling; easy-to-learn-hard-to-master as a mechanism |
+| [[system-economy]] | Economy | Faucets & sinks; currencies; inflation control; the pacing window |
+| [[system-resource-loops]] | Resource Loops | Gather→convert→spend cycles; bottlenecks as pacing |
+| [[system-crafting]] | Crafting | Recipes; combinatorial depth; discovery vs lookup |
+| [[system-tech-tree]] | Tech Tree | Research gating; branch exclusivity; the ramp of options |
+| [[system-reward-schedules]] | Reward Schedules | Variable-ratio drops/chests/loot; ethical compulsion, dark patterns to refuse |
+| [[system-collectibles]] | Collectibles | Sets, completion, cosmetics; optional goals with pull |
+
+## Combat · factions
+
+| id | title | summary |
+|---|---|---|
+| [[system-combat-model]] | Combat Model | Damage, resolution, timing; the shape of a hit |
+| [[system-telegraphs]] | Telegraphs | Tells, windups, readable threat; reaction windows |
+| [[system-status-effects]] | Status Effects | DoT / buffs / debuffs; stacking rules; build interaction |
+| [[system-counter-systems]] | Counter Systems | Rock-paper-scissors; near-hard counters; the duel matrix |
+| [[system-faction-asymmetry]] | Faction Asymmetry | Asymmetric identities that balance; "different but fair" |
+| [[system-unit-rosters]] | Unit Rosters | Unit roles, tiers, diversity; a legible roster |
+| [[system-boss-design]] | Boss Design | Phases, telegraphs, spectacle; the set-piece fight |
+| [[system-build-diversity]] | Build Diversity | Weapons / loadouts / synergies; many viable strategies |
+| [[system-grace]] | Grace | Coyote / i-frames / buffer / mercy as a system |
+| [[system-enemy-ai]] | Enemy AI | Behavior, aggro / threat, steering; readable, beatable minds |
+| [[system-enemy-archetypes]] | Enemy Archetypes | Tank / skirmisher / artillery / swarm / support; the enemy alphabet |
+| [[system-encounter-design]] | Encounter Design | Composing archetypes into fights; pressure & pockets |
+
+## Structure · AI · procgen · meta · social
+
+| id | title | summary |
+|---|---|---|
+| [[system-difficulty-and-dda]] | Difficulty & DDA | Difficulty curves; spikes / breathers; dynamic difficulty; assist |
+| [[system-onboarding]] | Onboarding | Tutorialization; teach-by-doing; the first ten minutes |
+| [[system-accessibility]] | Accessibility | Assist modes; remap; colour / contrast; readability floors |
+| [[system-procgen-design]] | Procgen Design | Runs, seeds, variance as content; controlled randomness |
+| [[system-session-structure]] | Session Structure | Run / campaign / level / world; session length & shape |
+| [[system-save-and-checkpoint]] | Save & Checkpoint | Save, checkpoint, retry; respecting the player's time |
+| [[system-emergent-systems]] | Emergent Systems | Nemesis-style memory, relationships, reputation; systemic story |
+| [[system-coop-and-competition]] | Coop & Competition | Coop / PvP hooks; asymmetric coop; interdependence & rivalry |
+
+## Generate the content; don't hand-author it
+
+Most of these systems produce *content* — levels, recipes, unlock curves, drop
+tables. The Hayao way is to **generate and prove** it, not to hand-write forty
+balanced rooms and hope. Point your progression/economy/loop pacing at
+[`src/content/`](../../src/content/) — `generateLevels` (solver-verified,
+in-band levels), `composeCampaign` (acts that ramp), `assertRamp`/`rampIssues`
+(the curve has no deserts, no walls). The 42-level generated reference is
+[`examples/lanternfold/`](../../examples/lanternfold/). Design the *shape* here;
+let the generator fill it and the verify suite prove it.

package/design/30-systems/accessibility.md

@@ -0,0 +1,110 @@
+---
+id: system-accessibility
+title: Accessibility
+kind: system
+tags: [accessibility, assist, remap, colorblind, contrast, readability, a11y, salience]
+summary: Assist modes, input remap, and colour/contrast that clear a readability floor — more players reach the game, none are shamed for it.
+use-when: You want the game playable by more people — different hands, eyes, and skill levels — without a separate "easy" ghetto.
+composes-with: [system-difficulty-and-dda, pattern-readability, world-aesthetic-direction, system-onboarding]
+anchors: [anchor-celeste]
+verify-with: docs/JUDGE.md
+---
+
+# Accessibility
+
+**What it is.** The set of choices that let **more people play the same game**:
+assist modes (speed, invulnerability, skip), full **input remap**, and a
+**colour/contrast** floor so threats and the avatar read for colour-blind and
+low-vision players. Accessibility is not a difficulty setting bolted on — it's a
+**readability and control floor** the whole design stands on.
+
+**Player fantasy / why it's fun.** Everyone gets the *actual* fantasy, tuned to
+their body. Celeste's assist mode doesn't make a lesser game — it makes the *same*
+game reachable. The pull is dignity: the game meets the player where they are.
+
+## When to use / when NOT
+
+| Use it when | Non-negotiable when |
+|---|---|
+| Any single-player game | *Colour/contrast is never optional* — it's a floor, always on |
+| Skill games with a high ceiling | Remap: any keyboard/gamepad game — bodies differ |
+| Games leaning on colour to signal | Assist modes: any game where "too hard" loses players you could keep |
+
+> **Accessibility is a floor, not a mode.** Contrast, remap, and salience aren't
+> a menu you *could* add — they're the baseline every player relies on, including
+> the ones who never open the options screen. Build the floor first; the toggles
+> are the ramp above it.
+
+## The axes
+
+| Axis | What it covers | Cheapest win |
+|---|---|---|
+| **Motor** | remap, hold-vs-toggle, reduced APM, larger targets | full key/button remap |
+| **Visual** | contrast, colour-blind-safe palette, non-colour cues, text size | shape/icon *plus* colour, never colour alone |
+| **Cognitive** | clear goals, no time-pressure option, readable telegraphs | slower/optional timers |
+| **Difficulty** | assist toggles (speed %, i-frames, skip) | per-axis, not one slider |
+
+## Tuning levers
+
+| Lever | Effect | Watch for |
+|---|---|---|
+| **Contrast ratio** (avatar vs. field, text vs. bg) | legibility floor | measure it — don't eyeball it |
+| **Redundant cues** | colour + shape + motion for each signal | colour-only = invisible to ~8% of players |
+| **Remap coverage** | which actions are rebindable | a hard-coded key is an inaccessible wall |
+| **Assist granularity** | per-axis toggles vs. one dial | one slider forces all-or-nothing |
+
+## How it wires to Hayao
+
+- **Contrast is measurable.** `contrastRatio(a, b)` (grep `docs/API.md`) gives the
+  WCAG-style ratio for any two hex colours — gate avatar-vs-field and text-vs-bg
+  against a threshold. The Kentō palette is *already* AA-gated
+  ([[world-aesthetic-direction]], `npm run palette`), so build on it.
+- **Redundant cues ride readability.** The `src/verify/gates.ts` readability gate
+  checks the avatar out-contrasts its surroundings and threats telegraph — that
+  *is* the visual-accessibility floor made checkable. Pair colour with the
+  telegraph shape so the signal survives colour-blindness ([[pattern-readability]],
+  JUDGE).
+- **Remap & assist are declared tuning.** Model assist axes as `tuning:` knobs
+  ([`docs/STUDIO.md`](../../docs/STUDIO.md)); resolved via `world.tune(key)`, they
+  stay in `world.hash()`, so an assisted or remapped run is still a first-class,
+  replayable artifact — never a cheat path.
+- **Input is action-based.** Because UI intent flows through input *actions*
+  (CONVENTIONS), remapping a key is a lookup change, not a sim change — the action
+  log and determinism are untouched.
+
+## Fails when…
+
+- **Colour carries a signal alone.** Red-vs-green danger with no shape cue is
+  invisible to a large minority — always add a second channel.
+- **Hard-coded controls.** One unbindable key excludes anyone whose hands don't fit
+  it.
+- **Assist as a lesser mode.** Withholding content/achievements on assist turns a
+  humane tool into a punishment (the opposite of Celeste's stance).
+- **Contrast by vibe.** "Looks fine to me" fails the players it's for — measure
+  with `contrastRatio`.
+- **Text-size afterthought.** Tiny fixed HUD text walls out low-vision players.
+
+## Verify
+
+- **Contrast gate:** `contrastRatio(avatar, field)` and text-vs-bg pass a threshold
+  (build on the AA-gated Kentō palette, `npm run palette`).
+- **Readability floor:** avatar out-contrasts surroundings, threats telegraph —
+  [`src/verify/gates.ts`](../../src/verify/gates.ts) + [JUDGE.md](../../docs/JUDGE.md)
+  (the headless SVG look).
+- **Assist stays deterministic:** golden-hash a run per assist setting; tuning is
+  in `world.hash()` (STUDIO knob semantics).
+- **Remap covers every action:** lint that no gameplay action is bound to an
+  unremappable key.
+
+## Composes with
+
+- [[system-difficulty-and-dda]] — assist modes are difficulty's accessible face.
+- [[pattern-readability]] — the salience floor accessibility depends on.
+- [[world-aesthetic-direction]] — the AA-gated Kentō palette is your contrast head-start.
+- [[system-onboarding]] — a readable first ten minutes is an accessibility win.
+
+## See also
+
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) — the readability/look bar, judged headlessly.
+- [`src/verify/gates.ts`](../../src/verify/gates.ts) — the readability feel gate.
+- [[anchor-celeste]] — assist mode as the field's humane benchmark.

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

@@ -0,0 +1,126 @@
+---
+id: system-boss-design
+title: Boss Design — the set-piece fight
+kind: system
+tags: [boss, phases, telegraph, spectacle, set-piece, mercy, encounter]
+summary: The multi-phase set-piece — a fight that teaches, escalates, and telegraphs, with mercy on every phase transition so a death is fair, not cheap.
+use-when: You need a climactic fight — a boss, an elite, a chapter finale — that's a spectacle and a skill test, not just a big HP bar.
+composes-with: [system-telegraphs, system-combat-model, system-encounter-design, system-grace, system-enemy-ai]
+anchors: [anchor-hades, anchor-into-the-breach]
+verify-with: docs/FUN.md#7-bullet-hell
+---
+
+# Boss Design — the set-piece fight
+
+**What it is.** The **climax**: a single opponent (or arena) built as a multi-phase
+performance — it teaches a pattern, escalates it, and pays off mastery. A boss is
+[[system-combat-model]] turned up to spectacle, held fair by heavy
+[[system-telegraphs]] and structural [[system-grace]].
+
+**Player fantasy / why it's fun.** The mountain. A boss is a wall you learn to
+climb — first attempt you're overwhelmed, tenth attempt you dance through it. The
+fun is the *arc of competence*, from panic to mastery, capped by a moment of
+spectacle you earned.
+
+## When to use / when NOT
+
+| Use a boss when… | Skip when… |
+|---|---|
+| You want a skill/knowledge checkpoint | Pacing needs a valley, not a peak |
+| A pillar deserves a climactic test | The genre is flat by design (idle, cozy) |
+| The player has the full toolkit to show off | Mechanics aren't taught yet (too early) |
+
+A boss is a *test* — it should demand the mechanics the game has already taught,
+not introduce them. Front-load teaching in encounters ([[system-encounter-design]]);
+let the boss examine.
+
+## Phase structure — the arc
+
+| Phase | Job | Design note |
+|---|---|---|
+| **Read** | teach the boss's vocabulary | slow, legible telegraphs; low punish |
+| **Pressure** | escalate — faster, layered patterns | now the taught reads matter |
+| **Desperation** | the spike; new wrinkle or tempo | the memorable peak; keep it *fair* |
+| **(optional) Puzzle** | a gimmick that gates damage | reflect-the-shot, break-the-armor |
+
+Each phase should re-use the previous phase's vocabulary plus one new element —
+escalation by *addition*, so the player is never asked to relearn from scratch.
+
+## The mercy law — FUN.md law 5
+
+> **Phase transitions are a grace point, not a gotcha.** FUN.md §7: mercy clears on
+> death and phase transitions are *structural*, not polish — without them deaths
+> cascade (you die to a bullet that spawned during the cutscene).
+
+Concretely, on every transition:
+
+- **Clear active threats** — no leftover bullet/hitbox from the last phase kills you
+  during the transition.
+- **Buffer input across the pause.** Any freeze the transition injects must re-emit
+  the player's intent (FUN.md law 5; §4 hit-stop rule). A dropped dash on a phase
+  change is the cheapest, worst death in the game.
+- **Checkpoint the phase** if the fight is long — respect the player's time
+  ([[pattern-anti-frustration]]); losing phase 3 shouldn't replay phase 1 for the
+  twentieth time.
+
+## Tuning levers
+
+| Lever | Does | Healthy range |
+|---|---|---|
+| **Phase HP split** | pacing across the fight | roughly even; a short desperation phase reads as a sprint |
+| **Telegraph window** | reactability per attack | ≥ the §4 floor; longer for the big committal moves |
+| **Punish window** | your damage opening after a whiff | real but bounded — the fight has rhythm |
+| **Pattern density** | simultaneous threats | coherent, not a wall (§7 — density that *reads*) |
+| **Mercy window** | i-frames / clears on transition | specced in frames, proven edge-in/edge-out |
+| **Attempt cost** | retry friction | low — instant retry keeps momentum (FUN.md law 5) |
+
+## How it wires to Hayao
+
+- **Every attack telegraphs.** Feed each threat's timeline to
+  `telegraphIssues(timeline, minFrames)` (in `@hayao`) — a boss move that goes live
+  cold is an unfair death (FUN.md §4/§7). See [[system-telegraphs]].
+- **The desperation phase is a dodge-bot proof.** FUN.md §7: a greedy lookahead
+  dodger must clear the pattern deathless — if the bot dies, humans die unfairly.
+  Pure state + `world.rng` makes that bot free (law 7).
+- **Mercy windows are gate-proven.** `graceWindowIssues(label, windowFrames, accepts)`
+  frame-pumps the transition i-frames and asserts accepted-inside / refused-outside
+  to the exact frame (FUN.md law 5).
+- **Spectacle is cosmetic.** Shake, particles, hit-stop are view (`Shaker`,
+  `Particles`, JUICE Part 1) — bounded by `feedbackIssues` (death shake ≈ 0.5,
+  hit-stop ≤ 12 frames), out of `world.hash()`.
+
+## Fails when…
+
+- **HP sponge.** No phases, no new vocabulary — just a long health bar. Tedium, not
+  a climax.
+- **Untelegraphed spike.** The desperation phase adds an attack with no tell —
+  `telegraphIssues` fails; it should.
+- **Transition death.** A leftover bullet or a dropped input during the phase change
+  kills you (the exact §7 cascade the mercy law prevents).
+- **Teaches in the exam.** Introduces a mechanic the game never taught — the boss is
+  a filter, not a lesson.
+- **Retry friction.** Long walk-back or slow retry breaks the learn-by-dying loop
+  (FUN.md law 5).
+
+## Verify
+
+- **[FUN.md §7](../../docs/FUN.md)** — dodge bot clears each phase deathless; peak-bullet
+  count asserted; mercy clears on death and transition.
+- **[FUN.md §4](../../docs/FUN.md)** — every attack telegraphed (`telegraphIssues`).
+- **[FUN.md law 5](../../docs/FUN.md)** — transition i-frames proven edge-in/edge-out
+  (`graceWindowIssues`).
+- Feel: death/boss-hit shake and hit-stop inside envelope (`feedbackIssues`) →
+  **[JUICE.md Part 3](../../docs/JUICE.md)**, **[VERIFICATION Channel 4](../../docs/VERIFICATION.md)**.
+
+## Composes with
+
+- [[system-telegraphs]] — a boss is a telegraph showcase; readability is the whole test.
+- [[system-grace]] — mercy on transitions, i-frames, instant retry are structural here.
+- [[system-encounter-design]] — the boss examines what the encounters taught.
+- [[system-combat-model]] — the boss is your combat model at maximum expression.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §7 (mercy + dodge bot), §4 (telegraphs), law 5 (grace).
+- [`docs/JUICE.md`](../../docs/JUICE.md) — spectacle within the feedback envelope.
+- [[anchor-hades]] — bosses as repeatable, learnable set-pieces across runs.

package/design/30-systems/build-diversity.md

@@ -0,0 +1,120 @@
+---
+id: system-build-diversity
+title: Build Diversity — many viable strategies
+kind: system
+tags: [builds, loadouts, synergy, diversity, dominant-strategy, viability, balance]
+summary: Many strategies that all win — weapons, loadouts, and synergies tuned so the fun is choosing a build, not solving for the one correct build.
+use-when: The player assembles a strategy from parts (weapons, cards, relics, skills) and you need more than one path to be worth taking.
+composes-with: [system-status-effects, system-counter-systems, system-skill-trees, system-reward-schedules, system-meta-progression]
+anchors: [anchor-slay-the-spire, anchor-vampire-survivors, anchor-hades]
+verify-with: docs/FUN.md#11-roguelike-deckbuilder
+---
+
+# Build Diversity — many viable strategies
+
+**What it is.** The discipline of keeping **many builds viable** — so a player
+assembling weapons, cards, relics, or skills faces *choices*, not a solved optimum.
+The enemy of build diversity is the **dominant strategy**: the one loadout that
+outperforms all others, collapsing the build screen into a lookup.
+
+**Player fantasy / why it's fun.** *Expression.* "This is *my* run — poison stacks,
+or crit-and-glass, or turtle-and-scale." Build diversity is what makes a roguelite
+replayable: the mechanics are fixed, but the *strategy you author* is new each time.
+
+## When to use / when NOT
+
+| Use it when… | Less critical when… |
+|---|---|
+| The player composes from many parts | There's one fixed kit |
+| Replayability comes from strategy variety | Content variety carries replay instead |
+| Synergies/[[system-status-effects]] exist | The game is short/linear |
+
+## Variants — where the diversity lives
+
+| Source | Diversity from | Anchor |
+|---|---|---|
+| **Loadout** | pick a weapon/kit, whole run reorganizes | [[anchor-hades]] weapons/aspects |
+| **Synergy engine** | parts combo multiplicatively | [[anchor-slay-the-spire]] archetypes; [[anchor-balatro]] jokers |
+| **Passive stacking** | choices compound into a style | [[anchor-vampire-survivors]] evolutions |
+| **Skill tree** | branch exclusivity forces identity | [[system-skill-trees]] |
+| **Draft** | reward-of-N shapes the deck over time | Slay the Spire card-reward-of-3 + skip |
+
+## The anti-dominant-strategy discipline
+
+A build system is healthy when **several distinct strategies clear the game at a
+similar rate**. Four levers keep it that way:
+
+1. **Multiple engines, none strictly best.** Poison, crit, block-scaling, summons —
+   each should win in the hands of a pilot who commits. If one wins with *no* commit,
+   it's dominant. Cut or nerf it.
+2. **Near-hard counters keep any single engine honest.** A build with no weakness is
+   a dominant build; give each strategy a matchup it dreads
+   ([[system-counter-systems]]). Diversity and counters are the same problem.
+3. **Meaningful exclusivity.** If you can take *everything*, there's no build — just
+   a checklist. Force trades: branch exclusivity ([[system-skill-trees]]), deck size,
+   slot limits, opportunity cost.
+4. **Reward the synergy, not the pile.** Diversity comes from parts that *interact*
+   ([[system-status-effects]] combos), not from a longer list of flat +damage. Flat
+   stacking always converges on one optimum.
+
+> **The proof is the delta, not the roster.** A big list of weapons proves nothing.
+> What proves diversity is: *pilot build A, it wins; pilot build B, it wins; pilot
+> the null / flat-stack build, it loses.* (FUN.md law 2, §11 draft-delta.)
+
+## Tuning levers
+
+| Lever | Does | Healthy range |
+|---|---|---|
+| **Win-rate spread across builds** | how even the top strategies are | tight — no build ≫ the field |
+| **Synergy multiplier** | payoff of a combo'd build | big enough to reward commitment, not so big it's mandatory |
+| **Exclusivity** | how much you must give up to specialize | real trades; you can't have it all |
+| **Floor build power** | how the "no plan" run does | it *loses* — the null baseline (law 2) |
+| **Ramp/scaling** | how builds keep pace with difficulty | multiplicative build vs superlinear threat (§6) |
+
+## How it wires to Hayao
+
+- **Pilot bots per build.** Pure state + `world.rng` (FUN.md law 7) lets you script a
+  greedy pilot for each archetype, run it, and compare win-rates. Assert the intended
+  builds land inside a win window and the null build falls below it (FUN.md §11).
+- **The draft delta is the direct test.** Same pilot, drafting *off*, must lose much
+  more (Slay the Spire's 17→9). That single assertion catches "the build doesn't
+  matter" and "one build dominates" at once.
+- **Synergies are pure status/state** — no special API; it's your data (grep
+  [`docs/API.md`](../../docs/API.md)). Reward drops via `weightedPick`/`pickEntry`
+  through `world.rng` keep the offer fair and replayable ([[system-reward-schedules]]).
+- Reference: [[anchor-slay-the-spire]] DNA (draft-of-3 + skip, archetype engines).
+
+## Fails when…
+
+- **A dominant strategy.** One build ≫ the field; every run converges on it, the
+  build screen is a lookup. The single most common diversity failure.
+- **Flat stacking.** +damage on +damage always has one optimum; no interaction, no
+  identity ([[pattern-emergence]] is absent).
+- **No exclusivity.** You take everything → there's no build, just accumulation.
+- **Trap options.** Choices that are *always* wrong aren't diversity — they're
+  padding. Every offered part should win *somewhere*.
+- **Diversity that doesn't survive scaling.** Builds that all work at easy but only
+  one keeps pace with the ramp (§6) — that's a dominant build in slow motion.
+
+## Verify
+
+- **[FUN.md §11](../../docs/FUN.md)** — greedy pilot per build in the win window;
+  never-draft/null build below it; the draft delta.
+- **[FUN.md law 2](../../docs/FUN.md)** — each viable build beats the null build by a margin.
+- **[FUN.md §6](../../docs/FUN.md)** — builds keep pace with a superlinear ramp (for
+  horde/survivor builds).
+- Determinism: golden hash of a scripted run per build.
+
+## Composes with
+
+- [[system-status-effects]] — the interacting parts that make synergy engines.
+- [[system-counter-systems]] — near-hard counters keep any single build honest.
+- [[system-skill-trees]] — branch exclusivity is a primary diversity source.
+- [[system-reward-schedules]] — how build parts are offered (draft-of-N, drops).
+- [[system-meta-progression]] — persistent unlocks widen the build space over time.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §11 (draft-delta), §6 (build-vs-tide), law 2 (skill delta).
+- [[anchor-slay-the-spire]], [[anchor-balatro]] — synergy engines that stay diverse.
+- [[pattern-emergence]] — diversity comes from interacting parts, not longer lists.

package/design/30-systems/collectibles.md

@@ -0,0 +1,108 @@
+---
+id: system-collectibles
+title: Collectibles — Sets, Completion & Optional Pull
+kind: system
+tags: [collectibles, sets, completion, cosmetics, optional-goals, 100-percent, checklist]
+summary: Optional goals that pull without shoving — sets to complete, cosmetics to earn; the compulsion of the almost-full grid, kept honest.
+use-when: You want optional content that rewards thoroughness and gives self-directed players a goal, without gating the main game behind it.
+composes-with: [system-reward-schedules, system-meta-progression, system-economy, system-mastery-curve, system-collectibles]
+anchors: [anchor-stardew-valley, anchor-dead-cells, anchor-vampire-survivors]
+verify-with: docs/FUN.md#15-farminglife-sim
+---
+
+# Collectibles — Sets, Completion & Optional Pull
+
+**What it is.** **Optional goals with pull.** Things to find, fill, and complete —
+a bestiary, a museum, a costume rack, a map's every corner. Collectibles give
+self-directed players a *reason to keep going* after the critical path ends,
+without making that content mandatory.
+
+**Player fantasy / why it's fun.** "Just one more, and the set's complete." The
+almost-full grid is a magnet; the empty slot is an itch. The pull is *closure* —
+the collector's satisfaction of a thing made whole.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| You want optional long-tail goals for completionists | It would pad a tight, focused game with busywork |
+| Exploration/thoroughness deserves a reward channel | The reward is required progress (then it's not optional) |
+| Cosmetics give a low-power, high-pull earn | Everything must matter mechanically |
+
+The discipline: collectibles are **optional**. The moment a set gates *required*
+power or the ending, it stops being a pull and becomes a tax. Keep the rewards
+*expressive* (cosmetics, lore, bragging rights) or *modest* (small bonuses) —
+never the only path to core power.
+
+## Variants
+
+| Variant | The pull is | Reward | Example |
+|---|---|---|---|
+| **Sets to complete** | Closure of a grid | Completion bonus / status | Bestiary, card album, museum |
+| **Cosmetics** | Expression, status | Looks, zero power | Skins, dyes, titles |
+| **Map completion** | Thoroughness | Reveal, %, secret | "100% map" ; hidden rooms |
+| **Cumulative unlocks** | Milestone counting | New content at N | "Kill 100 → unlock weapon" ([[system-meta-progression]]) |
+| **Lore/knowledge** | Curiosity | Story, world depth | Codex entries; audio logs ([[world-narrative-delivery]]) |
+| **Living dex / catch-em-all** | The complete roster | Prestige, function | Pokédex; VS character unlocks |
+
+## Tuning levers
+
+| Lever | What it controls | Healthy range / rule |
+|---|---|---|
+| **Set size** | Effort to complete | Big enough to be a journey, small enough to finish. Subdivide huge sets |
+| **Progress visibility** | The itch | *Show the empty slots* — the grid with gaps IS the pull |
+| **Acquisition clarity** | Fair vs guessy | The player should know *how* to get a missing one (or where to look) |
+| **Reward weight** | Power vs cosmetic | Keep low-power / expressive; optional means optional |
+| **Completion payoff** | The reason to finish | Give the 100% a *real* moment — a costume, a title, a secret |
+| **Missable density** | Anxiety | Minimise permanently-missable items, or players stress-play |
+
+## How it wires to Hayao
+
+- **Collection is state; the grid is chrome.** Owned/seen flags live in
+  `world.state` (or the meta slice via `SaveManager` for cross-run dexes); the
+  collection *screen* is `showScreen()` DOM, `cosmetic` where it renders in-world
+  (CLAUDE.md invariant 4, **[[FUN.md law 6]]**).
+- **Prove completability.** Assert every collectible is *reachable/obtainable* —
+  no item stranded behind a cut path or an impossible drop. This is the same
+  connectivity sweep the roguelike runs on loot (**[[FUN.md §10]]**), and it
+  catches the cruelest bug: a 99%-completable set.
+- **Show the player-critical number.** "3 of 12 found", "2 nights left to catch it"
+  — surface it, the way farming surfaces nights-in-season (**[[FUN.md §15]]**).
+  Knowledge the completionist needs, made visible.
+- **Persist across runs** with `SaveManager` + `SAVE_FORMAT_VERSION` for meta
+  dexes; the collection round-trips and hashes.
+
+## Fails when…
+
+- **99% completable.** One item unreachable (a cut spawn, a bugged drop) poisons the
+  whole set. The reachability sweep is non-negotiable.
+- **Mandatory sets.** A collectible gating the ending or core power isn't optional —
+  it's a chore with extra steps.
+- **Invisible progress.** No visible grid, no "N of M" — the pull evaporates.
+- **Missable minefield.** Many permanently-missable items → anxious, guide-dependent
+  play. Minimise or make everything re-obtainable.
+- **Hollow 100%.** Completing the set gives nothing — the payoff must *land*.
+
+## Verify
+
+- Every collectible reachable/obtainable — connectivity sweep across seeds:
+  **[[FUN.md §10]]**.
+- Surface the completion number (found/total, time-left): **[[FUN.md §15]]**.
+- Collection state persists & hashes (save round-trip): **[[FUN.md law 7]]**.
+- The main game clears without completing any set (optional-means-optional):
+  **[[FUN.md law 4]]**.
+
+## Composes with
+
+- [[system-reward-schedules]] — variable-ratio drops feed set completion.
+- [[system-meta-progression]] — cross-run dexes and cosmetic unlocks.
+- [[system-economy]] — cosmetics as a currency sink with no power creep.
+- [[system-mastery-curve]] — hard-to-get collectibles reward skill, not just time.
+- [[world-narrative-delivery]] — lore collectibles deliver story with little text.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §10 (reachability) · §15 (surfaced number) —
+  the collectible proofs.
+- **[[anchor-stardew-valley]]** (museum/bundles) · **[[anchor-vampire-survivors]]**
+  (character unlock roster).