hayao 0.4.0 → 0.4.2

package/design/10-anchors/shadow-of-mordor.md

@@ -0,0 +1,106 @@
+---
+id: anchor-shadow-of-mordor
+title: Shadow of Mordor
+kind: anchor
+tags: [nemesis, emergent, systemic-memory, rivalry, procedural-narrative, personalization]
+summary: The nemesis system — a systemic hierarchy of enemies that remember you, rise from your failures, and become personalized rivals no writer scripted.
+use-when: The design wants antagonists (or allies) that persist, remember player history, and generate personal stories from systemic memory.
+composes-with: [genre-action-adventure, system-emergent-systems, system-enemy-ai, system-progression, pattern-emergence]
+anchors: []
+verify-with: docs/FUN.md#4-top-down-action-adventure-zelda-like
+---
+
+# Shadow of Mordor
+
+**What it is.** An open-world action game remembered for one thing: the **nemesis
+system**. Instead of interchangeable enemies, a **procedural hierarchy** of named
+captains *remembers* every encounter — the orc who killed you gets promoted and
+taunts you by name; the one you scarred returns disfigured and afraid. Kill,
+fail, or spare them and the power structure *rewrites itself*, authoring rivalries
+no writer wrote.
+
+**Player fantasy.** *Your* enemies, with *your* history. The pull is personal: an
+orc you barely escaped becomes a boss you *need* to settle, and the game remembers
+the whole grudge — the scar you gave him, the time he humiliated you. Emergent,
+personalized drama beats any scripted villain because it happened to *you*.
+
+## Design DNA
+
+The engine is **systemic memory turned into personality**. Three parts. First, a
+**living hierarchy**: a roster of named agents with ranks, traits, and
+relationships that persists and reshuffles ([[system-emergent-systems]]). Second,
+**memory of the player**: every meaningful interaction (a death, a wound, a flee)
+is *recorded on the agent* and *surfaced later* — the orc references it. Third,
+**player actions rewrite the structure**: killing a captain promotes a rival, and
+the graph reconfigures. The result is procedural narrative: the *system*
+generates the story, and personalization (names, scars, callbacks) makes it feel
+authored. This is the same family as [[anchor-rimworld]]'s director, aimed at
+*rivals* instead of crises.
+
+## Load-bearing structures
+
+| Structure | Why it works |
+|---|---|
+| **Named agents with persistent identity** | Enemies are individuals with names, traits, and ranks, not spawns — the prerequisite for any personal story. → [[system-emergent-systems]]. |
+| **Memory of player history** | Each agent records interactions (who killed whom, who fled) and *surfaces* them later ("you ran last time") — recognition is the magic. |
+| **A hierarchy that rewrites** | Killing/promoting reshuffles ranks; the world's power structure responds to your actions. → [[pattern-feedback-loops]]. |
+| **Traits generating behaviour & flavour** | Fears, strengths, and quirks drive both combat (exploit the fear) and dialogue (colour the taunt). → [[system-enemy-ai]]. |
+| **Callbacks / recognition** | The system *voices* its memory back at you — the moment "he remembers me" lands is where the fantasy pays off. |
+| **Systemic stakes** | Rivalries you built are the goals; you set your own targets from the emergent web. → [[pattern-emergence]]. |
+
+## What to steal
+
+- **Give enemies persistent identity + memory**: even a lightweight
+  name+trait+"last interaction" record turns spawns into rivals. This is the whole
+  trick, and it's cheaper than it looks. → [[system-emergent-systems]].
+- **Surface the memory back at the player**: recognition ("you fled from me
+  before") is where the emergence *becomes felt*. Record *and* replay.
+- **Let player actions rewrite the structure**: kills promote, defeats scar,
+  mercies create allies — a graph that responds makes the world feel alive.
+- **Traits do double duty**: one trait drives both a combat exploit and a
+  personality beat — mechanics and story from the same data. → [[pattern-emergence]].
+
+## What's just theme (drop it)
+
+- The **Tolkien/orc fiction** — the nemesis system is medium- and
+  genre-agnostic: rival racers, court factions, corporate rivals, roguelike
+  bosses. → [[world-theme-vectors]].
+- The **AAA open-world combat** — the memory system is separable; it can ride a
+  card game, a roguelike, a tactics game. It's data, not spectacle.
+- **Full voice acting** — flavour text assembled from traits achieves the callback
+  effect at a fraction of the cost.
+- **The specific rank ladder** — captains/warchiefs is one hierarchy shape; any
+  reshuffling structure (a bracket, a court, a leaderboard) works.
+
+## Composes into
+
+- [[genre-action-adventure]] — the parent action genre it shipped on (readable
+  combat; door/containment proofs).
+- [[system-emergent-systems]] — the canonical *nemesis/systemic-memory* case; this
+  anchor is its combat-rival exemplar (RimWorld is its crisis-director exemplar).
+- [[system-enemy-ai]] — traits driving behaviour and exploitable weaknesses.
+- [[system-progression]] — rivals rise as you do; the ladder is a difficulty curve.
+- [[pattern-emergence]] — story from a few interacting rules over persistent agents.
+
+## Twist seams
+
+- **Nemesis but for allies** *(perspective / tonal)* — a system of companions who
+  remember your kindnesses and grow loyal or resentful; systemic friendship, not
+  rivalry. Pairs with [[genre-narrative-decisions]].
+- **Nemesis but turn-based / roguelike** *(structure)* — bosses that persist
+  *across runs*, remembering how you beat them last time and adapting. Pairs with
+  [[system-meta-progression]].
+- **Nemesis but the memory is the mechanic you fight** *(mechanic-swap)* — enemies
+  literally learn your patterns and counter them; the twist is out-thinking a
+  system that studies you.
+- **Nemesis but at empire scale** *(scale)* — rival *nations* remember your
+  treaties and betrayals; systemic memory as diplomacy. Pairs with
+  [[anchor-civilization]].
+
+## See also
+
+- [`docs/FUN.md#4-top-down-action-adventure-zelda-like`](../../docs/FUN.md) —
+  readable telegraphs; hit-stop buffering; containment every frame — the combat
+  substrate the nemesis roster fights on.
+- [[system-emergent-systems]] · [[anchor-rimworld]] (the crisis-director sibling) ·
+  [[pattern-emergence]].

package/design/10-anchors/slay-the-spire.md

@@ -0,0 +1,127 @@
+---
+id: anchor-slay-the-spire
+title: Slay the Spire
+kind: anchor
+tags: [deckbuilder, roguelike, draft, map-choice, synergy, deck-thinning, run-based]
+summary: The roguelike deckbuilder — every card is a draft-of-3-or-skip, every fight thins or thickens your deck, and the map is a route of risk you choose in advance.
+use-when: Designing a run where the player's growing toolkit (a deck) IS the strategy, refined choice by choice against escalating threats.
+composes-with: [genre-deckbuilder, system-build-diversity, system-procgen-design, system-reward-schedules]
+anchors: [anchor-slay-the-spire]
+verify-with: docs/FUN.md#11-·-roguelike-deckbuilder
+---
+
+# Slay the Spire
+
+**What it is.** Climb a branching map, fighting turn-based card battles. After
+each fight, draft one card of three (or skip). Your deck is your build; the
+run is one long refinement of it against enemies whose damage you can read in
+advance.
+
+**Player fantasy / why it's fun.** *I am sculpting a machine and watching it
+come alive.* The pull is **the deck as an evolving strategy**: a pile of weak
+cards slowly becomes an engine, and the moment two cards click into a combo is
+the whole genre's dopamine. Every choice — which card, which path, which relic
+— compounds.
+
+## Design DNA
+
+Make **the growing toolkit the game**. The player doesn't level a character;
+they *curate a deck*, and every reward is a fork: take this card (and dilute
+your draw) or skip it (and stay lean). Wrap that in a **route of pre-visible
+risk** — a branching map where you choose your fights, elites, shops, and
+rests before you take them — and escalating enemies whose intents are *shown*,
+so losing is a planning failure, not a coin flip.
+
+The magic is **subtractive as well as additive**: a good deck is often a
+*small* deck. Thinning is a strategy, not just adding. This is the
+counter-intuitive core — most progression systems only grow, so "the reward
+you decline" and "the card you delete" are dead concepts. Slay the Spire makes
+*both* live decisions: the skip has teeth because every card you add dilutes
+the odds of drawing the ones you already want, and card-removal at shops is
+often the strongest purchase. Power is a function of *consistency*, and
+consistency is a function of *restraint*.
+
+Every layer — the draft, the map, the relics, the energy budget — is a
+decision made against *incomplete future information but perfect present
+information*. You never know the next reward, but you always know exactly what
+this fight will do.
+
+## Load-bearing structures
+
+| Structure | Why it works |
+|---|---|
+| **Draft-of-3-with-skip** | Every reward is a real decision — including the decision to *not* dilute. The skip is what makes drafting have teeth. FUN.md truth. [[system-reward-schedules]]. |
+| **Deck as build; thinning matters** | Power comes from *composition*, not stats. Removing weak cards is as strong as adding good ones. [[system-build-diversity]]. |
+| **Pre-visible branching map** | You choose the route (elite for a relic? shop? rest?) before committing — [[pattern-risk-reward]] made spatial. [[system-procgen-design]]. |
+| **Telegraphed enemy intents** | Each enemy shows next-turn damage/effect; combat is a solvable puzzle, not a gamble. Intent honesty is CI (FUN.md). [[system-telegraphs]]. |
+| **Relics = passive multipliers** | Persistent modifiers that warp the whole run's math and reward committing to an archetype. [[pattern-emergence]]. |
+| **Energy as the real constraint** | Cards are cheap; the per-turn energy budget forces every hand into a small optimisation. [[system-economy]]. |
+| **Win-rate window as the balance instrument** | Tune to a band (e.g. 11–19/20), not a point — both "too hard" and "too easy" break CI. |
+
+## What to steal
+
+- **Draft-of-N *with a skip*.** The skip converts "free reward" into
+  "meaningful decision." Steal this into any progression, not just cards.
+- **Make composition the power, and let subtraction be a strategy.** A leaner
+  deck/loadout should sometimes beat a bigger one.
+- **A pre-visible route of risk.** Show the map's fights/rewards ahead; make
+  the player commit to a path. This is portable to any run structure.
+- **Telegraphed intents** so every fight is solvable. Assert intent honesty as
+  a one-line audit (FUN.md).
+- **Balance to a win-rate window** (e.g. 11–19/20), not a point — both edges
+  break CI, since "too easy" is as broken as "too hard." Assert the draft
+  delta: same pilot drafting-off must lose far more (FUN.md's 17→9).
+- **A per-turn budget (energy) as the real constraint.** Cards being cheap to
+  acquire but limited to play per turn means every hand is a small
+  optimisation puzzle — the budget, not the card pool, is where tactical depth
+  lives. See [[system-economy]].
+
+## What's just theme (drop it)
+
+- **The spire / the Ironclad-Silent-Defect fiction.** Cosmetic; the loop is
+  theme-agnostic.
+- **Playing *cards* specifically.** The structure is "draft-refine a personal
+  toolkit of single-use actions." It could be spells, dishes, dance moves —
+  see [[system-build-diversity]].
+- **The relic art and names.** *Passive run-warping modifiers* is structural;
+  the trinkets are flavour.
+- **Fantasy monsters.** Any enemy that can *show its next move* satisfies the
+  telegraph truth — [[system-telegraphs]].
+
+## Composes into
+
+- [[genre-deckbuilder]] — its canonical anchor; the draft-refine loop lives
+  there.
+- [[system-build-diversity]] — deck-as-build with meaningful thinning.
+- [[system-procgen-design]] — the branching, pre-visible map.
+- [[system-reward-schedules]] — draft-of-3-with-skip cadence.
+- [[system-telegraphs]] — intent-driven, solvable combat.
+
+## Twist seams
+
+- **Slay the Spire but the deck is shared and you draft *against* an
+  opponent** *(perspective)* — every skip becomes a card denied to them; the
+  route is a contested board. Pushes toward [[system-coop-and-competition]].
+- **Slay the Spire but the map is the deck** *(mechanic-swap)* — you draft
+  *rooms* onto a path and then walk them; placement is the build. This is the
+  [[anchor-loop-hero]] bend.
+- **Slay the Spire but you can only ever hold 10 cards — every add forces a
+  cut** *(constraint)* — makes thinning mandatory, not optional; the whole run
+  is a rolling replace-decision. Sharpens the subtractive pillar into the core
+  verb.
+- **Slay the Spire but tonal — the deck is a diplomatic hand and fights are
+  negotiations** *(tonal)* — recolor combat as conversation; "damage" is
+  persuasion, "block" is patience, intents are the other party's next
+  argument. Keeps the draft-refine spine, swaps violence for stewardship.
+  Pairs with [[genre-narrative-decisions]].
+
+## See also
+
+- [[genre-deckbuilder]] · [[anchor-balatro]] · [[anchor-loop-hero]] ·
+  [[system-telegraphs]]
+- `docs/FUN.md#11-·-roguelike-deckbuilder` — win-rate window + draft-delta +
+  intent audit.
+- `examples/lanternfold/` — generated, all-channels reference (drafted content
+  pipeline).
+- `sandboxes/procgen-lab/` — `Rng`/`pickEntry` for weighted card & map
+  generation.

package/design/10-anchors/starcraft.md

@@ -0,0 +1,98 @@
+---
+id: anchor-starcraft
+title: StarCraft
+kind: anchor
+tags: [rts, asymmetry, faction, balance, macro, micro, matchup]
+summary: The gold standard of RTS faction asymmetry — three rosters that share almost no units yet balance across every matchup because each expresses one clear identity.
+use-when: The design needs deeply different sides that still play fair; you're building faction identity, not palette-swaps.
+composes-with: [genre-rts, system-faction-asymmetry, system-unit-rosters, system-counter-systems, system-mastery-curve]
+anchors: []
+verify-with: docs/FUN.md#9-rts-lite
+---
+
+# StarCraft
+
+**What it is.** An RTS whose reputation rests on one achievement: **three
+factions that share almost nothing** — different units, different economy quirks,
+different production models — yet stay balanced across all three matchups and
+mirror matches. Terran, Zerg, Protoss aren't reskins; they're three *answers to
+the same question* (how do I convert economy into a winning army?), and the
+answers stay fair.
+
+**Player fantasy.** You don't pick a colour, you pick an *identity* — the swarm
+that drowns you in cheap bodies, the machine-precise army that trades up, the
+elite few that each hit like a truck. Mastering a faction feels like learning a
+language; the matchup is a conversation.
+
+## Design DNA
+
+Asymmetry is a **promise about identity, balanced by a shared power budget**. Each
+faction gets a distinct *fantasy* (swarm / tech / elite) and a distinct *texture*
+(macro rhythm, unit feel), but every unit is priced against a common yardstick so
+no faction's answer dominates. The magic is that **different but fair** multiplies
+depth: three factions × three opponents = far more than three times the
+strategies, because each matchup has its own logic. See
+[[system-faction-asymmetry]] for the balancing discipline this demands.
+
+## Load-bearing structures
+
+| Structure | Why it works |
+|---|---|
+| **One faction = one identity** | Zerg *are* the swarm; Protoss *are* few-and-elite. A one-word fantasy keeps every unit on-theme and legible. → [[world-faction-identity]]. |
+| **Distinct production model per side** | Larva/hatch vs build-from-structure vs warp-in. The economy *feels* different, not just the units. |
+| **Shared power budget** | Cheap-but-weak and expensive-but-strong cost out to the same value; asymmetry without a hidden best side. → [[system-faction-asymmetry]]. |
+| **Matchup-specific logic** | ZvP ≠ ZvT ≠ PvT. Each pairing is its own puzzle; balance is per-matchup, not global. |
+| **Counter web, not counter list** | Units soft-counter across factions; comp and timing decide fights, not a lookup table. → [[system-counter-systems]]. |
+| **Macro/micro split as skill ceiling** | Economy management (macro) and unit control (micro) are separable skills; the ceiling is doing both at once. → [[system-mastery-curve]]. |
+
+## What to steal
+
+- **Identity-first faction design**: write the one-word fantasy *before* the unit
+  list. Every unit must express it or it doesn't belong. → [[world-faction-identity]].
+- **A shared power budget** as the balance instrument: price every asymmetric thing
+  against a common yardstick so "different" never means "better."
+- **Per-matchup balance**, not global: verify each faction-vs-faction duel wins its
+  own NvN (FUN.md §9), including the mirror.
+- **Separable macro/micro**: two skills the player improves independently gives a
+  long mastery curve with early wins available.
+
+## What's just theme (drop it)
+
+- The **sci-fi fiction** — bugs vs marines vs psionic knights is one dressing of
+  swarm/tech/elite. Fantasy, historical, or abstract carries the same spine.
+- **Exactly three** factions — three is a sweet spot (each matchup distinct,
+  still tractable), but the principle is "N identities on one budget," not the 3.
+- **The specific units** — a Zergling is a delivery mechanism for "cheap swarm
+  body." The role matters; the sprite doesn't.
+- **Hard-APM execution** — the *demand* for macro+micro is the ceiling; you can
+  raise it with automation without losing the strategic identity.
+
+## Composes into
+
+- [[genre-rts]] — the parent genre; StarCraft is its asymmetry exemplar.
+- [[system-faction-asymmetry]] — the home system; this anchor is its canonical
+  case study of "different but fair."
+- [[system-unit-rosters]] — three legible rosters, each a clear set of roles.
+- [[system-counter-systems]] — the cross-faction counter web.
+- [[world-faction-identity]] — the fiction that makes each side feel distinct.
+
+## Twist seams
+
+- **StarCraft but the factions are drafted mid-run** *(structure)* — roguelite:
+  each run you compose a roster from a pool, and the "faction" is your draft.
+  Pairs with [[system-build-diversity]].
+- **StarCraft but one hero, not an army** *(perspective)* — you *are* a single
+  unit inside the swarm/machine/elite fantasy; the faction becomes a class.
+- **StarCraft but no micro** *(constraint)* — armies auto-resolve; the whole game
+  is macro and comp. Pairs with [[genre-auto-battler]].
+- **StarCraft but the third faction is the map** *(mechanic-swap)* — an
+  environmental "faction" (creep, weather, tide) plays against both players as a
+  neutral asymmetric force.
+
+## See also
+
+- [`docs/FUN.md#9-rts-lite`](../../docs/FUN.md) — "strategy is the balance test";
+  every counter edge must win its NvN duel; flow-field mass pathing.
+- [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo) — wall-aware
+  mass movement the roster rides on.
+- [[system-faction-asymmetry]] · [[anchor-age-of-empires]] (economy-first cousin).

package/design/10-anchors/stardew-valley.md

@@ -0,0 +1,103 @@
+---
+id: anchor-stardew-valley
+title: Stardew Valley
+kind: anchor
+tags: [life-sim, farming, cozy, open-ended, compulsion-loop, calendar, progression]
+summary: Gentle life sim whose pull is a calm compulsion loop — open-ended goals, a daily rhythm, and "one more day" pacing that never punishes.
+use-when: The intent is a low-stress, open-ended progression game where the player sets their own goals and the loop is soothing, not tense.
+composes-with: [genre-farming-sim, system-progression, system-collectibles, system-economy, system-session-structure]
+anchors: []
+verify-with: docs/FUN.md#15-farminglife-sim
+---
+
+# Stardew Valley
+
+**What it is.** A life sim with **no fail state and no forced goal**. You inherit a
+farm and a town; a **daily loop** (wake, tend, forage, socialise, sleep) advances
+a calendar of seasons and festivals. Progress is broad and **self-directed** —
+farm, mine, fish, befriend, decorate — and every strand pays out on its own gentle
+schedule. The genius is *calm compulsion*: "one more day" without pressure.
+
+**Player fantasy.** A softer life you're quietly building. The pull isn't winning;
+it's tending — a plot filling in, a friendship deepening, a collection nearing
+complete. You always have three small things you *want* to do next, and none of
+them can go badly.
+
+## Design DNA
+
+The loop is **open-ended progression with a soft clock**. A day is a fixed budget
+of time/energy; the calendar (seasons, crop timers, festivals) gives structure and
+anticipation *without* threat. Many parallel goal-strands
+([[system-collectibles]], [[system-progression]]) mean the player always has a
+choice and never a dead end — if farming stalls, go fish. The compulsion is
+*variable-but-safe*: rewards come on legible timers, so you can always plan a
+satisfying tomorrow. Crucially, **calendar arithmetic is a hard inequality**
+(FUN.md §15): a season must be long enough to grow what it offers, or the calm
+breaks into frustration.
+
+## Load-bearing structures
+
+| Structure | Why it works |
+|---|---|
+| **Daily loop with a time/energy budget** | A fixed day forces gentle prioritisation; ending the day is a natural save/breather. → [[system-session-structure]]. |
+| **Seasonal calendar** | Seasons gate crops and stage festivals — anticipation and rhythm without a threat clock. → [[system-progression]]. |
+| **Parallel self-directed goals** | Farm/mine/fish/social/collect run in parallel; the player always has an appealing next thing and no dead end. → [[system-collectibles]]. |
+| **No fail state** | You can't lose the farm; setbacks cost a day, never a run. The safety *is* the genre. → [[pattern-anti-frustration]]. |
+| **Gentle solvency economy** | Plans that can come true: crop→sell→reinvest with margins that reward diligence, not optimisation. → [[system-economy]]. |
+| **Relationship meters** | Slow, warm progress bars on townsfolk; social as a collectible you tend over seasons. → [[system-emergent-systems]]. |
+| **Surfaced deadlines** | "Days left in season" is shown — the one number the player must plan around. (FUN.md §15). |
+
+## What to steal
+
+- The **no-fail soft clock**: a calendar that gives rhythm and anticipation while
+  *nothing can go badly*. This is the mood engine; guard it above all.
+- **Parallel goal-strands**: enough independent tracks that the player always has
+  three things they *want* to do and never a wall. → [[system-collectibles]].
+- **Gentle solvency**: an economy where diligence pays and optimisation isn't
+  required — reinvest-vs-hoard has a clear right answer but a soft penalty (FUN.md
+  §15's 740-vs-236 delta).
+- **Surface the one deadline** the player must plan around; hide the rest. Knowledge
+  the bot needed, the player needs.
+
+## What's just theme (drop it)
+
+- The **rural-farm fiction** — the loop is "tend parallel strands on a soft clock,"
+  which fits a bookshop, a spaceship, a garden, a shrine equally. →
+  [[world-theme-vectors]].
+- **Farming as the central verb** — it's one strand among many; a Stardew of
+  *fishing* or *repair* or *ritual* keeps the DNA. → [[process-the-twist]]
+  mechanic-swap.
+- **Combat/mines** — an optional pressure strand many cozy players skip. Cut it
+  before you cut the calm.
+- **Pixel-art / marriage / specific NPCs** — content and dressing on the
+  relationship-meter and collection systems.
+
+## Composes into
+
+- [[genre-farming-sim]] — the parent (gentle solvency, calendar as a hard
+  inequality).
+- [[system-progression]] — broad, self-directed power/skill growth across strands.
+- [[system-collectibles]] — sets, completion, decoration: optional goals with pull.
+- [[system-economy]] — the solvent, forgiving money loop that funds tending.
+- [[system-session-structure]] — the day as the session; the season as the
+  campaign.
+
+## Twist seams
+
+- **Stardew but a garden of grief** *(tonal + mechanic-swap)* — the calm loop
+  becomes coming-to-terms; each crop is a memory you eventually release. (The
+  worked example in [[process-the-twist]].)
+- **Stardew but a run ends the year** *(structure)* — roguelite seasons: you lose
+  the farm each year but keep meta-unlocks, turning cozy into a run loop. Pairs
+  with [[system-meta-progression]].
+- **Stardew but one plot, no expansion** *(constraint)* — a single tiny space you
+  perfect instead of sprawl; depth over breadth. Pairs with [[genre-grid-puzzle]].
+- **Stardew but two farmers, one day** *(perspective)* — coop where the shared
+  time-budget forces gentle coordination. Pairs with [[genre-coop-chaos]].
+
+## See also
+
+- [`docs/FUN.md#15-farminglife-sim`](../../docs/FUN.md) — season ≥ growDays +
+  slack; surface nights-left; reinvest-vs-hoard delta; golden year.
+- [[genre-farming-sim]] · [[anchor-rimworld]] (the tense-sim cousin) ·
+  [[pattern-anti-frustration]].

package/design/10-anchors/tetris.md

@@ -0,0 +1,122 @@
+---
+id: anchor-tetris
+title: Tetris
+kind: anchor
+tags: [endless, mastery, single-verb, falling-block, tuning, flow, difficulty-ramp]
+summary: The perfectly-tuned single verb — place falling tetrominoes to clear lines, forever, with a difficulty that rises with your own success.
+use-when: Designing for pure, endless mastery on one tight mechanic where the score curve and the skill ceiling ARE the game.
+composes-with: [genre-grid-puzzle, system-mastery-curve, system-difficulty-and-dda, pattern-mastery-and-flow]
+anchors: [anchor-tetris]
+verify-with: docs/FUN.md#1-·-grid-puzzle-sokoban
+---
+
+# Tetris
+
+**What it is.** Seven shapes fall one at a time; rotate and slot them so rows
+fill and clear. There is no end, no story, no unlock — just a board, a next
+piece, and a speed that climbs the longer you last.
+
+**Player fantasy / why it's fun.** *One more line.* The pull is **flow through
+mastery of a single verb**: the rules fit on a napkin, but the skill ceiling
+is bottomless, and the game tightens exactly as fast as you improve. It is the
+cleanest proof that depth doesn't need breadth.
+
+## Design DNA
+
+Take **one verb** — orient-and-drop — and tune it until it's perfect, then let
+*difficulty rise with the player's own success*. Every cleared line speeds the
+fall; skill buys you time that the game immediately taxes back. There's no
+meta, no content treadmill: the loop is so tight and so well-tuned that
+repetition *is* the reward. The randomiser (a bag of 7) keeps it fair; the
+failure state (stack to the top) is always your doing.
+
+The discipline here is *subtraction*. Tetris is the proof that **depth doesn't
+require breadth** — that a single verb, tuned to perfection, out-lasts games
+with a hundred mechanics. Everything that isn't the drop was cut: no story to
+gate the loop, no unlocks to pace it, no second verb to dilute the tuning
+budget. All of that budget goes into *feel* — the exact frames of lock delay,
+the DAS charge, the gravity curve, the rotation kicks — because when there's
+one verb, the game *is* its feel.
+
+This is the ur-example of **easy to learn, impossible to master** — the entire
+game is a mastery curve with the fat trimmed off. And the ramp is self-tuning:
+because speed scales with *your* clears, the game meets every player at their
+edge without a difficulty menu. The flow channel holds for a beginner and a
+world-record holder using the identical rule.
+
+## Load-bearing structures
+
+| Structure | Why it works |
+|---|---|
+| **One verb, perfectly tuned** | Orient + drop is the whole moveset. All design budget goes into *feel* — DAS, lock delay, gravity — not breadth. [[system-mastery-curve]]. |
+| **Success raises difficulty** | Clearing lines speeds the fall; the game auto-escalates to match you, so flow holds across skill levels. FUN.md law: the ramp is the design. [[system-difficulty-and-dda]]. |
+| **Self-inflicted failure** | You lose by stacking to the top — always legibly your mistake. No cheap deaths, so retry is instant appetite. |
+| **Bag randomiser** | The 7-bag guarantees fairness (no piece drought) while staying unpredictable — controlled randomness. All rng via `world.rng` (FUN.md law). [[system-procgen-design]]. |
+| **The next-piece queue** | Showing what's coming turns reflex into *planning* — a one-cell telegraph that opens the skill ceiling. [[system-telegraphs]]. |
+| **Lock delay + soft/hard drop as grace** | A frame window to slide/rotate before a piece sets — the grace canon that makes fast play fair. FUN.md law 5. [[system-grace]]. |
+| **The score as the whole meta** | No progression system; the leaderboard number is the entire long-term goal. [[system-collectibles]] (score-as-goal). |
+
+## What to steal
+
+- **Pick one verb and spend everything on its feel.** Lock delay, buffer,
+  gravity curve, rotation system — the tuning *is* the game. Depth without
+  breadth.
+- **Let difficulty rise with success.** Tie the ramp to the player's own
+  score/clears so flow self-corrects across all skill levels — no difficulty
+  menu needed.
+- **A fair randomiser (bag, not pure-random).** Guarantee no droughts so
+  failure is always skill, never luck. Route it through `world.rng`.
+- **A lookahead queue** to convert reflex into planning and lift the ceiling.
+  Showing the next piece (or several) is a one-cell telegraph that lets skilled
+  players *pre-solve* placements — depth added with zero extra rules. See
+  [[system-telegraphs]].
+- **Make the failure state self-inflicted and instantly re-enterable.** Cheap,
+  legible death is the engine of "one more go" — you always know *why* you
+  lost, and you're one keypress from trying again.
+- **Cut everything that isn't the verb.** Resist the urge to bolt on story,
+  meta, or a second mechanic; every addition steals tuning budget from the one
+  thing players actually feel. Scope discipline is the design.
+
+## What's just theme (drop it)
+
+- **The Soviet / cosmonaut branding.** Pure decoration.
+- **The specific 7 tetrominoes.** *A small alphabet of shapes with a fair bag*
+  is structural; the exact set is tuning — a hexagonal or pentomino variant
+  obeys the same DNA.
+- **The music (Korobeiniki).** Iconic, but the loop is silent-viable — it's a
+  [[pattern-juice-choreography]] layer, not a mechanic.
+- **The board being 10×20.** Dimensions are tuning, not law.
+
+## Composes into
+
+- [[genre-grid-puzzle]] — shares the grid-and-piece substrate (though endless,
+  not solved-level).
+- [[system-mastery-curve]] — the purest "easy to learn, hard to master"
+  exemplar.
+- [[system-difficulty-and-dda]] — success-driven auto-escalation.
+- [[pattern-mastery-and-flow]] — the flow channel held by a self-tuning ramp.
+- [[system-grace]] — lock delay / drop buffering.
+
+## Twist seams
+
+- **Tetris but the pieces are your deck** *(mechanic-swap)* — you
+  draft/upgrade which tetrominoes can appear; the bag becomes a build. Pulls
+  in [[genre-deckbuilder]] depth over the pure verb.
+- **Tetris but two boards share a rising garbage line** *(perspective)* —
+  clears send junk to a rival; the single-verb duel becomes competitive. Feeds
+  [[system-coop-and-competition]].
+- **Tetris but gravity is a resource you spend** *(constraint)* — you *choose*
+  when the piece falls, and hesitation costs a meter; converts reflex into
+  economy. Bends the auto-fall that defines the genre.
+- **Tetris but tonal — you're stacking to *build*, not to clear** *(tonal)* —
+  filling rows raises a tower/city that persists instead of vanishing; the
+  same orient-and-drop verb, recolored from anxiety-management into gentle
+  construction. Pairs with [[genre-city-builder]].
+
+## See also
+
+- [[genre-grid-puzzle]] · [[system-mastery-curve]] ·
+  [[pattern-mastery-and-flow]] · [[system-grace]]
+- `docs/FUN.md#1-·-grid-puzzle-sokoban` — determinism + replay for grid
+  pieces.
+- `docs/JUICE.md` — line-clear feedback (the pop that sells a good drop).