hayao 0.4.0 → 0.4.2

package/design/50-patterns/emergence.md

@@ -0,0 +1,121 @@
+---
+id: pattern-emergence
+title: Emergence
+kind: pattern
+tags: [emergence, second-order, systemic, interaction, depth, combinatorics, rules, synergy]
+summary: Depth from few pieces — design rules that interact, not content that stacks, so the game generates situations you never authored.
+use-when: You want combinatorial depth without infinite content; deciding between more rules or more interactions between rules.
+composes-with: [pattern-feedback-loops, pattern-risk-reward, system-emergent-systems, system-build-diversity]
+verify-with: docs/FUN.md#12-·-turn-based-tactics-into-the-breach-like
+---
+
+# Emergence
+
+**What it is.** **Emergent** depth comes from a small set of rules that *interact*,
+producing situations the designer never explicitly authored. The opposite of
+content-stacking (a thousand bespoke levels) is second-order design: a dozen verbs
+that combine into millions of states. Baba Is You has a handful of word-rules;
+Into the Breach has push, damage, and terrain — the *combinations* are the game.
+
+**Player fantasy.** *"I did something the designers didn't plan."* The improvised
+solution, the synergy you discovered, the story only your run could tell. Ownership
+of the *how*, not just the outcome.
+
+## Why it works
+
+- **Few pieces, deep space.** N interacting rules give ~N² interactions and far more
+  states — depth scales combinatorially while your content budget stays flat. This
+  is how a tiny game reads as vast.
+- **Discovery is the reward.** An interaction *you* found feels earned in a way a
+  handed-to-you unlock never does; it's the [[pattern-mastery-and-flow]] ceiling
+  with no assets attached.
+- **Systemic story beats scripted story** ([[system-emergent-systems]]) — the
+  nemesis who killed you twice and now taunts you is more memorable than any cutscene
+  because *you* co-authored it.
+
+## Levers
+
+| Lever | Effect | Example |
+|---|---|---|
+| **Rule orthogonality** | More rules combine cleanly | Push, fire, and water are independent → they interact |
+| **Shared state** | Systems that read each other | Water conducts electricity *and* extinguishes fire |
+| **Verb reuse** | One verb, many contexts | "Push" affects enemies, allies, terrain alike (ItB) |
+| **Consistency** | Interactions are predictable | Same rule everywhere; no exceptions to memorise ([[pattern-readability]]) |
+| **Legibility** | Players can *see* the interaction coming | Perfect-information telegraphs (FUN.md §12) |
+| **Feedback loops** | Interactions cascade | One rule feeds another ([[pattern-feedback-loops]]) |
+
+## Applied across genres
+
+| Genre | The interacting pieces | The emergence |
+|---|---|---|
+| **Rule-puzzle** ([[anchor-baba-is-you]]) | Word-rules you rewrite | Break "wall is stop" and the whole board reinterprets |
+| **Tactics** ([[anchor-into-the-breach]], [[genre-tactics]]) | Push · damage · terrain · fire | A shove that turns an enemy's attack onto its ally |
+| **Immersive-sim / exploration** ([[genre-exploration]]) | Systemic verbs (fire, water, gravity) | The unintended path through a level |
+| **Deckbuilder** ([[genre-deckbuilder]], [[anchor-balatro]]) | Cards/jokers that read each other | The synergy engine you drafted into existence |
+| **Colony / sim** ([[anchor-rimworld]]) | Needs · relationships · events | The AI director authoring drama from rule collisions |
+| **Systemic memory** ([[anchor-shadow-of-mordor]]) | Rivals with persistent state | The nemesis arc no writer scripted |
+| **Auto-battler** ([[genre-auto-battler]]) | Synergies + positioning | The comp that only works because two traits overlap |
+
+## Overdone when…
+
+- **Emergent chaos, not depth.** Interactions so tangled the player can't predict
+  them — that's noise, not systemic play. Legibility is the price of emergence
+  ([[pattern-readability]]): Into the Breach shows you *exactly* what every
+  interaction resolves to (FUN.md §12).
+- **Degenerate dominant combo.** One interaction is so strong it eats the space —
+  the emergent tree collapses to a single branch ([[system-build-diversity]] dead).
+- **Unfair emergence.** A rule collision that softlocks or one-shots the player
+  through no readable cause. Emergence must stay *fair*: the losing state should
+  have been foreseeable.
+- **Second-order for its own sake.** Interactions no player will ever hit aren't
+  depth, they're untested edge cases. Depth is the *reachable* combination space.
+- **Inconsistent rules.** An interaction that fires here but not there ("fire spreads
+  on grass, except this grass") breaks the mental model emergence depends on — the
+  player stops predicting and starts guessing. One rule, everywhere, no exceptions.
+
+## Verify / feel-gate link
+
+Emergence is where **perfect honesty** and **pure-state bots** earn their keep:
+
+- **Perfect information / intent honesty (FUN.md §12).** For emergent tactics, what
+  is shown must be exactly what resolves — store telegraphs as *directions* so a
+  push *rewrites* the outcome, and audit that the resolved state matches the shown
+  one. An interaction the player can't foresee is a bug.
+- **Mechanic-in-isolation proofs (FUN.md §12).** Prove each verb (push, bump,
+  redirect) alone, *then* trust the combinations — you can't unit-test N² states,
+  so you test the N rules and the pure sim guarantees the rest.
+- **Clone-and-score bots (FUN.md law 7).** Plain-JSON `world.state` lets a 1-ply
+  greedy bot explore the interaction space — it finds the degenerate combo before a
+  player does.
+- **Determinism (law 6/7).** Emergent cascades must be reproducible from the seed or
+  the systemic story can't be replayed or debugged.
+
+## Worked micro-example
+
+*"A tiny tactics game that feels vast on a four-verb budget."* Don't author a hundred
+bespoke enemies — author four **orthogonal** verbs (push, damage, fire-spread,
+water-conduct) and one **shared state** (tiles carry fire/water). The depth is in the
+collisions: shove an enemy into water to douse a fire, or into fire to burn it, or
+into *another enemy* to turn its telegraphed attack onto its ally. Nobody scripted
+"redirect a spider's web onto the tank" — the rules produced it. Keep it *fair* with
+legibility: show exactly what each interaction resolves to before the player commits
+([[pattern-readability]], FUN.md §12). Prove the verbs in isolation, then trust the
+N² space; run a greedy clone-bot to surface the degenerate combo before a player does.
+
+## Composes with
+
+- [[system-emergent-systems]] — this pattern is the *principle*; that system is the
+  concrete nemesis/reputation/relationship machinery. Read them together.
+- [[pattern-feedback-loops]] — the loops *between* interacting rules are what make
+  emergence cascade instead of fizzle.
+- [[system-build-diversity]] — emergence is only alive while many combinations stay
+  viable; a dominant combo kills it.
+- [[pattern-risk-reward]] — the best emergent moments are risky improvisations that
+  paid off.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §12 & law 7 — perfect-information honesty and
+  pure-state bots, the proofs that keep emergence *fair* and *explorable*.
+- [[anchor-baba-is-you]] · [[anchor-into-the-breach]] — the two clearest "the
+  mechanic IS the content" anchors.

package/design/50-patterns/feedback-loops.md

@@ -0,0 +1,121 @@
+---
+id: pattern-feedback-loops
+title: Feedback Loops
+kind: pattern
+tags: [feedback, snowball, comeback, runaway, balance, positive-loop, negative-loop, catch-up]
+summary: Positive loops snowball, negative loops correct — design which one dominates so leads stay tense, not decided.
+use-when: A lead is being built (economy, kills, board control) and you must decide whether it should compound or self-limit.
+composes-with: [pattern-risk-reward, pattern-pacing-and-tension, system-economy, system-difficulty-and-dda]
+verify-with: docs/FUN.md#part-1-—-universal-laws
+---
+
+# Feedback Loops
+
+**What it is.** A **feedback loop** feeds a system's output back into its own
+input. *Positive* loops amplify (a lead makes the next lead easier — a snowball);
+*negative* loops dampen (falling behind makes catching up easier — a rubber band).
+Every game with state has both; the design question is *which one dominates, and
+when*.
+
+**Why it's fun.** A pure snowball decides the match at minute two and the rest is
+a formality. A pure rubber band erases skill — why play well if the game hands it
+back? The fun lives in the **tension between them**: a lead that *matters* (so
+building it is exciting) but is *never safe* (so defending it stays tense). The
+[[system-mastery-curve]] skill-delta only reads as fun when a good lead is real
+and a comeback is possible.
+
+## Why it works
+
+- **A lead you can lose is a lead worth chasing.** If the snowball is uncatchable,
+  the loser stops trying and the winner stops sweating — both channels of tension
+  die at once.
+- **Loops are the engine of [[pattern-pacing-and-tension]].** Positive loops build
+  the peak; negative loops manufacture the valley (the comeback beat) without the
+  designer hand-scripting it.
+- **Runaway is a *bug you can prove*.** FUN.md law 2 (skill-delta) has a dark twin:
+  if the *winning* strategy's margin grows without bound across a session, a
+  bot-vs-bot sim shows the game deciding itself. Assert the lead is bounded, or
+  that a trailing bot's win-rate stays > 0.
+
+## Levers
+
+| Lever | Turns the loop… | Example |
+|---|---|---|
+| **Loop gain** (how much output re-feeds input) | Steeper positive → faster snowball | Kill → gold → item → more kills (MOBA) |
+| **Diminishing returns** | Caps a positive loop | Each territory worth less; XP curve inflates |
+| **Catch-up faucet** | Adds a negative loop | Last place gets the blue shell; comeback mechanic in fighting games |
+| **Loss forgiveness** | Softens the *negative* of falling behind | Bankruptcy protection; mercy income floor |
+| **Tempo of payout** | *When* the lead converts | Bank-it-now vs compound-later ([[pattern-risk-reward]]) |
+| **Information** | Whether players *see* the loop | An exposed "+N" lets players fight the snowball ([[pattern-readability]]) |
+
+## Applied across genres
+
+| Genre | Positive loop (snowball) | Negative loop (comeback) |
+|---|---|---|
+| **RTS** ([[genre-rts]]) | Eco lead → more army → more map → more eco | Defender's advantage; cheaper tech when behind |
+| **4X / city** ([[anchor-civilization]], [[genre-city-builder]]) | Cities fund cities; the classic runaway leader | War-weariness, unhappiness, upkeep scaling |
+| **Roguelite** ([[system-meta-progression]]) | Build synergy compounds mid-run | Death resets the run; meta-unlocks aid the *next* attempt, not this lead |
+| **Deckbuilder** ([[genre-deckbuilder]]) | An engine deck draws into itself | Deck bloat; scaling enemy damage punishes stalling |
+| **Horde survival** ([[genre-horde-survival]]) | Build growth is multiplicative | Spawn pressure is *superlinear* (FUN.md §6) — the tide is the negative loop |
+| **Racing** ([[genre-racing]]) | Clean line → speed → gap | Rubber-band AI; slipstream helps the trailer |
+| **Incremental** ([[genre-incremental]]) | Production buys production | Flat payback ratio (~15–25s) caps runaway (FUN.md §14) |
+
+## Overdone when…
+
+- **The snowball is uncatchable** — the leader wins on turn 3, the game plays out
+  a decided result. Add diminishing returns or a comeback faucet.
+- **The rubber band is visible and cheap** — players *see* the game handing back
+  their lead and stop caring. Comeback should widen the *chance*, not erase the
+  *gap* (the trailer gets a shot, not a gift).
+- **Catch-up punishes winning** — if leading is strictly bad (everyone sandbags to
+  avoid the target), the loop inverted. The lead must stay *desirable*.
+- **Two positive loops with no damper** — economy AND military both compound with
+  nothing pulling back; the match resolves before skill can express.
+- **A hidden loop** — the snowball is real but the player can't *see* it building, so
+  they can't fight it ([[pattern-readability]]). An exposed lead (the live "+N", the
+  score bar) turns a runaway from a fait accompli into a target.
+
+## Verify / feel-gate link
+
+Feedback runaway is a **skill-delta pathology** (FUN.md law 2): run the intended
+line *and* a trailing/null line and assert the trailing side keeps a non-zero
+win-rate across a session — a lead that grows unboundedly is the bot proving the
+game decides itself.
+
+- **Bounded-lead assert.** Sim two bots; assert the leader's margin stops growing
+  (or the trailer's win-rate stays > 0) — the negative loop is doing its job.
+- **Economy pacing.** For incremental/economy loops, the flat payback-ratio window
+  (FUN.md §14, [[system-economy]]) *is* the runaway gate — rising paybacks are an
+  unchecked positive loop strangling the late game.
+- **Determinism rail.** All loop randomness (catch-up rolls, blue-shell draws)
+  through `world.rng` (FUN.md law 7) or the balance sim can't reproduce the runaway.
+
+## Worked micro-example
+
+*"An RTS that never feels decided at minute two."* The core positive loop is eco →
+army → map → eco. Left ungated it's a hard snowball. Add three dampers: (1)
+**diminishing returns** — each expansion costs more to defend than the last; (2) a
+**defender's-advantage** negative loop — losing ground makes your remaining ground
+cheaper to hold; (3) an **information** lever — expose the score so the trailer can
+*aim* a comeback ([[pattern-readability]]). Now the lead is real (building it is the
+game) but never safe (defending it is the *other* game). Prove it: two bots, assert
+the leader's margin stops compounding and the trailer keeps a non-zero win-rate.
+
+## Composes with
+
+- [[pattern-risk-reward]] — *when* to bank a lead vs compound it is a risk decision
+  that rides on the loop's gain.
+- [[pattern-pacing-and-tension]] — loops *are* the mechanism that makes peaks and
+  valleys emerge instead of being scripted.
+- [[system-economy]] — faucets/sinks are the most common positive/negative loop pair.
+- [[system-difficulty-and-dda]] — dynamic difficulty is a deliberately-added
+  negative loop; tune it so it corrects without erasing skill.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) laws 2 & 7 — skill-delta and pure-state bots,
+  the tools that turn "does it snowball?" into an assertion.
+- [[anchor-civilization]] — the "one more turn" snowball-vs-comeback layering, done
+  as a whole game.
+- [[genre-incremental]] — the whole genre *is* a positive loop; its flat payback
+  window is the cleanest example of a damper holding runaway in check.

package/design/50-patterns/juice-choreography.md

@@ -0,0 +1,124 @@
+---
+id: pattern-juice-choreography
+title: Juice as Choreography
+kind: pattern
+tags: [juice, feel, feedback, choreography, particles, shake, cosmetic, two-senses, game-feel]
+summary: The sim resolves instantly and returns a choreography script; the view replays it — every event answers on ≥2 senses.
+use-when: Wiring feedback (impact, pickup, death) or deciding what belongs in the sim vs the view.
+composes-with: [pattern-readability, pattern-anti-frustration, pattern-pacing-and-tension, system-combat-model]
+verify-with: docs/JUICE.md#part-3-—-make-the-feel-checkable-channel-4-gates
+---
+
+# Juice as Choreography
+
+**What it is.** Feel is not decoration sprinkled on a sim — it's a **choreography**
+the sim *authors* and the view *performs*. The sim resolves an event instantly and
+returns a script (what happened, when); the view replays it as particles, shake,
+pops, and sound. FUN.md law 6, the **cosmetic-view rule**: views must be deletable
+without changing a single sim bit. Juice is loud *and* free of gameplay risk because
+it never touches the hash.
+
+**Player fantasy.** *"That hit felt like it mattered."* Weight, punch, satisfaction —
+the difference between clicking a spreadsheet and landing a blow. The game answering
+your input like it *heard* you.
+
+## Why it works
+
+- **The 2-senses feedback contract.** Every meaningful event answers on **≥ 2
+  senses** within the frame — sfx + particles, or sfx + flash + shake. One channel
+  reads as cheap; two reads as *professional* (JUICE.md Part 2). This is the single
+  highest-leverage feel rule.
+- **Choreography-not-state keeps determinism sacred.** Because the view reads sim
+  *events*, not state it feeds back, a replay reproduces the exact same show and
+  deleting the whole view changes not one game bit (FUN.md law 6). You can lean all
+  the way into juice at zero risk to the proofs.
+- **Timing is sim time.** Impact, beat, cascade timing is `world.time` / the fixed
+  `dt`, never wall-clock — so the choreography is reproducible and the hash holds
+  (JUICE.md Part 1).
+
+## Levers
+
+| Lever | The Hayao primitive | Envelope (JUICE.md Part 2) |
+|---|---|---|
+| **Screen shake** | `Shaker` (camera's parent) | land ≈ 0.12, death ≈ 0.5; quadratic falloff, decay ≈ 3/s |
+| **Hit-stop** | freeze frames on impact | sells weight; > ~12 frames reads as a hitch |
+| **Impact particles** | `Particles` + `PARTICLE_PRESETS` | answer an event, life 0.2–0.6s, then vanish |
+| **Pop numbers / pickups** | `FloatingText` + `FLOAT_PRESETS` | one pop per event; don't stack to soup |
+| **Atmosphere** | `AmbientField` + `AMBIENT_PRESETS` | *persistent* field (snow/ash), not a burst stream |
+| **Depth** | `ParallaxLayer` | 0 = far/pinned, 1 = foreground |
+| **Procedural SFX** | `audio.tone/blip/play/success` | pitch-rising combo; the second sense, cheaply |
+
+*(Grep [`docs/API.md`](../../docs/API.md) before citing — all of the above are real;
+[`examples/updrift`](../../examples/updrift) wires every one and passes all four feel
+gates.)*
+
+## Applied across genres
+
+| Genre | The signature choreography |
+|---|---|
+| **Physics arcade** ([[genre-physics-arcade]], [[anchor-peggle]]) | Pitch-rising ricochet chain, big burst on multipliers — the juice *is* the product |
+| **Action-adventure** ([[genre-action-adventure]]) | Hit-stop + flash + i-frame shimmer sell the blow (FUN.md §4) |
+| **Horde survival** ([[genre-horde-survival]]) | Screen full of pops on a level-up; the "number goes up" feast |
+| **Match-3** ([[genre-match3]]) | The purest law 6 — the deterministic sim returns the cascade *script*, the view animates it (FUN.md §13) |
+| **Deckbuilder** ([[anchor-balatro]]) | The score-multiplier crescendo; each joker its own beat |
+| **Precision platformer** ([[genre-precision-platformer]]) | Dust on land, shake on death, snappy landing — feel that rewards clean movement |
+| **Rhythm** ([[genre-rhythm]]) | Feedback *on the beat* — sim time drives both the hit and its flourish (FUN.md §18) |
+
+## Overdone when…
+
+- **Juice smothers the read.** Constant shake and particle spam bury the avatar and
+  the threat — feel that fights [[pattern-readability]]. Reserve the big
+  choreography for the big events (the 2-senses contract, not the 5-senses assault).
+- **Nausea shake.** Trauma that doesn't decay fast reads as motion sickness; the
+  feedback gate caps it (JUICE.md Part 2).
+- **Hitch hit-stop.** Freezes > ~12 frames read as a bug, not weight.
+- **Juice bound to state, not events.** If the view reads back state it influences,
+  determinism breaks and the replay diverges — law 6 violated. Wire to events.
+- **Seizure-bright / frantic.** The judge flags it as a *high*-severity juice-restraint
+  failure (JUDGE.md rubric 4).
+
+## Verify / feel-gate link
+
+Feel is made **checkable** — this is the whole point of Channel 4:
+
+- **Declare a `FeedbackContract`, then gate it** (JUICE.md Part 3):
+  `feedbackIssues(FEEDBACK, [...]).length === 0` asserts every listed event answers
+  on ≥ 2 senses with bounded juice. A silent one-channel event is now a failing test.
+- **Camera smoothness.** `cameraIssues(camSamples).length === 0` — no snaps or jerk
+  (the pattern's timing rail; JUICE.md Part 4 lists the frame-1 snap gotchas).
+- **Determinism (FUN.md law 6).** Run headless, hash; run with view, hash; assert
+  equal. Proves the choreography is cosmetic — the view is deletable.
+- **The vision judge (JUDGE.md rubric 4 & 5).** Juice restraint and motion clarity
+  are scored from the actual pixels — feel gates can pass while the *image* still
+  reads as noise; the judge closes that mile.
+
+## Worked micro-example
+
+*"A sword swing that feels like it lands."* The sim resolves the hit instantly and
+returns a script: `{ hit: true, at: pos, hitstop: 5, knockback: dir }`. The view
+performs it — `Shaker.addTrauma(0.12)`, a `PARTICLE_PRESETS.hit()` burst at `pos`, a
+5-frame freeze that *buffers* the next input through it, an `audio.tone` that pitches
+up on a combo, and a `FloatingText` damage pop. That's the **2-senses contract** met
+several times over (sfx + particles + flash + shake), all cosmetic, all driven off
+the *event* not read-back state. Delete the whole view and the sim hash is identical
+(FUN.md law 6). Prove it: run headless, hash; run with view, hash; assert equal — and
+`feedbackIssues(FEEDBACK, ['hit']).length === 0` guards the ≥2-senses rule.
+
+## Composes with
+
+- [[pattern-readability]] — juice must *serve* the read, never bury it; the two are
+  in constant tension and readability wins ties.
+- [[pattern-pacing-and-tension]] — reserve the loudest choreography for the peaks so
+  it stays meaningful.
+- [[pattern-anti-frustration]] — a death that *feels* clean (readable cause, quick
+  reset) is half feel, half forgiveness.
+- [[system-combat-model]] — hit-stop and i-frames are where the *shape of a hit* and
+  its choreography meet.
+
+## See also
+
+- [`docs/JUICE.md`](../../docs/JUICE.md) — the full cookbook; **the** reference for
+  this pattern. Copy from [`examples/updrift`](../../examples/updrift).
+- [`docs/FUN.md`](../../docs/FUN.md) law 6 — the cosmetic-view rule that makes juice
+  free.
+- [`sandboxes/juice-lab`](../../sandboxes/juice-lab) — the juice primitives in isolation.

package/design/50-patterns/mastery-and-flow.md

@@ -0,0 +1,121 @@
+---
+id: pattern-mastery-and-flow
+title: Mastery & Flow
+kind: pattern
+tags: [flow, mastery, challenge, skill, difficulty, engagement, learning-curve, skill-delta]
+summary: Keep challenge riding just above current skill — the flow channel — and prove it with the skill-delta gap.
+use-when: Setting difficulty, ramp, or the depth ceiling; deciding whether skill actually changes outcomes.
+composes-with: [pattern-feedback-loops, pattern-pacing-and-tension, system-mastery-curve, system-difficulty-and-dda]
+verify-with: docs/FUN.md#part-1-—-universal-laws
+---
+
+# Mastery & Flow
+
+**What it is.** **Flow** is the state where challenge tracks skill so closely that
+attention locks: too easy and the player is bored, too hard and they're anxious.
+The design job is to keep play inside that narrow **flow channel** as the player's
+skill climbs — the difficulty rises to meet a rising player. **Mastery** is the
+channel's ceiling: how far skill can keep buying results.
+
+**Player fantasy.** *"I'm getting better and the game noticed."* The near-miss that
+pulls you back in; the run where you finally read the pattern; the moment a wall
+becomes a warm-up. Time disappearing.
+
+## Why it works
+
+- **Boredom and anxiety are the two failure modes**, and they sit on either side of
+  the same line. Flow is the ridge between them; the ramp is how you walk it upward.
+- **The skill-delta *is* the flow proof.** FUN.md law 2: run the intended strategy
+  and a null strategy and assert the gap. That gap is the operational definition of
+  "skill matters here" — no gap, no channel, no flow, just noise. This is the fun
+  proxy the whole engine leans on.
+- **Learnable depth keeps the channel open.** A high skill *ceiling* ([[system-mastery-curve]])
+  means the player can keep climbing without you authoring infinite content —
+  Tetris has no level 900 assets, just a faster you.
+- **The channel is per-player, not per-game.** Two players of different skill both
+  deserve flow at once. You reach both by *widening* the channel (assist options, a
+  high ceiling over a gentle floor), not by picking one difficulty and hoping.
+
+## Levers
+
+| Lever | Moves the channel | Example |
+|---|---|---|
+| **Ramp slope** | How fast challenge rises | Level times/spawn curves that track completion |
+| **Skill ceiling** | How high mastery can climb | Tech, movement tech, combos, optimisation ([[system-mastery-curve]]) |
+| **Failure cost** | Anxiety dial | Instant retry (low) vs run-loss (high) — see [[system-grace]] |
+| **Onboarding** | Where the channel *starts* | Teach-by-doing so the floor isn't a wall ([[system-onboarding]]) |
+| **DDA** | Auto-centres the channel | Nudge difficulty to the measured player ([[system-difficulty-and-dda]]) |
+| **Assist / options** | Widens the channel per-player | Slow-mo, invincibility (Celeste); flow for more people |
+
+## Applied across genres
+
+| Genre | Where flow lives | The mastery ceiling |
+|---|---|---|
+| **Precision platformer** ([[genre-precision-platformer]]) | Each screen just past the last verb | Movement tech, optimal routing, deathless runs |
+| **Endless arcade** ([[anchor-tetris]], [[anchor-nuclear-throne]]) | The self-raising speed curve | Pure execution; the wall *is* the player |
+| **Bullet hell** ([[genre-bullet-hell]]) | Fire-lane uptime under rising density | Reading patterns, holding fire under pressure (FUN.md §7) |
+| **Tactics** ([[genre-tactics]]) | The optimal line hidden in a legible board | Perfect-clears; seeing three moves deep |
+| **Rhythm** ([[genre-rhythm]]) | Window accuracy vs chart density | Frame-tight timing, full-combo chains (FUN.md §18) |
+| **Racing** ([[genre-racing]]) | The line at the edge of grip | Braking discipline, the speed/line tradeoff (FUN.md §20) |
+| **Roguelite** ([[system-meta-progression]]) | Run knowledge + build reading | System mastery outpacing unlock power |
+
+## Overdone when…
+
+- **The wall with no ramp.** Difficulty jumps a cliff — anxiety, not challenge.
+  Break the spike into a slope ([[pattern-pacing-and-tension]]).
+- **The plateau.** Skill stops buying results (a hard cap, a dominant strategy) —
+  boredom. A collapsed [[system-build-diversity]] flattens the ceiling.
+- **Difficulty by unfairness.** Faster balls, more HP, coin-flip deaths — that's
+  *anxiety without skill expression*, the opposite of flow (FUN.md §7: density ≠
+  difficulty; §19: speed ≠ harder).
+- **DDA that erases skill.** Rubber-banding so hard that playing well is pointless
+  is a [[pattern-feedback-loops]] gone wrong — the channel should *centre*, not
+  *flatten*.
+- **A ceiling the player can't see.** Depth exists but nothing signposts it, so the
+  expert doesn't know there's more to climb ([[pattern-readability]]) — the mastery
+  is real but invisible, and invisible depth reads as a plateau.
+
+## Verify / feel-gate link
+
+Flow is not directly measurable, but its precondition — *skill changes outcomes* —
+is the single most important assertion in FUN.md:
+
+- **Skill-delta (law 2).** `expect(smartScore).toBeGreaterThan(nullScore * K)` —
+  greedy 158 vs random 82, judgement 19/20 vs recklessness 0/20, braking 26.2s vs
+  flooring 27.7s. No gap = no flow channel exists to walk.
+- **Ramp legibility.** Per-level bot completion times *expose* the ramp (FUN.md §2)
+  — a flat or inverted curve is a difficulty bug you can see in the numbers.
+- **Grace bounds anxiety (law 5).** Coyote/buffer/i-frames/instant-retry keep the
+  anxious side of the channel humane; spec them in frames and gate edge-in/edge-out.
+- **Mastery ceiling.** Pairs with [[system-mastery-curve]] — prove an *expert* line
+  meaningfully beats a *competent* one, not just skill vs null.
+
+## Worked micro-example
+
+*"A platformer that stays in flow for a beginner and an expert."* One difficulty
+number can't serve both — a floor for the beginner is a plateau for the expert. Widen
+the channel instead of moving it: (1) the *ramp* teaches each verb one screen before
+it's required ([[system-onboarding]]) so the floor isn't a wall; (2) a high **skill
+ceiling** — optional deathless/speed routes let the expert keep climbing
+([[system-mastery-curve]]); (3) **assist options** (slow-mo, invuln) widen the floor
+for players who'd otherwise fall out of the channel entirely ([[system-accessibility]]).
+Prove the ceiling with a two-tier skill-delta: an *expert* line meaningfully beats a
+*competent* one, not just skill vs null (FUN.md law 2).
+
+## Composes with
+
+- [[system-mastery-curve]] — this pattern is the *why*; that system is the *how* of
+  building a high, learnable ceiling. Read them together.
+- [[system-difficulty-and-dda]] — the mechanism that keeps the channel centred as
+  skill rises.
+- [[pattern-pacing-and-tension]] — flow over a session is a curve of peaks and
+  breathers, not a constant.
+- [[pattern-feedback-loops]] — the negative loop that stops a snowball is also what
+  keeps a match inside the flow channel for both players.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) law 2 — the skill-delta, the closest thing to
+  a fun proof and the operational test for "is there a flow channel here?".
+- [[system-onboarding]] — where the channel starts; a wall on frame one loses the
+  player before flow can begin.

package/design/50-patterns/pacing-and-tension.md

@@ -0,0 +1,120 @@
+---
+id: pattern-pacing-and-tension
+title: Pacing & Tension
+kind: pattern
+tags: [pacing, tension, rhythm, peaks, valleys, breather, session, curve, escalation]
+summary: Tension is a curve, not a constant — alternate peaks and breathers so the finale reads as a peak, not another wave.
+use-when: Shaping a session/level/wave/run; deciding difficulty and intensity over time, not just at one moment.
+composes-with: [pattern-feedback-loops, pattern-mastery-and-flow, pattern-risk-reward, system-session-structure]
+verify-with: docs/FUN.md#8-·-tower-defense
+---
+
+# Pacing & Tension
+
+**What it is.** Intensity over time is a **curve**, not a level you set once. A game
+that's flat-out from minute one exhausts; one that's flat-calm bores. The craft is
+**peaks and valleys** — escalating pressure punctuated by **breather beats** — so the
+session breathes, tension recovers, and the finale lands as the *peak* because you
+built up to it.
+
+**Player fantasy.** *"I can't stop — but I can catch my breath."* The pull of rising
+stakes, the relief of a lull, the dread of the next climb. A shape you feel even
+when you can't name it.
+
+## Why it works
+
+- **Tension needs contrast to exist.** A peak only reads as a peak against a valley;
+  constant maximum is just noise the player tunes out. The breather *makes* the spike.
+- **Breathers refill the flow tank.** Sustained challenge without recovery slides the
+  player from flow into anxiety and quitting ([[pattern-mastery-and-flow]]); the lull
+  resets attention so the next peak lands.
+- **The curve can emerge from loops.** [[pattern-feedback-loops]] and
+  [[pattern-risk-reward]] build peaks *without hand-scripting* — a snowball is a rising
+  slope, a push-your-luck run is a self-authored spike. Design the loop, get the curve.
+- **The valley is where the other systems breathe.** Downtime isn't dead time — it's
+  where the shop, the draft, the plan, and the story live. A game with no valleys has
+  nowhere to put its [[pattern-risk-reward]] decisions; the breather *is* the choice beat.
+
+## Levers
+
+| Lever | Shapes the curve | Example |
+|---|---|---|
+| **Escalation slope** | How fast pressure rises | Wave HP/spawn ramp; enemy density over a level |
+| **Breather placement** | Where the valleys sit | A runner wave; a safe room; a shop between fights |
+| **Peak spacing** | Rhythm of spikes | Mini-boss every N rooms; a crescendo mid-level |
+| **Finale weight** | The last peak is *the* peak | Gate on "finale is the max", not monotonicity |
+| **Session length** | The whole arc's footprint | Run vs level vs campaign ([[system-session-structure]]) |
+| **Downtime texture** | What a valley *does* | Loot, dialogue, planning, catching your breath ([[pattern-risk-reward]]) |
+
+## Applied across genres
+
+| Genre | The curve | The breather |
+|---|---|---|
+| **Tower defense** ([[genre-tower-defense]]) | Wave intensity climbs to a finale peak | Runner waves are the pressure break (FUN.md §8) |
+| **Horde survival** ([[genre-horde-survival]]) | Superlinear spawn ramp | The level-up pick pauses the tide (FUN.md §6) |
+| **Roguelite** ([[system-session-structure]], [[anchor-hades]]) | Room → room → elite → boss | The shop/reward room between fights |
+| **Bullet hell** ([[genre-bullet-hell]]) | Pattern density escalates per phase | Phase transitions (with mercy clears) reset (FUN.md §7) |
+| **Deckbuilder** ([[genre-deckbuilder]]) | Act → elite → boss | Rest sites; the map-choice planning beat |
+| **Survival horror** ([[genre-survival-horror]]) | Dread accrues on a fuel budget | The lit safe pocket at a traversal's midpoint (FUN.md §16) |
+| **Narrative** ([[genre-narrative-decisions]]) | Stakes rise across the reign | A quiet, low-Δ choice between crises |
+
+## Overdone when…
+
+- **Monotone escalation.** Every wave strictly harder than the last with no dip —
+  the player never recovers and the finale reads as "just another wave, but slower to
+  die". Gate on *shape* (each wave ≥ ~55% of the previous, finale peaks), not
+  monotonicity (FUN.md §8).
+- **All-breather / no spine.** Endless low-stakes downtime — the game never grips.
+  Valleys serve peaks; they aren't the point.
+- **Whiplash pacing.** Peaks and valleys with no ramp between — jarring, not
+  rhythmic. Ease into and out of spikes.
+- **The false finale.** The biggest fight sits mid-session and the ending fizzles —
+  the curve should *build* to its last peak.
+
+## Verify / feel-gate link
+
+Pacing is one of the few *aesthetic* concerns FUN.md makes into a hard assertion,
+via the wave-curve gate:
+
+- **Assert the shape, not monotonicity (FUN.md §8).** Gate on "each wave ≥ 55% of
+  the previous, finale peaks" — a *breathing* curve, with deliberate breather beats,
+  not a straight climb. Both CLAWSTRIKE and Norman the Necromancer pace waves with
+  explicit breathers (FUN.md §8).
+- **Pressure curve checklist (FUN.md Part 3).** "Wave/pressure curve breathes —
+  deliberate breather beats; finale is the peak; assert the shape" is a
+  before-you-author-content gate.
+- **No unlock deserts (FUN.md §14).** For incremental/economy arcs, the pacing
+  failure is a *desert* — a stretch with no new thing; balance-sim the whole arc and
+  assert no gap ([[genre-incremental]]).
+- **Session-length fit** ([[system-session-structure]]) — the curve must fit the
+  intended session footprint; a 40-minute arc in a 5-minute run has no room to breathe.
+
+## Worked micro-example
+
+*"A tower-defense run that builds to a finale instead of grinding flat."* The naive
+curve is monotone — every wave a little harder — and the "finale" reads as just a
+slower-to-die version of wave 12. Shape it instead: (1) **escalate** the combat waves
+in a rising slope; (2) drop a **runner wave** every third slot as a pressure break —
+a valley that lets the player retool and breathe; (3) weight the **finale** as the
+true peak, well above the prior maximum. Now the run has a shape you can feel. Prove
+it with the wave-curve gate (FUN.md §8): assert each wave ≥ ~55% of the previous and
+the finale peaks — a *breathing* curve, not a straight climb, and not monotonicity.
+
+## Composes with
+
+- [[pattern-feedback-loops]] — loops build the peaks and the comebacks *emergently*;
+  the curve falls out of the loop's gain.
+- [[pattern-mastery-and-flow]] — pacing is flow *over time*; breathers keep the
+  player on the ridge across a whole session.
+- [[pattern-risk-reward]] — push-your-luck is a self-authored tension spike; the
+  player draws their own curve.
+- [[system-session-structure]] — the container (run/level/campaign) sets the arc's
+  length and where its peaks can sit.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §8 (wave curves breathe) & §14 (no deserts) —
+  the two places pacing becomes an assertion.
+- [[anchor-hades]] — room-shop-room-boss rhythm as a whole-game pacing spine.
+- [[system-encounter-design]] — a single encounter has its own micro-curve (pressure
+  then pocket); pacing is that shape nested up to the session.