hayao 0.4.0 → 0.4.2

package/design/10-anchors/vampire-survivors.md

@@ -0,0 +1,122 @@
+---
+id: anchor-vampire-survivors
+title: Vampire Survivors
+kind: anchor
+tags: [horde-survival, auto-attack, build-growth, rising-tide, minimal-input, power-fantasy]
+summary: One-stick horde survival where you only move — weapons fire themselves — and the whole game is your multiplying build racing an escalating swarm.
+use-when: Designing a low-input game whose fun is watching a snowballing build outrun a superlinear threat curve.
+composes-with: [genre-horde-survival, system-build-diversity, system-reward-schedules, system-progression]
+anchors: [anchor-vampire-survivors]
+verify-with: docs/FUN.md#6-·-twin-stick-horde-survival-vampire-survivors-like
+---
+
+# Vampire Survivors
+
+**What it is.** You steer a character with one stick; every weapon auto-fires.
+Kill enemies, collect gems, level up, pick one of three upgrades, and repeat
+until you're a screen-clearing storm of projectiles — or the swarm finally
+catches you.
+
+**Player fantasy / why it's fun.** *I started weak and now I am a walking
+apocalypse.* The pull is the **power-curve crossover**: for the first minutes
+you barely survive; then your build tips over a threshold and the same enemies
+that terrified you become confetti. Minimal input, maximal escalation.
+
+## Design DNA
+
+Strip combat down to **positioning only** — remove aiming, remove firing — so
+the entire skill expression is *where you stand* and *what you build*. Then
+run two exponentials against each other: a **multiplicatively growing build**
+vs a **superlinearly rising tide** of enemies. Fun is the race between those
+curves, and the drama is whether your build tips over before the swarm does.
+
+The whole design lives or dies on the **crossover point**. Set it too early
+and the run is a boring victory lap; too late and it's a frustrating grind
+that never pays off. The spawn curve must be *superlinear* (quadratic ramp)
+precisely because the build is *multiplicative* — a linear threat can't stay
+ahead of a build that stacks area × count × cooldown, so the upgrades would
+trivialise the night. Two matched exponentials is what keeps the tension taut
+for the full timer.
+
+The upgrade draft is the whole game's decision surface. Everything else is a
+treadmill you're outrunning — which is why the draft cadence (frequent,
+low-stakes, one-of-three) matters more than any single weapon's numbers.
+
+## Load-bearing structures
+
+| Structure | Why it works |
+|---|---|
+| **Auto-attack; you only move** | Removes execution skill, foregrounds build + positioning. Radically low input, high legibility. |
+| **Superlinear spawn pressure** | Enemy density ramps quadratically so it can stay ahead of a multiplicative build — or upgrades trivialise the run. FUN.md truth. [[system-difficulty-and-dda]]. |
+| **Level-up draft-of-3, sim paused** | The one decision that matters, delivered as a frequent, low-stakes pick. Picks are *input actions* so runs replay. [[system-reward-schedules]]. |
+| **Multiplicative build growth** | Weapons + passives stack multiplicatively (area × count × cooldown), so builds *tip over* rather than climb linearly. [[system-build-diversity]]. |
+| **Evolution recipes** | Weapon + matching passive fuses into a super-weapon — a hidden combinatorial goal that rewards knowledge. [[system-crafting]]. |
+| **Orbiting is the skill** | The safe play is circling the horde, not fleeing (kiting corners you). The map teaches this by shape. |
+| **Session = a fixed timer** | ~15–30 min "survive the clock" gives a clean win condition and a legible arc. [[system-session-structure]]. |
+
+## What to steal
+
+- **Auto-fire so the only inputs are move + draft.** The lowest-input action
+  loop that still feels like combat. Instant onboarding.
+- **Two racing curves.** Multiplicative build vs superlinear swarm. Tune the
+  crossover point — that's the whole difficulty design. Assert `peak alive ≥
+  N` so the horde feel can't regress (FUN.md).
+- **Frequent low-stakes draft-of-3.** Many small choices beat few big ones for
+  flow; keep the sim paused during the pick and log it as input.
+- **Hidden fusion recipes** as a knowledge-reward layer over the visible
+  draft.
+- **A survive-the-timer session frame** for a clean, repeatable arc — a fixed
+  clock gives a legible win, a natural finale spike, and a stable unit for
+  balancing the two curves.
+- **Foreground positioning by making the safe play *circling*.** Design the
+  arena and enemy speeds so orbiting the horde beats fleeing it; a kiting-bot
+  that corners itself proves the map teaches the right instinct (FUN.md §6).
+
+## What's just theme (drop it)
+
+- **Gothic/vampire skin.** Pure paint — the same loop ships as bugs, robots,
+  or emoji.
+- **The specific weapon roster.** The *categories* (orbit, projectile, aura,
+  melee) are structural; garlic vs holy-water is flavour — see
+  [[system-build-diversity]].
+- **Meta gold shop.** A common bolt-on ([[system-meta-progression]]) but not
+  essential; the in-run curve carries the fun alone.
+- **The pixel-swarm look.** Aesthetic. The tide only needs to *read* as
+  overwhelming.
+
+## Composes into
+
+- [[genre-horde-survival]] — its canonical anchor; the rising-tide-vs-build
+  loop lives there.
+- [[system-build-diversity]] — the multiplicative-stack draft is the exemplar.
+- [[system-reward-schedules]] — the paced level-up draft.
+- [[system-progression]] — in-run power pacing.
+- [[system-difficulty-and-dda]] — the superlinear spawn curve as the
+  difficulty engine.
+
+## Twist seams
+
+- **Vampire Survivors but you place the build before the run and only watch**
+  *(structure)* — pushes it toward [[genre-auto-battler]]: the draft moves to
+  a prep phase, positioning becomes formation. Bends who decides when.
+- **Vampire Survivors but one weapon, and the draft upgrades the *map***
+  *(mechanic-swap)* — instead of stacking weapons you reshape the arena
+  (walls, funnels, hazards); the tide stays, the build becomes level design.
+- **Vampire Survivors but the tide is time itself** *(constraint)* — no
+  enemies; the "swarm" is a rising flood or dark you outbuild by
+  lighting/pumping. Same crossover drama, no combat. Pairs with
+  [[genre-survival-horror]].
+- **Vampire Survivors but tonally serene — you're growing a garden the weeds
+  are racing** *(tonal)* — the swarm becomes encroaching overgrowth, the build
+  becomes cultivation; the same two-exponential race, recolored from panic to
+  tending. Pairs with [[genre-farming-sim]].
+
+## See also
+
+- [[genre-horde-survival]] · [[system-build-diversity]] ·
+  [[system-reward-schedules]]
+- `docs/FUN.md#6-·-twin-stick-horde-survival-vampire-survivors-like` —
+  orbit-bot + peak-alive verify.
+- `sandboxes/particle-studio/` — pooled, cosmetic swarm rendering (deletable
+  per law 6).
+- `docs/JUICE.md` — the level-up / crit / clear feedback choreography.

package/design/20-genres/README.md

@@ -0,0 +1,62 @@
+# 20-genres/ — the creative genre templates
+
+Each module here is the **design** counterpart to a section of
+[`docs/FUN.md`](../../docs/FUN.md). FUN.md answers *"how do I PROVE this genre is
+fair?"* — solvers, bot runs, pacing windows, both-ways affordance proofs. These
+modules answer the front-half question FUN.md can't: *"how do I DESIGN a great
+one?"* — the pillars, the loop stack, the systems it needs, the twist seams, and
+the traps that kill it.
+
+**They pair, they don't overlap.** Every genre module sets `verify-with:` to its
+matching FUN.md section and *links* it rather than restating a single verify
+recipe. Design here; prove there. When your design blends genres, satisfy **every
+parent's** verify pattern (rhythm = roguelike + input legality; Peggle = physics +
+aim search — FUN.md Part 3).
+
+Reach for one when the [pipeline](../README.md) hits **COMPOSE**: you've named the
+[[anchor]] the game *is*, and you need the genre's design skeleton — pillars, loop
+stack, and the `[[system-*]]` parts to bolt on — before you [twist](../00-process/the-twist.md)
+it into something worth building.
+
+## The 24 genre modules
+
+The first 21 map 1:1 to FUN.md §1–§21. The last three are **extensions** beyond
+FUN.md's corpus — genres the campaign didn't cover but the Codex designs for.
+
+| id | title | one-line pillar |
+|---|---|---|
+| [[genre-grid-puzzle]] | Grid Puzzle (Sokoban) | The solvable knot: obvious move is the trap. |
+| [[genre-precision-platformer]] | Precision Platformer (Celeste) | Trust in inputs; every death is your own. |
+| [[genre-metroidvania]] | Metroidvania | The locked-door promise, always kept. |
+| [[genre-action-adventure]] | Action-Adventure (Zelda) | Readable combat; telegraphs make reaction fair. |
+| [[genre-stealth]] | Stealth | Plannable danger you can read and route. |
+| [[genre-horde-survival]] | Horde Survival (Vampire Survivors) | The rising tide vs your rising build. |
+| [[genre-bullet-hell]] | Bullet Hell | Density that reads; uptime, not dodging, is the skill. |
+| [[genre-tower-defense]] | Tower Defense | Build decisions that matter; coverage is geometry. |
+| [[genre-rts]] | RTS-lite | Mass under command; asymmetry that balances. |
+| [[genre-roguelike]] | Traditional Roguelike | Fair discovery; procgen that always connects. |
+| [[genre-deckbuilder]] | Roguelike Deckbuilder | Drafts with teeth; a win-rate window. |
+| [[genre-tactics]] | Turn-based Tactics (Into the Breach) | Rewriting the telegraphed future. |
+| [[genre-match3]] | Match-3 | Cascades you triggered; instant sim, animated view. |
+| [[genre-incremental]] | Incremental / Idle | A pacing curve with no deserts. |
+| [[genre-farming-sim]] | Farming / Life Sim | Gentle solvency; plans that can come true. |
+| [[genre-survival-horror]] | Survival Horror | Dread you can budget in resource arithmetic. |
+| [[genre-city-builder]] | City / Colony Builder | The exposed score; negative synergies. |
+| [[genre-rhythm]] | Rhythm | Tight but fair; the beat is sim time. |
+| [[genre-physics-arcade]] | Physics Arcade (Peggle) | Trustworthy flight; swept collision. |
+| [[genre-racing]] | Top-down Racing | The speed/line tradeoff made physically real. |
+| [[genre-narrative-decisions]] | Narrative Decisions (Reigns) | Impossible stewardship between two ditches. |
+| [[genre-coop-chaos]] | Co-op Chaos (Overcooked) | *Extension* — communication under time pressure. |
+| [[genre-auto-battler]] | Auto-battler | *Extension* — prep then watch; economy + positioning + synergy. |
+| [[genre-exploration]] | Exploration / Immersive-sim-lite | *Extension* — curiosity and knowledge as the reward. |
+
+## Authoring one
+
+Follow [`../CONTRIBUTING.md`](../CONTRIBUTING.md): the **genre** skeleton is
+Pillars (exactly 3) · The loop stack (moment/encounter/session/meta) · Essential
+systems (a table linking `[[system-*]]` ids + why each) · Content & difficulty
+model · Signature-mechanic seeds (3–5 "X but Y" bends) · Common pitfalls · Anchors
+· Verify (link the FUN.md section) · See also. Keep it 120–260 lines, tables over
+prose, the [`docs/FUN.md`](../../docs/FUN.md) voice. Never invent a Hayao API —
+point at a [`sandboxes/`](../../sandboxes/) lab or [`examples/`](../../examples/)
+slug that already wires it.

package/design/20-genres/action-adventure.md

@@ -0,0 +1,126 @@
+---
+id: genre-action-adventure
+title: Top-down Action-Adventure (Zelda-like)
+kind: genre
+tags: [action-adventure, zelda, top-down, combat, telegraph, dungeon, readable]
+summary: Readable combat and gated dungeons — enemies that tell you what they'll do, a hit that feels like it landed, and keys that turn the map into a lock.
+use-when: Designing a top-down game of reactive melee combat woven with light puzzle-gating and exploration.
+composes-with: [system-telegraphs, system-combat-model, system-enemy-archetypes, system-encounter-design, system-boss-design, system-grace]
+anchors: [anchor-shadow-of-mordor, anchor-dead-cells]
+verify-with: docs/FUN.md#4--top-down-action-adventure-zelda-like
+---
+
+# Top-down Action-Adventure (Zelda-like)
+
+**What it is.** A top-down world of rooms and dungeons. You fight readable
+enemies with a small verb set (attack, dodge, a tool or two), collect keys and
+items that open the map, and best set-piece bosses. Combat is *reactive*: the
+enemy shows its intent, you answer.
+
+**Player fantasy / why it's fun.** *"I read that and beat it."* The satisfaction
+of watching a wind-up, recognising it, and punishing it — plus the steady drip of
+a new tool that reframes every room you've seen.
+
+## Pillars
+
+1. **Readable threat.** Every attack telegraphs — a flash, a wind-up, a
+   ~0.45s tell — long enough to react. Reactive play is only possible if the
+   threat is *legible* (FUN.md §4). [[system-telegraphs]].
+2. **The hit has weight.** Hit-stop, i-frames, knockback — a landed blow *feels*
+   landed. But hit-stop must buffer inputs through its freeze or attacks
+   "randomly" vanish ([[system-combat-model]], FUN.md law 5/§4).
+3. **The map is a lock.** Keys, switches, and items gate progress; a dungeon is a
+   spatial puzzle whose solution is the tool you find inside it.
+
+## The loop stack
+
+| Scale | The loop |
+|---|---|
+| **Moment** | Read a wind-up → dodge or block → punish in the recovery window. Sub-second. |
+| **Encounter** | A room of mixed [[system-enemy-archetypes]] — clear it by exploiting each one's tell. |
+| **Session** | A dungeon: rooms + a keyed lock puzzle + the tool that solves it + the boss that tests the tool. |
+| **Meta** | New tools reopen the overworld; hearts/upgrades and secrets reward exploration. |
+
+## Essential systems
+
+| System | Why it's needed |
+|---|---|
+| [[system-telegraphs]] | Pillar 1. The wind-up window is the entire fairness contract of reactive combat. |
+| [[system-combat-model]] | Defines the hit — damage, hit-stop, i-frames, knockback — and the input-buffer-through-freeze rule. |
+| [[system-enemy-archetypes]] | A legible alphabet (skirmisher/artillery/tank/swarm) so rooms compose meaning, not noise. |
+| [[system-encounter-design]] | Rooms as compositions of archetypes; pressure and pockets, clear exit lanes. |
+| [[system-boss-design]] | The dungeon's set-piece; phases and telegraphs that test the dungeon's tool. |
+| [[system-grace]] | I-frames on dodge, hit-stop buffering, wound-before-death — the reactive-combat grace canon. |
+
+## Content & difficulty model
+
+- **Telegraph budget first.** Fix the tell duration (~0.45s baseline) and derive
+  enemy density from it — enough space to read every threat that's live at once.
+  Overlapping unreadable tells are the genre's core unfairness.
+- **Keep exit lanes clear.** Cover or pillars in a door row/column is a softlock —
+  the containment/exit-lane rule (FUN.md §4). Author door lanes obstacle-free.
+- **Escalate by combining archetypes, not by inflating stats.** A skirmisher +
+  artillery pair is harder — and more interesting — than a bigger-HP skirmisher.
+  See [[system-encounter-design]].
+- **Gate honestly.** Dungeon locks should be solvable with the tools available
+  inside; the item you find is the intended key. Prove door gates open only when
+  their key is held (both ways).
+
+Reference wiring: [`examples/gleamvale`](../../examples/gleamvale) — the top-down
+steering + hunt-and-slash combat bot (walk, fight, telemetry: win time, hp floor,
+0 deaths). Grep [`docs/API.md`](../../docs/API.md) for the hit-stop / i-frame /
+particle primitives before citing them.
+
+## Signature-mechanic seeds
+
+"X but Y" ([[process-the-twist]]) — bend the *tool*, the *enemy memory*, or *time*.
+
+- **Zelda but every enemy remembers your last fight** — the nemesis bend: a foe
+  you fled comes back scarred and cocky. (mechanic-swap — see [[anchor-shadow-of-mordor]])
+- **Zelda but your weapon is also your key** — the sword that opens the door is the
+  one you fight with; upgrading it re-gates the map. (mechanic-swap)
+- **Zelda but time only moves when you do** — a Superhot dungeon; telegraphs freeze
+  between your steps. (constraint)
+- **Zelda but you can only hold one tool at a time** — the loadout swap *is* the
+  dungeon puzzle. (constraint)
+- **Zelda but the dungeon is a single boss's body** — rooms are organs; the tool
+  you find disables one. (theme + structure)
+
+## Common pitfalls
+
+- **Unreadable combat.** Too many simultaneous tells, tells too short, or no tell
+  at all → the player can't play reactively, only spam. Budget telegraphs first.
+- **Weightless hits.** No hit-stop/knockback/i-frames → combat feels like poking
+  fog. And hit-stop *without* input buffering eats attacks — buffer through the
+  freeze (FUN.md §4).
+- **Softlocking door lanes.** Cover in an exit row can trap the player with a live
+  enemy. Keep lanes clear.
+- **Dungeons that are combat corridors.** Without the lock-and-key layer it's a
+  beat-'em-up wearing a map. The *puzzle* of the dungeon is half the genre.
+- **Stat-inflation difficulty.** Bigger numbers aren't harder, they're slower.
+  Combine archetypes instead.
+
+## Anchors
+
+- [[anchor-shadow-of-mordor]] — the nemesis system; systemic enemy memory that
+  personalises the overworld's threats.
+- [[anchor-dead-cells]] — tight, weighty top-down/side melee feel and the
+  tool-as-key unlock loop.
+
+## Verify
+
+Prove it with **[FUN.md §4 · Action-adventure](../../docs/FUN.md#4--top-down-action-adventure-zelda-like)** —
+kiting-bot telemetry (win time, hp floor comfortable, 0 deaths); door gate proven
+both ways; containment every frame; hit-stop buffers inputs through the freeze.
+Design the readable fight here; prove it fair there.
+
+## Composes with
+
+- [[system-telegraphs]] — the readability pillar made mechanical.
+- [[system-combat-model]] — the shape and weight of a hit.
+- [[system-emergent-systems]] — nemesis-style memory turns fights into rivalries.
+
+## See also
+
+- [`examples/gleamvale`](../../examples/gleamvale) — the top-down combat bot + feel.
+- [`docs/FUN.md §4`](../../docs/FUN.md#4--top-down-action-adventure-zelda-like) — the proof playbook.

package/design/20-genres/auto-battler.md

@@ -0,0 +1,121 @@
+---
+id: genre-auto-battler
+title: Auto-Battler
+kind: genre
+tags: [auto-battler, autochess, prep-then-watch, economy, synergy, positioning, rounds, shared-pool]
+summary: Prep-then-watch — spend an economy on units, position and synergise them, then watch the round resolve itself.
+use-when: The design is a prep-phase-then-auto-combat game (autochess-like): economy + positioning + synergy across rounds.
+composes-with: [system-economy, system-build-diversity, system-unit-rosters, system-counter-systems, system-reward-schedules]
+anchors: [anchor-loop-hero]
+verify-with: docs/FUN.md#12-·-turn-based-tactics
+---
+
+# Auto-Battler
+
+**What it is.** In a prep phase you buy units from a shared pool, arrange them, and
+stack synergies; then combat resolves *without your input* and you watch your build
+prove itself. Win or lose the round, adjust, and buy again. **Extension** beyond
+FUN.md's 21 genres.
+
+**Player fantasy.** *"I built the machine; now I watch it work."* The pleasure of
+composition — of finding the synergy that snowballs — plus the tension of a fight
+you set up but can no longer touch.
+
+## Pillars
+
+1. **Prep is the game; combat is the reveal.** All agency lives in the shop and the
+   board. The auto-resolved fight is *feedback on a decision*, choreographed, not a
+   thing you play. (This is law 6 taken literally: the sim resolves, the view replays.)
+2. **Economy is the spine.** Gold, interest, roll-vs-save, level-vs-power — the
+   push-your-luck of the shop is where skill lives. Faucets and sinks must breathe.
+3. **Synergy over stats.** Power comes from combinations (traits, tiers, positions),
+   so many builds stay viable and no single unit is a solve.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Buy / sell / reroll / reposition one unit; a shop decision. |
+| **Encounter** | One round: prep, then the auto-fight resolves and scores the build. |
+| **Session** | A match: survive rounds vs a ladder/opponents until one economy wins. |
+| **Meta** | Unlocked rosters/traits/heroes; MMR; the meta-of-comps players learn. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-economy]] | Gold, interest, and the roll-vs-save tension are the primary decision layer. |
+| [[system-build-diversity]] | Many viable comps is the replay engine; synergy makes builds, not stats. |
+| [[system-unit-rosters]] | A legible roster of roles/tiers is what players draft and read. |
+| [[system-counter-systems]] | Comp-vs-comp near-hard counters keep the meta from converging on one build. |
+| [[system-reward-schedules]] | The shared-pool draw and reroll are variable-ratio; tune the odds. |
+
+## Content & difficulty model
+
+- **The shared pool is a constraint, not a faucet.** Contested units mean your comp
+  affects opponents' options; model the pool as finite (draining it is a real play).
+- **Balance is a win-rate window over comps**, borrowing the deckbuilder instrument:
+  no comp should win too often or never — assert a band, and check both edges break.
+- **Economy solvency is a law-3 inequality.** Interest breakpoints, level costs, and
+  round income must let a disciplined build power-spike on schedule; state and assert
+  the payback curve so no tier strangles the mid-game.
+- **Positioning must matter provably.** The same units in a bad formation must lose
+  to the same units well-placed — that's the proof the board is a real decision.
+
+## Signature-mechanic seeds
+
+- **Autochess *but* you place units on a hero's looping path and combat auto-runs
+  as they walk it** — the board becomes a track (structure; the Loop Hero bend,
+  composes [[anchor-loop-hero]]).
+- **Auto-battler *but* the shared pool is literally shared — one deck, drafted
+  competitively** (constraint; sharpens [[system-counter-systems]] denial).
+- **Auto-battler *but* you can interrupt the fight once, at a cost** — a single
+  spent moment of agency in a watch-only genre (mechanic-swap; [[pattern-risk-reward]]).
+- **Auto-battler *but* co-op: two players share one economy and one board**
+  (structure; composes [[genre-coop-chaos]], [[system-coop-and-competition]]).
+- **Auto-battler *but* units level by *surviving* rounds, not by gold** — the board
+  is a persistent roster you nurture (mechanic-swap; composes [[system-progression]]).
+
+## Common pitfalls
+
+- **Dominant comp.** If one synergy wins regardless, build diversity is a lie; the
+  win-rate window catches it — widen counters, not nerf-hammer a single unit.
+- **Economy with no tension.** If saving always beats rolling (or vice versa), the
+  core decision evaporates. Interest and power-spikes must trade off honestly.
+- **Combat you must watch but can't read.** If the auto-fight is illegible, players
+  can't learn from the reveal. Choreograph it so the *reason* a build won is visible.
+- **Non-deterministic resolution.** The fight must be a pure function of board +
+  `world.rng` seed; then goldens, clone-and-score comp bots, and replays are free
+  (FUN.md law 7). No `Math.random` in the fight.
+
+## Anchors
+
+- [[anchor-loop-hero]] — composing placement + auto-combat + deck into one novel
+  loop; the reference for "arrange, then watch it resolve."
+
+## Verify — extension note
+
+Auto-battler is an **extension**; with no dedicated FUN.md section it *composes its
+parents' verify patterns*:
+
+- **Auto-resolved combat honesty** → [FUN.md §12 — Tactics](../../docs/FUN.md#12-·-turn-based-tactics):
+  the fight is a pure sim returning choreography; 1-ply/clone-and-score comp bots are
+  real baselines; golden end-state per board. **This is the primary proof.**
+- **Draft/economy balance** → [FUN.md §11 — Deckbuilder](../../docs/FUN.md#11-·-roguelike-deckbuilder):
+  win-rate *window* over comps; a "never-synergise" pilot loses well below it.
+- **Pacing solvency** → [FUN.md §14 — Incremental](../../docs/FUN.md#14-·-incrementalidle):
+  assert flat-ish payback curves across economy tiers; no power desert.
+- Determinism and cosmetic-view (laws 6–7) apply unchanged — the watch phase is the
+  clearest case of "sim resolves, view replays."
+
+## Composes with
+
+- [[system-economy]] — the shop is the game; borrow its faucet/sink and interest tuning.
+- [[system-build-diversity]] — synergy space is the replay value.
+- [[system-counter-systems]] — comp-vs-comp counters keep the meta honest.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §11–12 — the deckbuilder window + tactics
+  clone-and-score bots this genre borrows wholesale.
+- [[anchor-loop-hero]] — the three-genre composition reference.

package/design/20-genres/bullet-hell.md

@@ -0,0 +1,123 @@
+---
+id: genre-bullet-hell
+title: Bullet Hell
+kind: genre
+tags: [bullet-hell, shmup, danmaku, patterns, dodging, boss, density]
+summary: Screen-filling patterns that read as motion, not noise — dodging is trivial, holding fire lanes under a boss is the skill.
+use-when: You want a reflex game where the fantasy is threading a wall of bullets that looks impossible but is fair.
+composes-with: [system-telegraphs, system-boss-design, system-difficulty-and-dda, system-grace, genre-horde-survival]
+anchors: [anchor-nuclear-throne]
+verify-with: docs/FUN.md#7--bullet-hell
+---
+
+# Bullet Hell
+
+**What it is.** A shoot-'em-up where the screen fills with **coherent bullet
+patterns** the player threads on foot. The bullets are the level; your hitbox is
+a single pixel; the whole game is *reading density as motion*.
+
+**Player fantasy / why it's fun.** *"I walked through a wall of death and it was
+gorgeous."* Danmaku turns raw panic into a dance — a pattern that looks
+unsurvivable resolves into one obvious gap you slide through at the last frame.
+
+## Pillars
+
+1. **Density that reads.** Every pattern is a legible shape (spiral, aimed
+   spread, wall-with-gap). Difficulty comes from *tighter gaps and faster
+   waves*, never from noise. Density ≠ difficulty.
+2. **The gap is always there.** Fairness is provable: a greedy lookahead dodger
+   clears deathless. If the bot can't survive, humans die *unfairly* — that's a
+   bug, not challenge.
+3. **Uptime is the game.** Dodging is trivial; the skill is holding your fire
+   lane on the boss *while* dodging. Reward aggression under pressure.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Read the next wave's shape → slide into its gap → keep firing. |
+| **Encounter** | A boss's pattern sequence: phases escalate; each phase teaches its gap before it speeds up. |
+| **Session** | A stage: trash waves as breathers, midboss, boss. Graze/point economy rewards flying close. |
+| **Meta** | Score chase, unlock ships/patterns, difficulty tiers (easy = wider gaps, same shapes). |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-telegraphs]] | Every pattern's spawn point and direction must be readable *before* it's lethal — the tell is the fairness. |
+| [[system-boss-design]] | The boss IS the content; phases are the difficulty ramp. Spectacle + honest tells. |
+| [[system-grace]] | Mercy clears on death and at phase transitions are **structural** — without them deaths cascade (FUN.md law 5). |
+| [[system-difficulty-and-dda]] | Difficulty tiers = wider gaps / slower bullets on the *same* patterns, not new ones. |
+| [[pattern-readability]] | Player bullets, enemy bullets, and the tiny hitbox must never blur together. |
+
+## Content & difficulty model
+
+- **Pattern library, not level data.** Author reusable emitters (spiral, ring,
+  aimed n-spread, wall-with-moving-gap) parameterised by rate/speed/count.
+  Stages are *sequences* of patterns; difficulty is the parameters.
+- **Ramp by geometry.** Widen or narrow the gap chord; speed up bullets; overlap
+  two patterns. Cap peak on-screen bullet count and assert it — a spike past the
+  budget is a frame-rate cliff, not difficulty.
+- **Breathers are structural.** Trash waves and post-boss lulls let the player
+  reset. A stage that never breathes reads as noise.
+- **Verify the gap exists.** The greedy dodge bot must clear every stage
+  deathless before you tune numbers — see [[system-difficulty-and-dda]] and the
+  verify link below.
+
+## Signature-mechanic seeds
+
+- **Bullet hell but you place the bullets** *(mechanic-swap)* — a reverse shmup:
+  you author the enemy's next pattern from a hand, then dodge your own design.
+- **Bullet hell but time only moves when you do** *(constraint)* — SuperHot for
+  danmaku; density becomes a spatial puzzle instead of a reflex test.
+- **Bullet hell but the gap is drawn in ink** *(theme + tonal)* — Kentō
+  woodblock; every wave is a brushstroke, grazing "wets" the paper for score.
+- **Bullet hell but co-op share one hitbox** *(perspective)* — two players, one
+  ship's life pool; threading requires reading each other. Pairs
+  [[system-coop-and-competition]].
+- **Bullet hell but bullets are the platform** *(mechanic-swap)* — stand *on*
+  slow bullets to reach the boss; movement and dodging invert.
+
+Pick one and let it ripple: a strong bullet-hell twist changes the *scoring
+economy* (what grazing means), the *pattern authoring* (who places the bullets),
+or the *hitbox itself* — not just the skin. See [[process-the-twist]].
+
+## Common pitfalls
+
+- **Noise mistaken for depth.** More bullets ≠ harder; unreadable ≠ challenging.
+  If a death feels random, the pattern didn't telegraph.
+- **No mercy on death.** Reviving into a live pattern chains deaths — always
+  clear the screen and grant i-frames (law 5).
+- **Hitbox lies.** If the visible sprite is the hitbox, players die to grazes
+  that looked clear. Hitbox must be a tiny, honest sub-pixel.
+- **Passive is optimal.** If parking in a corner survives, uptime isn't rewarded
+  — pull the player forward with graze/point economy.
+- **Difficulty tiers are new patterns.** An "easy" mode that swaps in different
+  shapes doubles your authoring and splits your proofs. Same patterns, wider
+  gaps — one library, many tunings ([[system-difficulty-and-dda]]).
+
+## Anchors
+
+- [[anchor-nuclear-throne]] — arcade twin-stick reflex mastery; the tight
+  run-based loop and readable enemy fire translate straight to danmaku.
+- [[genre-horde-survival]] — the sibling "rising tide" genre; borrow its
+  density-that-reads discipline, swap auto-attack for manual dodge.
+
+## Verify
+
+Prove it in **[FUN.md §7 · Bullet hell](../../docs/FUN.md#7--bullet-hell)**: the
+greedy lookahead dodge bot clears deathless, peak-bullet count is asserted, and
+the per-step time budget holds.
+
+## Composes with
+
+- [[system-telegraphs]] — the tell that makes a wall of bullets fair.
+- [[system-boss-design]] — the phased set-piece that is the whole encounter.
+- [[system-grace]] — mercy clears and i-frames as structure, not polish.
+
+## See also
+
+- [`sandboxes/particle-studio`](../../sandboxes/particle-studio) — emitter and
+  pooled-sprite wiring for cheap on-screen bullet mass.
+- [docs/JUICE.md](../../docs/JUICE.md) — graze feedback, hit-stop, screen-clear
+  flash as choreography (cosmetic, law 6).