hayao 0.4.1 → 0.4.2

package/design/20-genres/grid-puzzle.md

@@ -0,0 +1,126 @@
+---
+id: genre-grid-puzzle
+title: Grid Puzzle (Sokoban-like)
+kind: genre
+tags: [puzzle, sokoban, grid, solver, deterministic, turn-based, knot]
+summary: The solvable knot — a grid of pieces where the obvious move is a trap and the real line is a small proof you feel yourself find.
+use-when: Designing a turn-based, perfect-information puzzle whose fun is out-thinking a hand-authored or generated board.
+composes-with: [system-onboarding, system-difficulty-and-dda, system-procgen-design, system-save-and-checkpoint, system-mastery-curve]
+anchors: [anchor-baba-is-you, anchor-into-the-breach]
+verify-with: docs/FUN.md#1--grid-puzzle-sokoban
+---
+
+# Grid Puzzle (Sokoban-like)
+
+**What it is.** A finite grid, a handful of pieces, and one legal-move rulebook.
+Every board is a **knot**: a state you must untie in a fixed number of reversible
+moves. No timer, no dexterity, no hidden information — only the gap between the
+move that looks right and the move that is.
+
+**Player fantasy / why it's fun.** *"I saw it."* The click of a solution
+resolving in your head one beat before your hands move. The puzzle never lies to
+you; when you lose you were wrong, and being wrong is the whole pleasure.
+
+## Pillars
+
+1. **Perfect information, imperfect intuition.** Everything is on the board. The
+   difficulty is entirely in the player's head — the trap is a *plausible* wrong
+   line, not a hidden fact.
+2. **Reversibility.** Undo and restart are free and instant. The player
+   experiments *toward* the answer; punishment is boredom, never lost progress.
+3. **The mechanic is the content.** One clean rule, milked for every
+   consequence. New pieces teach; they don't clutter. (Baba Is You is the
+   extreme: the *rules themselves* are pushable blocks.)
+
+## The loop stack
+
+| Scale | The loop |
+|---|---|
+| **Moment** | Push a block one tile. Read the new board. Feel the knot loosen or tighten. |
+| **Encounter** | One level: form a hypothesis → test a line → hit a dead end → *see* the real line → execute. The "aha" is the encounter payload. |
+| **Session** | A ramp of 8–15 levels that each introduce or recombine one idea; the last is the boss knot. |
+| **Meta** | Level packs, star ratings for move-optimality, optional "hard mode" variants of solved boards. |
+
+## Essential systems
+
+| System | Why it's needed |
+|---|---|
+| [[system-onboarding]] | Teach each mechanic by *forcing* its use in a trivially-solvable board before it appears in a hard one. No text tutorials. |
+| [[system-difficulty-and-dda]] | The pack is a difficulty curve; sequence levels so each isolates one new idea, then combines. |
+| [[system-save-and-checkpoint]] | Undo + restart are the genre's grace (FUN.md law 5); per-level completion + best-move-count persist. |
+| [[system-procgen-design]] | Optional: generate-and-solve to mass-produce boards; every generated board must be solver-proven winnable. |
+| [[system-mastery-curve]] | Move-optimal solutions and hidden variant boards give experts a ceiling above "just solved it." |
+
+## Content & difficulty model
+
+- **One idea per level, then combine.** Introduce piece X in a board where *only*
+  X matters. Two levels later, cross X with Y. The boss is X × Y × Z.
+- **Difficulty = branching factor × depth of the trap.** A hard board isn't a
+  bigger board; it's a board where the greedy first move is *wrong* and the real
+  line is 3 moves deeper than it looks.
+- **Machine-proven winnable, always.** Every level ships with a solver
+  (BFS/A* over `Puzzle<State, Move>`) proof. An unwinnable board is unshippable —
+  see FUN.md §1. Generated boards are filtered by the same solver; tune the
+  generator's *difficulty* on solver depth, not by eye.
+- **Author dead-ends on purpose.** The best boards let the player reach a
+  *stuck-but-not-lost* state — reachable, un-winnable, obvious in hindsight. That
+  near-miss is where the lesson lands.
+
+Reference wiring: [`examples/sokoban`](../../examples/sokoban) — the canonical
+logic/view split, a pure `logic.ts` `Puzzle` module driving a scene-tree view;
+[`examples/gravewell`](../../examples/gravewell) and
+[`examples/seamfold`](../../examples/seamfold) for two more grid-logic variants.
+
+## Signature-mechanic seeds
+
+Each is an "X but Y" ([[process-the-twist]]) — bend the *rule*, since the rule is
+the content.
+
+- **Sokoban but the boxes are you** — push a block and *your* avatar is what
+  moves; you shove yourself around the knot. (mechanic-swap)
+- **Sokoban but gravity picks a direction each turn** — every move re-drops the
+  board; you plan the settle, not just the push. (mechanic-swap)
+- **Sokoban but two avatars share one input** — every arrow moves both; the level
+  is solved only when their mirrored paths both land. (constraint)
+- **Sokoban but the goal tiles move when you do** — the target is a second puzzle
+  chasing the first. (structure)
+- **Sokoban but undo is a piece you place** — a finite pool of rewinds becomes a
+  resource you spend inside the puzzle, not a free safety net. (constraint)
+
+## Common pitfalls
+
+- **Trial-and-error instead of insight.** If brute-forcing every push beats
+  thinking, the board is a search, not a puzzle. Keep boards small enough that the
+  *thinking* is faster than the flailing.
+- **Read-the-designer's-mind moves.** A required move with no on-board reason is
+  unfair. Every step of the real line must be *justifiable from the board alone*.
+- **Undo that costs.** Punishing experimentation kills the loop. Undo/restart are
+  free, instant, and unlimited — pillar 2.
+- **Difficulty by fiddliness.** A 40×40 board isn't hard, it's tedious. Depth
+  comes from the trap, not the tile count.
+- **Skipping the solver.** Hand-authoring "I'm pretty sure this is solvable" ships
+  dead levels. Prove every one — FUN.md §1.
+
+## Anchors
+
+- [[anchor-baba-is-you]] — the mechanic *is* the content, pushed to its limit.
+- [[anchor-into-the-breach]] — perfect-information reasoning; a telegraphed board
+  you solve, not react to.
+
+## Verify
+
+Prove it with **[FUN.md §1 · Grid puzzle](../../docs/FUN.md#1--grid-puzzle-sokoban)** —
+solver over `Puzzle<State,Move>` for every level; replay determinism; undo/restart
+as grace. Design the knot here; prove it solvable there.
+
+## Composes with
+
+- [[system-onboarding]] — the pack *is* the tutorial; teach by forced use.
+- [[system-procgen-design]] — generate-and-solve for volume; solver-gated.
+- [[pattern-mastery-and-flow]] — the ramp must keep challenge just above intuition.
+
+## See also
+
+- [`examples/sokoban`](../../examples/sokoban) — the reference logic/view split.
+- [`docs/FUN.md §1`](../../docs/FUN.md#1--grid-puzzle-sokoban) — the proof playbook.
+- [[process-the-twist]] — bend the rule; the rule is the game.

package/design/20-genres/horde-survival.md

@@ -0,0 +1,128 @@
+---
+id: genre-horde-survival
+title: Twin-stick Horde Survival (Vampire Survivors-like)
+kind: genre
+tags: [horde, survivors, twin-stick, auto-attack, build, wave, roguelite, orbit]
+summary: The rising tide vs your rising build — minimal input, auto-attacks, and a level-up draft that races a superlinear swarm you must out-scale.
+use-when: Designing a survive-the-timer game where the skill is positioning and build-drafting against an escalating horde.
+composes-with: [system-build-diversity, system-meta-progression, system-reward-schedules, system-difficulty-and-dda, system-procgen-design, system-session-structure]
+anchors: [anchor-vampire-survivors, anchor-nuclear-throne]
+verify-with: docs/FUN.md#6--twin-stick-horde-survival-vampire-survivors-like
+---
+
+# Twin-stick Horde Survival (Vampire Survivors-like)
+
+**What it is.** You move; you don't aim. Weapons fire automatically. The screen
+fills with enemies at a rising rate, and every few seconds you pick one upgrade
+from a draft. The run is a race between the **swarm's growth** and your **build's
+growth** — survive the timer, or drown.
+
+**Player fantasy / why it's fun.** *"My build came online."* The turn from
+scraping by to mowing hundreds — the multiplicative moment when three upgrades
+click and the horde that was killing you becomes XP confetti. Minimal input,
+maximal escalation.
+
+## Pillars
+
+1. **Positioning is the only input.** No aiming, no reloading — the skill is
+   *orbiting* the horde so your auto-attacks sweep them, herding density into your
+   fire. (Kiting bots corner themselves; the skill is the orbit — FUN.md §6.)
+2. **Build growth is multiplicative.** Upgrades compound — +area × +count ×
+   +damage — so the power fantasy accelerates. This is why the tide must be
+   superlinear to keep pace ([[system-build-diversity]]).
+3. **The tide always rises.** Spawn pressure climbs relentlessly (quadratic ramp)
+   so the run is always tightening; the peak-alive count is a designed target, not
+   an accident.
+
+## The loop stack
+
+| Scale | The loop |
+|---|---|
+| **Moment** | Orbit; sweep a cluster; scoop the XP gems it drops. |
+| **Encounter** | A wave / minute band: survive its density, then the level-up draft that answers it. |
+| **Session** | One ~10–20 min run: draft a build, out-scale the tide, reach the timer or die. |
+| **Meta** | Between-run persistent unlocks (new characters, weapons, permanent perks) that change *what you can draft*. |
+
+## Essential systems
+
+| System | Why it's needed |
+|---|---|
+| [[system-build-diversity]] | The draft is the game; many upgrades × real synergies make each run a different build story. Pillar 2. |
+| [[system-meta-progression]] | Persistent between-run unlocks that add *options* (not just power) — the reason to run again. Pillar of retention. |
+| [[system-reward-schedules]] | XP gems, chests, level-up timing — the drip that paces the power fantasy; keep it ethical (no dark patterns). |
+| [[system-difficulty-and-dda]] | The tide curve; the quadratic spawn ramp is the difficulty. Assist = slower ramp or a revive. |
+| [[system-procgen-design]] | Enemy composition and pickup placement varied per run within provable pressure bounds. |
+| [[system-session-structure]] | A run is a fixed-length timer; define the band structure (minute → boss-minute → finale). |
+
+## Content & difficulty model
+
+- **Spawn pressure must be superlinear.** Multiplicative build growth out-runs a
+  linear tide by minute three; the horde needs a *quadratic* ramp to stay a threat
+  through the finale (FUN.md §6). Derive the ramp from expected build DPS, not by
+  feel.
+- **Level-up picks pause the sim, and are input actions.** The draft freezes time;
+  each pick is a replayable input, never a direct mutation (FUN.md §6, law 6).
+- **Assert `peak alive ≥ N`.** Lock in the horde feel so it can't silently regress
+  — a build that trivialises the swarm should still face a wall of bodies at the
+  peak (FUN.md §6).
+- **Synergies over stat sticks.** A weapon that *combines* with another (garlic +
+  knockback = a grinder) beats a flat +10% damage. Build the upgrade pool so 3–4
+  archetypes each have a payoff spike.
+
+Reference wiring: [`examples/emberwake`](../../examples/emberwake) — the horde sim
+in `world.state` with a *pooled-sprite* view (the cosmetic-view rule under load);
+the orbit-bot survival proof and `peak alive` assertion pattern. Grep
+[`docs/API.md`](../../docs/API.md) for the pooling and particle primitives.
+
+## Signature-mechanic seeds
+
+"X but Y" ([[process-the-twist]]) — bend the *input*, the *tide*, or the *draft*.
+
+- **Survivors but you draw your attack path** — one gesture per few seconds aims
+  the sweep; positioning *plus* one deliberate stroke. (mechanic-swap)
+- **Survivors but the horde is your XP economy AND your clock** — kills you don't
+  scoop become the enemies of the next minute. (structure)
+- **Survivors but you draft the enemies too** — pick your upgrade *and* what the
+  tide sends next; risk-reward push-your-luck. (mechanic-swap — pairs with [[pattern-risk-reward]])
+- **Survivors but two players share one XP pool and one screen** — coop where you
+  fight over the draft. (perspective — pairs with [[genre-coop-chaos]])
+- **Survivors but the map shrinks each minute** — the arena, not just the spawn
+  rate, is the rising tide. (constraint)
+
+## Common pitfalls
+
+- **Linear tide, exponential build.** By minute three the player is a god and
+  bored. The ramp must be superlinear (FUN.md §6). This is the #1 failure.
+- **Aiming.** Adding a manual aim verb breaks the minimal-input fantasy and the
+  orbit skill. Keep the hands quiet; the mind does the building.
+- **Flat upgrade pool.** All-stat-sticks, no synergies → every run is the same
+  build. Author payoff spikes ([[system-build-diversity]]).
+- **Meta that only adds raw power.** If unlocks just make you stronger, runs
+  homogenise. Add *options* that change the draft ([[system-meta-progression]]).
+- **A draft that doesn't pause.** Picking under fire is stress, not strategy —
+  freeze the sim for the choice.
+
+## Anchors
+
+- [[anchor-vampire-survivors]] — the minimal-input horde loop; build-growth vs
+  rising tide; the auto-attack fantasy.
+- [[anchor-nuclear-throne]] — arcade twin-stick roguelite tightness; steal the
+  run-based mastery and moment-to-moment feel.
+
+## Verify
+
+Prove it with **[FUN.md §6 · Horde survival](../../docs/FUN.md#6--twin-stick-horde-survival-vampire-survivors-like)** —
+orbit-bot survives with an hp floor; `peak alive ≥ N` asserted so the horde can't
+regress; the superlinear spawn ramp checked against build DPS; sim ms/step budget
+under load. Design the tide-vs-build here; prove the race there.
+
+## Composes with
+
+- [[system-build-diversity]] — the draft is the game; synergies over stat sticks.
+- [[system-meta-progression]] — between-run options are the retention loop.
+- [[pattern-feedback-loops]] — the build's positive loop must stay just behind the tide.
+
+## See also
+
+- [`examples/emberwake`](../../examples/emberwake) — the reference horde sim + pooled view.
+- [`docs/FUN.md §6`](../../docs/FUN.md#6--twin-stick-horde-survival-vampire-survivors-like) — the proof playbook.

package/design/20-genres/incremental.md

@@ -0,0 +1,120 @@
+---
+id: genre-incremental
+title: Incremental / Idle
+kind: genre
+tags: [incremental, idle, clicker, prestige, economy, pacing, payback, ramp]
+summary: Number-goes-up economy where the design IS the pacing curve — first-buy times and era gaps tuned so there are no deserts.
+use-when: Designing a clicker/idle/prestige game whose fun is a smooth ramp of unlocks with no dead stretches waiting for a wall.
+composes-with: [system-economy, system-progression, pattern-feedback-loops, system-reward-schedules]
+anchors: [anchor-balatro, anchor-factorio]
+verify-with: docs/FUN.md#14--incrementalidle
+---
+
+# Incremental / Idle
+
+**What it is.** An economy that grows itself. You buy producers, producers make
+currency, currency buys more producers; periodically a **prestige** reset trades
+progress for a permanent multiplier. The number goes up — the question is only
+*how fast, and toward what next unlock*.
+
+**Player fantasy / why it's fun.** *"I keep crossing thresholds I couldn't afford a
+minute ago."* The pull is a horizon that keeps arriving: every purchase is close, the
+next tier is visible, and a reset makes the whole climb feel faster. Fun is the
+**pacing curve with no deserts** — the moment you're bored, the game has failed.
+
+## Pillars
+
+1. **The curve is the game.** First-buy times and the gaps between eras *are* the
+   design surface. You are authoring a rhythm of "soon", not a set of numbers.
+2. **Every tier pays back on schedule.** Cost-over-production per tier stays roughly
+   flat (a ~15–25s payback). A rising payback silently strangles the late game.
+3. **Intent is an action, never a mutation.** A click is `input.press`, not a direct
+   state write — or the replay lies and the balance-sim can't trust the arc.
+
+## The loop stack
+
+| Layer | The beat |
+|---|---|
+| **Moment** | Afford the next thing → buy it → watch the rate tick up. |
+| **Encounter** | Reach a tier / unlock / milestone that changes what you optimise. |
+| **Session** | Climb toward a prestige; decide when to reset. |
+| **Meta** | Prestige multipliers, permanent upgrades, new mechanic layers per reset. |
+
+## Essential systems
+
+| System | Why this genre needs it |
+|---|---|
+| [[system-economy]] | Faucets, sinks, and currencies are the entire object; inflation control keeps late tiers meaningful. |
+| [[system-progression]] | The power curve *is* the content; pacing power gain is pacing the game. |
+| [[pattern-feedback-loops]] | Production→currency→production is a runaway positive loop; prestige is the negative-loop reset that re-paces it. |
+| [[system-reward-schedules]] | Milestone unlocks and offline-earnings payouts are the variable, anticipated rewards. |
+| [[system-meta-progression]] | Prestige currency + permanent buffs are cross-run meta; power vs. new options is the tuning axis. |
+| [[system-onboarding]] | The first three buys must land in under a minute or the ramp never catches. |
+
+## Content & difficulty model
+
+- **Balance-sim the whole arc.** Run the economy headless from zero to endgame; assert
+  the pacing windows (first-buy times, era-to-era gaps), **monotone production**, and
+  **no unlock deserts** — no stretch where nothing new is affordable for too long.
+- **Flat payback per tier.** State the inequality: `cost_n / production_n ≈ const`
+  (~15–25s) across tiers. A tier whose payback balloons is a wall; assert it against
+  the actual config, don't vibe it.
+- **No click-softlock.** Prove the player can always progress without a required
+  manual click storm — an idle game must idle.
+- **Difficulty = slope, not spikes.** You never "make it harder"; you shape how long
+  each threshold takes. A desert is the only real failure state.
+- **New layer per prestige.** Each reset should unlock a *mechanic*, not just a bigger
+  multiplier, or the late loop flattens into staring.
+
+## Signature-mechanic seeds
+
+- **Incremental but the producers are a factory graph** — outputs feed inputs, and
+  the bottleneck moves (mechanic-swap toward [[anchor-factorio]]; the curve becomes a
+  logistics puzzle).
+- **Incremental but every prestige is a poker deck** — reset trades score for jokers
+  that reshape the next run's multipliers (mechanic-swap toward [[anchor-balatro]]).
+- **Incremental but it's a tended garden** — production is crops maturing on a
+  calendar; the tonal bend swaps grind-anxiety for [[genre-farming-sim]] calm.
+- **Incremental but one hard constraint: one currency, one screen** — no menus, the
+  whole ramp legible at once (constraint; forces ruthless curve design).
+- **Incremental but the number going up is a story meter** — thresholds unlock
+  narrative, not just power (tonal; pairs with [[genre-narrative-decisions]]).
+
+## Common pitfalls
+
+- **Rising payback ratios.** The classic strangler: late tiers cost far more than they
+  return, the ramp stalls, the player quits. The flat-payback inequality exists to
+  catch exactly this.
+- **Unlock deserts.** Any dead stretch waiting on a wall is the genre's cardinal sin;
+  the balance-sim asserts against them.
+- **Direct-mutation UI.** Buttons that write state instead of pressing an input make
+  replay and the balance-sim untrustworthy — the arc can't be proven.
+- **Prestige-as-only-content.** Resets that add a multiplier and nothing else flatten
+  the meta; each should open a new mechanical layer.
+- **Punishing idle.** If afk means you fall behind, it isn't idle. Offline earnings and
+  a click-free path are load-bearing.
+
+## Anchors
+
+- [[anchor-balatro]] — the "number goes up" surge and the reset-for-multipliers loop;
+  the direct reference for the prestige-as-deck seed.
+- [[anchor-factorio]] — production feeding production, complexity scaling with the
+  curve; the reference for the factory-graph bend.
+
+## Verify
+
+Balance-sim the arc; assert pacing windows, monotone production, no unlock deserts,
+no click-softlock → **[docs/FUN.md §14 · Incremental/idle](../../docs/FUN.md#14--incrementalidle)**.
+Author the curve here; prove its windows there.
+
+## Composes with
+
+- [[system-economy]] — the faucet/sink model the whole ramp rides on.
+- [[system-progression]] — the power curve you are literally pacing.
+- [[pattern-feedback-loops]] — the runaway production loop and the prestige brake.
+
+## See also
+
+- [docs/FUN.md §14](../../docs/FUN.md#14--incrementalidle) — mechanical truth + verify recipe.
+- [`sandboxes/`](../../sandboxes/) — the procgen/economy lab to prototype a payback
+  curve headless before wiring UI.

package/design/20-genres/match3.md

@@ -0,0 +1,120 @@
+---
+id: genre-match3
+title: Match-3
+kind: genre
+tags: [match3, cascade, tile-swap, puzzle, board, combo, casual, choreography]
+summary: Swap-adjacent tile matcher where the fun is the cascade you triggered — one swap, a chain reaction the board runs for you.
+use-when: Designing a tile-swap/board-clear game where a single legal move should bloom into a satisfying, deterministic chain.
+composes-with: [system-reward-schedules, system-difficulty-and-dda, pattern-juice-choreography, pattern-feedback-loops]
+anchors: [anchor-peggle, anchor-balatro]
+verify-with: docs/FUN.md#13--match-3
+---
+
+# Match-3
+
+**What it is.** A grid of coloured tiles. You **swap two adjacent tiles**; any line
+of 3+ clears, tiles above fall, and new clears may form — a **cascade** the board
+resolves on its own. One input, a bloom of consequence.
+
+**Player fantasy / why it's fun.** *"I found the one move that made the whole board
+go off."* The pull is authored luck: you set up the domino, the game topples it in a
+shower of pops. Fun is the **cascade you triggered**, not the cascade you watched.
+
+## Pillars
+
+1. **The swap is the whole decision.** Everything downstream — cascade, combo,
+   special tiles — is *consequence*, not input. Depth lives in reading the board,
+   not in dexterity.
+2. **The board is always fair and always alive.** No pre-made matches at deal, a
+   legal move always exists, and a dead board reshuffles. The player never loses to
+   the deal.
+3. **Consequence is choreographed.** The sim resolves instantly and deterministically
+   to a *script*; the view animates that script (the purest form of the cosmetic
+   rule). The juice is earned by the move, timed to the chain.
+
+## The loop stack
+
+| Layer | The beat |
+|---|---|
+| **Moment** | Pick a swap → watch the cascade the board runs. |
+| **Encounter** | A board/level: hit a goal (score, clear jelly, drop an anchor) within a move or time budget. |
+| **Session** | A run of boards; difficulty ramps via goal, not rule change. |
+| **Meta** | Level map, stars, boosters/unlocks, daily board. |
+
+## Essential systems
+
+| System | Why this genre needs it |
+|---|---|
+| [[system-reward-schedules]] | Cascades and special-tile creation are variable-ratio payoffs; the "number goes up" surge is the retention engine. |
+| [[system-difficulty-and-dda]] | Difficulty is the *goal* tuned to measured bot win-rate — a distribution, not a rule tweak (see Content model). |
+| [[pattern-juice-choreography]] | The pop/fall/combo chain is the product; feel is timed to the deterministic script. |
+| [[pattern-feedback-loops]] | Cascades that spawn special tiles that trigger cascades — bounded so a lucky board doesn't auto-win. |
+| [[system-onboarding]] | Teach swap → match → cascade → special tile by doing, one mechanic per early board. |
+| [[system-collectibles]] | Stars, level completion, cosmetic boards — the optional pull past "cleared". |
+
+## Content & difficulty model
+
+- **Winnability is a distribution, not a switch.** Run a greedy matcher bot over N
+  seeds; read its win-rate; **tune the GOAL to the bot**, never the mechanics to a
+  fixed goal. A level is "hard" because the target sits high on the bot's curve.
+- **Board fairness is a connectivity proof.** Deal with no existing matches; assert a
+  legal move exists every turn; reshuffle when none does. This is the genre's
+  mechanical truth — prove it, don't eyeball it.
+- **Score accounting is an invariant.** `score === Σ (cleared × base × combo)`. One
+  pure scorer feeds sim, bot, tests, and the on-screen counter — same seam as the
+  city-builder's exposed score ([[genre-city-builder]]).
+- **Ramp by objective family:** score → clear-the-jelly → drop-the-anchor → limited
+  moves → blockers. New *constraint*, same swap.
+
+## Signature-mechanic seeds
+
+- **Match-3 but the board is a poker hand** — clears score as hands, jokers modify
+  multipliers (mechanic-swap toward [[anchor-balatro]]; the cascade *builds* the hand).
+- **Match-3 but gravity rotates** — swap the fall direction as a move; setups you
+  hold across a turn (mechanic-swap; the board becomes 4-directional).
+- **Match-3 but every clear is a step in a duel** — cascades power attacks against a
+  telegraphing foe; it's a rhythm-of-turns fight over a board (structure; pairs with
+  [[genre-rhythm]]'s "input-legality filter over a turn-based game").
+- **Match-3 but you place, not swap** — deal tiles onto the grid Tetris-style; the
+  bend moves the decision from finding a match to *engineering* one (mechanic-swap).
+- **Match-3 but tiles are a garden** — matched crops mature instead of vanishing; a
+  tonal + theme bend toward [[genre-farming-sim]]'s gentle solvency.
+
+## Common pitfalls
+
+- **Dealing pre-matches.** Free clears at deal cheapen the swap and desync score;
+  the fairness proof exists to forbid this.
+- **Tuning mechanics to a fixed goal.** Leads to unwinnable or trivial boards. Tune
+  the goal to the bot's measured curve instead.
+- **View drives sim.** Animating the cascade as it "decides" makes replay lie and
+  breaks `world.hash()`. Sim resolves to a script; view is a `cosmetic` observer.
+- **Runaway cascades.** Unbounded chain-of-specials means a lucky board auto-wins.
+  Cap combo scaling so skill still separates from luck.
+- **Special-tile soup.** Too many special types muddies the read. Introduce one per
+  objective family via [[system-onboarding]].
+
+## Anchors
+
+- [[anchor-peggle]] — maximal juice on a single trivial input; variable-ratio reward;
+  the "one shot, watch it pay off" fantasy the cascade shares.
+- [[anchor-balatro]] — the score-multiplier "number goes up" surge; the direct
+  reference for the poker-hand and joker seeds above.
+
+## Verify
+
+Board fairness sweep, score-accounting invariant, greedy-matcher hit-rate, golden
+session → **[docs/FUN.md §13 · Match-3](../../docs/FUN.md#13--match-3)**. Design the
+cascade here; prove fairness and the score invariant there.
+
+## Composes with
+
+- [[system-reward-schedules]] — the cascade payoff schedule that keeps a session pulling.
+- [[pattern-juice-choreography]] — the pop/fall/combo choreography timed to the script.
+- [[genre-rhythm]] · [[genre-farming-sim]] — natural blend targets for the seeds above.
+
+## See also
+
+- [docs/FUN.md §13](../../docs/FUN.md#13--match-3) — mechanical truth + verify recipe.
+- [docs/JUICE.md](../../docs/JUICE.md) — feel gates for the cascade choreography.
+- [`sandboxes/`](../../sandboxes/) — reach for the particles/tweens lab to wire the
+  pop-and-fall feel in isolation before building a whole board.

package/design/20-genres/metroidvania.md

@@ -0,0 +1,132 @@
+---
+id: genre-metroidvania
+title: Metroidvania
+kind: genre
+tags: [metroidvania, exploration, gating, ability, map, backtrack, locked-door]
+summary: The locked-door promise kept — a single connected world where every ability you earn retroactively unlocks a place you already saw and couldn't reach.
+use-when: Designing an interconnected exploration game whose progression is spatial — abilities as keys, the map as the meta-puzzle.
+composes-with: [system-progression, system-skill-trees, system-save-and-checkpoint, system-onboarding, system-boss-design, system-collectibles]
+anchors: [anchor-dead-cells, anchor-celeste]
+verify-with: docs/FUN.md#3--metroidvania
+---
+
+# Metroidvania
+
+**What it is.** One continuous world, not a level list. You explore, hit a
+**locked door** (a wall too high, a gap too wide, a gate keyed to an ability you
+don't have), and file it away. Later you earn the key — and the world you already
+walked opens up beneath you. The map is the real progression bar.
+
+**Player fantasy / why it's fun.** *"I remember this place."* The double-jump you
+just earned is a memory of a dozen ledges you eyed and left. Power is measured in
+*where you can now go*, and the world rewarding your growth feels like the world
+was waiting for you.
+
+## Pillars
+
+1. **The locked-door promise.** Every gate you can't pass is a promise the game
+   *will* let you pass it later — and keeps. Gates really gate; abilities really
+   open. A gate you can cheese breaks the contract (FUN.md §3 demands *negative*
+   proofs).
+2. **One connected world.** Not levels — a place. Shortcuts fold back, biomes
+   interlock, and the joy is holding the whole map in your head.
+3. **Ability as key and as verb.** Each unlock changes both *where* you go and
+   *how* you move/fight — a double-jump is a key to high ledges and a new combat
+   option at once. (Celeste's abilities do exactly this to its movement envelope.)
+
+## The loop stack
+
+| Scale | The loop |
+|---|---|
+| **Moment** | Traverse a room; test a gap; note "can't yet." |
+| **Encounter** | Reach an ability (often behind a boss/miniboss) → the room that teaches it → the first gate it opens. |
+| **Session** | Sweep a biome: open its gates, find its shortcuts, beat its guardian, leave with one new key. |
+| **Meta** | The whole map fills in; optional collectibles and sequence-breaks reward mastery of the geography. |
+
+## Essential systems
+
+| System | Why it's needed |
+|---|---|
+| [[system-progression]] | Abilities are the power curve; each is a discrete, world-changing unlock, not a stat bump. |
+| [[system-boss-design]] | Guardians gate abilities; the fight *is* the ceremony of earning the key. |
+| [[system-save-and-checkpoint]] | The world is persistent; save/load must round-trip the full map + unlock state (FUN.md §3 asserts the hash round-trip). |
+| [[system-onboarding]] | The room right after each ability must *force* its use — teach the verb before the world demands it. |
+| [[system-skill-trees]] | Optional: layer optional upgrades over the mandatory ability spine for build texture. |
+| [[system-collectibles]] | Off-the-critical-path secrets give the fully-powered player reasons to re-sweep the map. |
+
+## Content & difficulty model
+
+- **Gates need negative proofs.** The movement envelope is only a *lower* bound.
+  For every "you can't pass yet," simulate the best ungated maneuver against the
+  real geometry and show it falls short — otherwise a skilled player sequence-
+  breaks by accident and the promise means nothing (FUN.md §3).
+- **Design the map as a lock-and-key graph.** Author the ability order first, then
+  place gates so each new key opens exactly the doors that route the player
+  forward *and* backward into old regions. A progression-as-graph spine keeps it
+  provable.
+- **Room transitions must be clean.** Trigger inside the border, land past the far
+  threshold — no ping-pong at the seam (FUN.md §3).
+- **Backtracking must pay.** A revisited region should offer new reachability, a
+  shortcut, or a secret — never an empty walk. Fast-travel or folded shortcuts
+  respect the player's time once the geography is learned.
+
+Reference wiring: [`examples/sproutveil`](../../examples/sproutveil) — the
+room-connected exploration structure and the waypoint-bot pattern extended across
+rooms; [`examples/kintsugi`](../../examples/kintsugi) — the flagship whose five
+abilities each extend the movement envelope (the metroidvania spine).
+
+## Signature-mechanic seeds
+
+"X but Y" ([[process-the-twist]]) — bend the *key*, the *map*, or *who holds it*.
+
+- **Metroidvania but the map rearranges when you gain an ability** — new powers
+  re-lay the world, so backtracking is always into somewhere new. (structure)
+- **Metroidvania but abilities are spent, not kept** — a key opens one door then
+  is consumed; routing the map is a resource puzzle. (constraint)
+- **Metroidvania but the locked doors are in time, not space** — a "key" lets you
+  visit an earlier state of the same room. (perspective)
+- **Metroidvania but you play the world, not the hero** — you *place* the gates and
+  route an AI explorer. (perspective)
+- **Metroidvania but every gate is a promise you make to an NPC** — social access,
+  not physical, opens the map. (theme)
+
+## Common pitfalls
+
+- **Cheesable gates.** A gate the movement envelope can clear ungated is a broken
+  promise. Prove every gate *both ways* (ungated fails, gated passes) — FUN.md §3.
+- **Levels wearing a map costume.** Disconnected rooms with a fast-travel menu
+  aren't a metroidvania; the *interconnection* is the fun. Fold the world back on
+  itself.
+- **Empty backtracking.** Sending the player through cleared rooms with nothing new
+  is padding. Every revisit pays.
+- **Ability that's only a key.** If a new power opens doors but doesn't change how
+  you move or fight, it's a keycard, not a verb. Make it both (pillar 3).
+- **Save that loses the map.** Unlock/exploration state must survive save/load
+  exactly — assert the hash round-trip.
+
+## Anchors
+
+- [[anchor-dead-cells]] — metroidvania × roguelite; permanent unlocks over
+  impermanent runs (steal the unlock-as-key spine, drop the run structure if you
+  want the classic form).
+- [[anchor-celeste]] — abilities as movement-envelope changers; the traversal feel
+  a metroidvania needs under its map.
+
+## Verify
+
+Prove it with **[FUN.md §3 · Metroidvania](../../docs/FUN.md#3--metroidvania)** —
+bot full-run with abilities; both-ways gate proofs (best ungated maneuver fails,
+gated passes); save/load hash round-trip; clean room-transition triggers. Design
+the lock-and-key world here; prove the doors there.
+
+## Composes with
+
+- [[system-progression]] — abilities *are* the curve; pace their power.
+- [[system-boss-design]] — guardians as the gate ceremony.
+- [[genre-precision-platformer]] — the traversal feel under the exploration.
+
+## See also
+
+- [`examples/kintsugi`](../../examples/kintsugi) — the flagship metroidvania spine.
+- [`examples/sproutveil`](../../examples/sproutveil) — room-connected structure.
+- [`docs/FUN.md §3`](../../docs/FUN.md#3--metroidvania) — the proof playbook.