hayao 0.4.1 → 0.4.2

package/design/30-systems/economy.md

@@ -0,0 +1,117 @@
+---
+id: system-economy
+title: Economy — Faucets, Sinks & the Pacing Window
+kind: system
+tags: [economy, currency, faucets, sinks, inflation, balance, pacing, incremental]
+summary: Currencies flowing in through faucets and out through sinks; keeping the two in tension so the player is always almost-able-to-afford the next thing.
+use-when: The design has resources or currency the player earns and spends, and you need them to stay meaningful instead of trivial or crushing.
+composes-with: [system-resource-loops, system-progression, system-crafting, system-reward-schedules, system-meta-progression]
+anchors: [anchor-factorio, anchor-stardew-valley, anchor-civilization]
+verify-with: docs/FUN.md#14-incrementalidle
+---
+
+# Economy — Faucets, Sinks & the Pacing Window
+
+**What it is.** Every currency is a bucket with **faucets** (where it flows in)
+and **sinks** (where it drains out). The economy is the *ratio* between them over
+time. Get the ratio right and the player lives in a productive tension — always
+almost able to afford the next thing. Get it wrong and money is either worthless
+or a wall.
+
+**Player fantasy / why it's fun.** "I can *almost* afford it — one more run."
+A good economy makes desire renewable: the moment you can buy the thing, a better
+thing is just out of reach. The pull is the **pacing window** itself.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Earning and spending is a core loop (RPG, sim, incremental) | The game has no persistent resource (pure arcade, puzzle) |
+| You want the player pacing themselves via what they can afford | A flat unlock list reads clearer than a currency |
+| Multiple currencies segment progress into tracks | One currency would do — don't invent five |
+
+**Currency count is a tax.** Each currency the player must track is cognitive
+overhead. Add a second only when it *segments* meaningfully (soft vs premium,
+common vs prestige, run vs meta). Civilization's gold/science/culture each gate a
+different track; that earns its complexity.
+
+## Variants
+
+| Variant | Shape | Best for | Watch for |
+|---|---|---|---|
+| **Single currency** | One in, one out | Small games; clarity | Boredom if one sink dominates |
+| **Multi-currency** | Parallel buckets, separate tracks | Sims, 4X, gacha | Confusion; conversion loopholes |
+| **Convertible chain** | A → B → C ([[system-resource-loops]]) | Crafting, production | Bottleneck placement is the whole game |
+| **Closed loop** | Fixed total, only moves | Auto-battler gold; poker chips | No growth fantasy |
+| **Open (growth)** | Faucets > sinks by design | Incrementals, idlers | Inflation → late-game money is meaningless |
+
+## Tuning levers
+
+| Lever | What it controls | Healthy range / rule |
+|---|---|---|
+| **Faucet rate** | Income per unit time/effort | Tie to *effort/skill*, not idle time, or you've built a clock |
+| **Sink appetite** | How fast money leaves | Sinks must scale *with* faucets or inflation eats meaning |
+| **Payback ratio** (cost ÷ production) | Time to recoup a purchase | Keep ~flat per tier (**~15–25s** in idlers). Rising payback strangles the late game (**[[FUN.md §14]]**) |
+| **First-buy time** | The onboarding hook | Fast — the first affordable purchase within the first minute |
+| **Inflation control** | Whether late money matters | New, costlier sinks per era; or a prestige reset ([[system-meta-progression]]) |
+| **Currency count** | Cognitive load | As few as segment the game meaningfully |
+
+The discipline that defines a healthy economy is the **pacing window**: state the
+payback inequality as a law-3 constraint and *assert it holds across the whole
+arc* — no tier where the next purchase is a desert, none where it's instant
+(**[[FUN.md §14]]**, law 3).
+
+## How it wires to Hayao
+
+- **The ledger is state.** Balances live in `world.state`; every earn and spend is
+  an **input action** (`input.press`), *never* a direct mutation — this is the
+  exact rule incremental/idle lives by so replays don't lie (**[[FUN.md §14]]**).
+- **Balance-sim the whole arc.** Because state is pure JSON and rng flows through
+  `world.rng`, script a bot that plays the economy start-to-finish and assert the
+  pacing windows, monotone production, and *no unlock deserts* — the incremental
+  verify pattern. Grep `docs/API.md` for the ramp/pacing helpers
+  (`assertRamp`/`rampIssues`).
+- **The HUD is cosmetic.** Balance labels, floating "+N", coin sprites render on
+  `LAYER_HUD` and are `cosmetic = true` — deletable without changing
+  `world.hash()` (**[[FUN.md law 6]]**). The city-builder truth applies: the live
+  "+N under the cursor" is a *pure* score serving sim, bot, test, and label at
+  once (**[[FUN.md §17]]**).
+- **Shops/upgrade menus are chrome** — `showScreen()` DOM (CLAUDE.md invariant 4).
+
+## Fails when…
+
+- **Inflation.** Faucets outrun sinks; late-game money is meaningless and every
+  purchase is trivial. Scale sinks with faucets; add prestige resets.
+- **A desert.** A tier where the next thing costs far more than income can reach in
+  a fun span — the player grinds a solved loop. The payback assertion catches it.
+- **Idle-not-effort faucets.** Income from waiting, not playing, turns the game
+  into a timer. Tie faucets to skill/effort.
+- **Currency soup.** Five currencies where one would do; players lose the thread.
+- **A conversion loophole.** A → B → A at profit breaks a multi-currency economy —
+  prove no cycle nets positive.
+
+## Verify
+
+- Pacing windows, monotone production, no deserts, no click-softlock — the
+  incremental balance-sim: **[[FUN.md §14]]**.
+- Payback ratio as an asserted law-3 inequality across tiers: **[[FUN.md law 3]]**.
+- The exposed score as one pure function (sim = bot = test = label):
+  **[[FUN.md §17]]** (city-builder).
+- Reinvest-vs-hoard skill delta (740 vs 236): **[[FUN.md §15]]** (farming).
+
+## Composes with
+
+- [[system-resource-loops]] — the gather→convert→spend cycles the economy prices.
+- [[system-progression]] — XP/levels are one faucet–sink pair among many.
+- [[system-crafting]] — recipes are structured sinks with combinatorial payoff.
+- [[system-reward-schedules]] — the drip that fills the faucet.
+- [[system-meta-progression]] — prestige/meta currency as an inflation reset.
+- [[pattern-feedback-loops]] — income→buy→more income is the runaway loop to tame.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §14 (incremental pacing) · §15 (farming
+  solvency) · §17 (exposed score) — the three economy proofs.
+- `src/content/` + `assertRamp` — pace-as-data; balance-sim the arc, don't vibe it.
+- **[[anchor-factorio]]** (production economy) · **[[anchor-civilization]]**
+  (multi-currency tracks).

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

@@ -0,0 +1,114 @@
+---
+id: system-emergent-systems
+title: Emergent Systems
+kind: system
+tags: [emergence, nemesis, memory, relationships, reputation, systemic-story, story-generator, second-order]
+summary: Nemesis-style memory, relationships, and reputation — systemic story generators where the game remembers you and interactions author drama.
+use-when: You want stories the designer didn't script — rivalries, grudges, and reputations that arise from the player's own play.
+composes-with: [system-enemy-ai, system-faction-asymmetry, pattern-emergence, world-narrative-delivery]
+anchors: [anchor-shadow-of-mordor, anchor-rimworld]
+verify-with: docs/FUN.md#7-pure-data-state-pays-compound-interest
+---
+
+# Emergent Systems
+
+**What it is.** Systems that **remember and relate** so the game authors stories no
+designer wrote. The exemplar is Shadow of Mordor's **nemesis system**: an orc that
+kills you gets promoted, scars, and a grudge — and when you meet again, *the game
+remembers*. The family includes relationships (who likes whom), reputation (how the
+world treats you), and any **systemic memory** that turns a one-off event into an
+ongoing thread.
+
+**Player fantasy / why it's fun.** *A story that's mine because it happened to me.*
+Emergent drama beats scripted drama on ownership: the rival who humiliated you three
+runs ago carries weight no cutscene can. The pull is a world that reacts to your
+history, not a script that ignores it.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Replayability + memorable specific antagonists/allies | A tight linear story — scripting owns it |
+| The world should react to *your* history | Pure skill games where memory adds noise, not meaning |
+| You want stories from interaction, not authoring | You can't afford the systemic-consequence budget (it must *ripple*) |
+
+> **Memory only matters if it changes play.** A tracked grudge that never alters an
+> encounter is a stat, not a story. The nemesis is fun because the promoted orc is
+> genuinely *tougher and taunts you* — the memory has mechanical teeth
+> ([[process-the-twist]]: cosmetic signatures don't carry a game).
+
+## Variants
+
+| Variant | Remembers | Expresses as | Anchor |
+|---|---|---|---|
+| **Nemesis / rival** | who bested/fled whom | promoted, scarred, taunting foes | [[anchor-shadow-of-mordor]] |
+| **Relationship web** | who likes/loathes whom | mood, cooperation, feuds | [[anchor-rimworld]] pawns |
+| **Reputation** | your deeds toward a group | prices, aggression, access | RPG factions |
+| **World state memory** | choices & consequences | changed places, remembered NPCs | narrative games |
+| **Ecology / rivalry** | predator/prey, territory | shifting balance you disturbed | sim sandboxes |
+
+## Tuning levers
+
+| Lever | Effect | Watch for |
+|---|---|---|
+| **Memory salience** | how much the game references history | too little = forgettable; too much = nagging |
+| **Consequence magnitude** | how hard memory hits play | cosmetic memory = no story; brutal = punishing |
+| **Promotion/decay rules** | how relationships evolve | no decay = the web ossifies |
+| **Legibility of memory** | can the player *see* the history? | invisible memory reads as randomness |
+
+## How it wires to Hayao
+
+- **Memory is pure data.** Grudges, relationships, and reputation are plain JSON in
+  `world.state`, advanced through `dmath`, rolled through `world.rng` — so a
+  nemesis roster is part of `world.hash()`, saves, and replays for free (FUN.md
+  law 7). "Pure-data state pays compound interest": the *same* property that makes
+  a story generator deterministic makes it save/loadable and testable.
+- **The behavior hangs off [[system-enemy-ai]].** A promoted rival is an archetype
+  with a memory-derived stat block and a targeting bias toward *you* — same brain,
+  history-tuned numbers.
+- **Ordered iteration is mandatory.** Relationship/promotion resolution must iterate
+  in a deterministic order (by id), never by insertion or hash order, or the story
+  diverges between machines (CLAUDE.md invariant 2).
+- **Expression is often systemic narrative** — the memory shows up in the world,
+  not a text dump ([[world-narrative-delivery]]).
+- **A director can dramatize it.** `pollDirector` ([[system-difficulty-and-dda]])
+  can weight spawns toward a remembered rival's return.
+
+## Fails when…
+
+- **Memory with no mechanical consequence.** A tracked history that never changes an
+  encounter is a spreadsheet, not a saga.
+- **Non-deterministic resolution.** Iteration-order or wall-clock in the memory
+  update breaks `world.hash()` and desyncs the story.
+- **Illegible memory.** If the player can't perceive *why* a foe hates them, the
+  emergent story reads as random difficulty ([[pattern-readability]]).
+- **Runaway feuds.** No decay or bounds and relationships spiral into an unreadable
+  tangle ([[pattern-feedback-loops]]).
+- **Over-narration.** The system reminding you of every past event constantly kills
+  the surprise it exists to create.
+
+## Verify
+
+- **Determinism of the story:** golden-hash a scripted multi-run sequence; the
+  nemesis/relationship state must replay bit-exactly
+  ([FUN.md law 7](../../docs/FUN.md#part-1--universal-laws)).
+- **Save round-trip:** snapshot→restore→hash the memory state — a rivalry survives a
+  save intact (CONVENTIONS; [[system-save-and-checkpoint]]).
+- **Consequence delta:** assert a remembered rival is measurably harder / behaves
+  differently than a fresh spawn — memory has teeth (FUN.md law 2 skill-delta shape).
+- **Bounded evolution:** relationship/reputation values stay inside bounds across a
+  long sim (no runaway, per [[pattern-feedback-loops]]).
+
+## Composes with
+
+- [[system-enemy-ai]] — the behavior a memory-tuned rival runs.
+- [[system-faction-asymmetry]] — reputation and relationships across distinct groups.
+- [[pattern-emergence]] — the second-order design this is the flagship case of.
+- [[world-narrative-delivery]] — how the remembered story reaches the player.
+- [[system-difficulty-and-dda]] — a director can stage a rival's return.
+
+## See also
+
+- [`docs/FUN.md` law 7](../../docs/FUN.md#part-1--universal-laws) — pure-data state as the enabler.
+- [[anchor-shadow-of-mordor]] — the nemesis system, distilled.
+- [[anchor-rimworld]] — relationships + a director as a story engine.

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

@@ -0,0 +1,107 @@
+---
+id: system-encounter-design
+title: Encounter Design
+kind: system
+tags: [encounter, combat, pacing, pressure, safe-pocket, exit-lane, waves, composition]
+summary: Composing archetypes into a fight — pressure and safe pockets, exit lanes, and a wave curve that breathes.
+use-when: You have enemy roles and need to arrange them into a specific fight that reads, pressures, and resolves fairly.
+composes-with: [system-enemy-archetypes, system-enemy-ai, system-difficulty-and-dda, system-boss-design]
+anchors: [anchor-into-the-breach, anchor-vampire-survivors]
+verify-with: docs/FUN.md#5-stealth
+---
+
+# Encounter Design
+
+**What it is.** The **arrangement** of enemies, space, and time into a single
+fight. If [[system-enemy-archetypes]] is the alphabet, an encounter is the
+*sentence*: which roles, in what count, entering from where, with what geometry —
+and crucially, where the player can **breathe**. A fight is a rhythm of **pressure
+and pocket**, not a constant scream.
+
+**Player fantasy / why it's fun.** The satisfaction of *reading a room and solving
+it live*. A great encounter poses a legible problem, ramps the pressure, gives one
+honest window to recover, then peaks. FUN.md §5's "plannable danger" is the whole
+ideal: the player should be able to route the fight, not just survive noise.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Hand-authoring set-piece fights or rooms | Endless horde — that's a *pressure curve* (§6), tune the director not the room |
+| A boss arena with adds | The fight IS one entity — go to [[system-boss-design]] |
+| Roguelike rooms assembled from parts | Pure puzzle levels — that's solver-authored (§1) |
+
+## The anatomy of an encounter
+
+| Element | The design question | Failure mode |
+|---|---|---|
+| **Composition** | which archetypes, how many? | all-tank slog / all-swarm noise |
+| **Ingress** | where do they enter, in what order? | everything at once → no read |
+| **Pressure curve** | does intensity rise, then peak? | flat = boring; monotone-hard = unfair |
+| **Safe pocket** | where can the player recover mid-fight? | none = a war of attrition, not a fight (§5) |
+| **Exit lanes** | are doors/escape routes obstacle-free? | cover in the door row = **softlock** (§4) |
+| **Resolution** | how does it end — clear, timer, objective? | ambiguous end = the fight overstays |
+
+## Tuning levers
+
+| Lever | Turns up… | Watch for |
+|---|---|---|
+| **Enemy budget** (a points cost per role) | raw difficulty | cheap way to overshoot — cap it |
+| **Ingress cadence** | how fast the room fills | dumping all at frame 0 kills the read |
+| **Pocket size / duration** | recovery generosity | zero pocket = frustration; huge pocket = no tension |
+| **Arena geometry** (pillars, funnels) | kiting arcs & LoS breaks | a pillar in an exit lane softlocks (§4) |
+| **Composition ratio** | the *kind* of pressure | shift ratios to reface a reused arena |
+
+## How it wires to Hayao
+
+- **Encounters are data.** A room is a list of spawns + positions in `world.state`,
+  fed to the shared archetype behaviors. Timed ingress rides
+  `pollDirector(waves, state, world.time, world.rng)` — a repeating wave with an
+  `end` is a controlled trickle, a one-shot wave is an ambush
+  ([`src/content/dsl.ts`](../../src/content/dsl.ts)).
+- **Geometry legibility** is a lint, not a vibe: `astarGrid`/`connectedComponents`
+  (grep `docs/API.md`) prove exit lanes stay traversable and every enemy can reach
+  the player — cover in a door row shows up as an unreachable path.
+- **Procedural rooms** compose from proven parts: `generateDungeon` /
+  `generateLevels` (see [[system-procgen-design]]) with a per-room accept rule that
+  every spawn is reachable and a pocket exists.
+- **Wave curve** shares the tower-defense breather math — see
+  [[system-difficulty-and-dda]] for `assertRamp`/`rampIssues`.
+
+## Fails when…
+
+- **No safe pocket.** A long fight with nowhere to recover is attrition, not
+  skill — FUN.md §5 requires a pocket at the *midpoint* of any long traversal.
+- **Blocked exit lanes.** A pillar or an enemy parked in a door row is a softlock;
+  keep door rows/columns clear (§4).
+- **Everything at once.** Simultaneous ingress erases the read — the player never
+  gets to *solve* the room, only flail.
+- **Flat pressure.** No rise, no peak → the fight is texture, not an arc
+  ([[pattern-pacing-and-tension]]).
+- **Joint-phase waits** (stealth): chaining two guard windows that must *both*
+  align makes wait times explode (§5) — chain single windows.
+
+## Verify
+
+- **Both-ways affordance / safe pocket:** the stealth proof pattern — punished
+  exposure AND concealment-holds AND a mid-path pocket
+  ([FUN.md §5](../../docs/FUN.md#5-stealth)).
+- **Beatable:** a bot clears the encounter deathless with hp floor ≥ comfortable
+  ([FUN.md §4](../../docs/FUN.md#4-top-down-action-adventure-zelda-like)).
+- **Curve breathes:** assert the pressure *shape* (each wave ≥ ~55% of prior,
+  finale peaks) with `rampIssues`, not monotonicity ([FUN.md §8](../../docs/FUN.md#8-tower-defense)).
+- **Exit lanes clear:** reachability lint over the actual room geometry (FUN.md Part 3).
+
+## Composes with
+
+- [[system-enemy-archetypes]] — the letters this arranges into sentences.
+- [[system-enemy-ai]] — the behaviors that animate each spawn.
+- [[system-difficulty-and-dda]] — encounters are the units a director sequences.
+- [[system-boss-design]] — a boss arena is an encounter with a super-archetype.
+- [[pattern-pacing-and-tension]] — pressure/pocket is pacing at fight scale.
+
+## See also
+
+- [`docs/FUN.md` §4/§5/§8](../../docs/FUN.md) — readable combat, plannable danger, breathing waves.
+- [`src/content/dsl.ts`](../../src/content/dsl.ts) — director-driven ingress.
+- [[anchor-into-the-breach]] — the perfectly legible, fully telegraphed encounter.

package/design/30-systems/enemy-ai.md

@@ -0,0 +1,121 @@
+---
+id: system-enemy-ai
+title: Enemy AI
+kind: system
+tags: [ai, behavior, aggro, threat, steering, flow-field, pathfinding, kiting, telegraph]
+summary: Readable, beatable enemy minds — aggro/threat, steering, and pathing that the player can predict, route around, and outplay.
+use-when: A design needs enemies that move and decide, and you want them to feel intelligent without being unfair or opaque.
+composes-with: [system-enemy-archetypes, system-encounter-design, system-telegraphs, system-difficulty-and-dda]
+anchors: [anchor-nuclear-throne, anchor-shadow-of-mordor]
+verify-with: docs/FUN.md#4-top-down-action-adventure-zelda-like
+---
+
+# Enemy AI
+
+**What it is.** The **decision + movement** an enemy runs each tick: who to
+target, whether to press or retreat, and how to get there without walking into a
+wall. Good enemy AI is not *smart* — it is **legible**. The player must be able to
+read its intent, predict its next move, and beat it with position and timing.
+
+**Player fantasy / why it's fun.** The fantasy is *outwitting a mind*. That only
+lands if the mind is knowable: a shark that telegraphs its lunge is thrilling; one
+that teleports behind you is cheap. The skill the player buys is *reading and
+routing* — FUN.md §4's kiting bot exists because "the enemy is beatable by
+positioning" is a provable claim.
+
+## When to use / when NOT
+
+| Use it when | Skip it / go simpler when |
+|---|---|
+| Enemies must chase, flank, or hold ground | Bullet-hell foes: they emit **patterns**, not decisions (§7) — script the pattern, not a brain |
+| The player's skill is spacing & threat-reading | Pure puzzle enemies: they're **rules**, deterministic and solver-legible (§1, §12) |
+| You want emergent pressure from a few archetypes | A single scripted boss: hand-author phases ([[system-boss-design]]), don't build a general AI |
+| Mass units under command (RTS) | One enemy, one behavior: a state flag beats a behavior tree |
+
+> **Never build a mind the player can't read.** Perfect aim, wall-hacks, and
+> reaction-time-zero are the difficulty of a slot machine. Difficulty comes from
+> *count, geometry, and telegraph windows* — not from the AI cheating.
+
+## Variants
+
+| Variant | The mind | Reads as | Best for |
+|---|---|---|---|
+| **Direct seeker** | steer straight at the target | "it wants me" | swarms, zombies (§6) |
+| **Flow-field mass** | one BFS per goal, every unit follows the field | "the tide is coming" | RTS-lite, hordes (§9) |
+| **Kiter / spacer** | hold a preferred range, back off when close | "keep your distance" | archers, ranged skirmishers (§4) |
+| **Ambusher** | wait in a state until a trigger, then commit | "don't step there" | stealth, traps (§5) |
+| **State-machine bruiser** | idle → aggro → windup → attack → recover | "here comes the swing" | melee bosses, mini-bosses (§4) |
+| **Threat-driven** | pick target by an aggro/threat score, not proximity | "I pulled it" | party fights, taunt play |
+
+## Tuning levers
+
+| Lever | Turns up… | Watch for |
+|---|---|---|
+| **Aggro radius** | when the enemy notices you | too large = no safe pockets ([[system-encounter-design]]) |
+| **Threat weights** | *who* it targets (damage dealt, distance, taunt) | must be deterministic & ordered — ties break by entity id, never by iteration order |
+| **Preferred range** (kiters) | the spacing the fight settles at | range < player reach = it's just a melee foe |
+| **Windup / telegraph frames** | the reaction window before a hit | too short = unreadable; own this in [[system-telegraphs]] |
+| **Steering deadzone** | jitter vs. commitment near the target | too tight = enemies vibrate on the spot |
+| **Repath cadence** | how fast it reacts to you moving | every frame = twitchy & expensive; every N frames = readable |
+
+## How it wires to Hayao
+
+- **Pathing:** `astarGrid` and `floodFill` (grep `docs/API.md`) give per-enemy
+  paths and wall-aware reachability. For **mass** pathing, one BFS per goal tile
+  cached *outside* `world.state` is the flow field (FUN.md §9) — hundreds of units
+  share it. `connectedComponents` proves a goal is even reachable before you spawn
+  a chaser that would path into nothing.
+- **Steering:** `steer2D(px,py,tx,ty,out,dead)` emits the same action strings a
+  human would press, so an enemy and a bot driver share one movement path — and
+  the enemy replays deterministically. The `dead` deadzone is your jitter lever.
+- **Threat/aggro:** plain data in `world.state` — a per-enemy target id and score,
+  advanced through `dmath`, ordered iteration for ties. No wall-clock, all rolls
+  through `world.rng`.
+- **See it in isolation:** [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo/)
+  — `astarGrid`/`floodFill` with paintable walls and a movable goal, no genre
+  attached. Learn the primitive there, not from a whole game.
+
+## Fails when…
+
+- **The mind cheats.** Perfect prediction, seeing through walls, or homing that
+  can't be dodged. The FUN.md §7 dodge-bot exists precisely to prove a human
+  *can* survive; an enemy that beats the bot is unfair to people too.
+- **No safe pocket.** Every enemy aggros at once with no gap to breathe → it's a
+  wall of pressure, not a fight ([[system-encounter-design]], FUN.md §5).
+- **Iteration-order targeting.** Picking a target by array order leaks
+  non-determinism into the sim and breaks `world.hash()`. Order by an explicit
+  key.
+- **Repathing every frame** — cost spikes and the enemy twitches; humans read
+  *committed* motion, not a gradient-follower recomputing constantly.
+- **Melee foes that outrun you with no telegraph** — the fight becomes a coin
+  flip, not a read.
+
+## Verify
+
+- **Beatable by positioning:** the kiting-bot telemetry pattern — win time, hp
+  floor ≥ comfortable, **0 deaths** — is the proof an enemy roster is fair
+  ([FUN.md §4](../../docs/FUN.md#4-top-down-action-adventure-zelda-like)).
+- **Reachability first:** `connectedComponents` / flow-field over the actual
+  geometry before spawning chasers ([FUN.md §9](../../docs/FUN.md#9-rts-lite)).
+- **Feel floor:** every attack telegraphs before its hitbox goes live — the
+  readability gate in [`src/verify/gates.ts`](../../src/verify/gates.ts) checks it.
+- **Determinism:** golden-hash a scripted encounter; targeting and steering must
+  replay bit-exactly (FUN.md law 6/7).
+
+## Composes with
+
+- [[system-enemy-archetypes]] — AI is the *how it moves*; archetypes are the
+  *what role it plays*. Same brain, different stats, different feel.
+- [[system-telegraphs]] — a readable mind is mostly a well-telegraphed one; the
+  windup frames live here.
+- [[system-encounter-design]] — one enemy is a behavior; a fight is a *composition*
+  of them with pressure and pockets.
+- [[system-difficulty-and-dda]] — aggro radius and count are the director's dials.
+- [[pattern-readability]] — the salience floor that makes a mind knowable.
+
+## See also
+
+- [`docs/FUN.md` §4/§7/§9](../../docs/FUN.md) — kiting, dodge-bot fairness, flow fields.
+- [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo/) — the pathing primitive alone.
+- [[anchor-nuclear-throne]] — tight-loop enemies whose danger is *count + read*, never cheating.
+- [[anchor-shadow-of-mordor]] — where a readable mind grows a *history* ([[system-emergent-systems]]).

package/design/30-systems/enemy-archetypes.md

@@ -0,0 +1,117 @@
+---
+id: system-enemy-archetypes
+title: Enemy Archetypes
+kind: system
+tags: [enemy, archetypes, roles, tank, skirmisher, artillery, swarm, support, roster]
+summary: The enemy alphabet — tank/skirmisher/artillery/swarm/support — a small set of roles that combine into fights bigger than their parts.
+use-when: You need a legible enemy roster where each foe demands a different answer and pairs interact.
+composes-with: [system-enemy-ai, system-encounter-design, system-unit-rosters, system-counter-systems]
+anchors: [anchor-vampire-survivors, anchor-into-the-breach]
+verify-with: docs/FUN.md#4-top-down-action-adventure-zelda-like
+---
+
+# Enemy Archetypes
+
+**What it is.** A **role vocabulary** for enemies, not a bestiary. Five roles cover
+almost every action game: **tank** (soaks, blocks lanes), **skirmisher** (fast,
+flanks, punishes greed), **artillery** (ranged, forces you to close or break line
+of sight), **swarm** (individually trivial, dangerous in numbers), **support**
+(buffs/heals/shields others — the *priority* target). The alphabet is small on
+purpose: a player learns five answers, then every fight is a *sentence* of them.
+
+**Player fantasy / why it's fun.** Recognition, then adaptation. Seeing an
+artillery unit behind a tank behind a swarm is a *puzzle you read at a glance* —
+the fun is choosing the order to solve it. FUN.md §4's whole claim is "readable
+combat"; archetypes are how a fight becomes readable before it becomes hard.
+
+## When to use / when NOT
+
+| Use it when | Skip it when |
+|---|---|
+| Combat has ≥3 enemy types and you want them to *combine* | A single-enemy game (one boss, one rival) — design that fight directly |
+| You need difficulty from *composition*, not stat inflation | Puzzle "enemies" that are really rules ([[genre-grid-puzzle]], §12) |
+| The player should learn one answer per role | Pure horde where the enemy is *count itself* — one type, superlinear spawn (§6) |
+
+## Variants
+
+The five roles and what each *demands*:
+
+| Role | Job in the fight | Player answer | Signature knob |
+|---|---|---|---|
+| **Tank** | control space, absorb, block a lane | reposition or burst; don't trade | HP + a lane it denies |
+| **Skirmisher** | punish overextension, flank | spacing, patience, don't chase | speed > player, low HP |
+| **Artillery** | force movement, deny camping | close the gap or break LoS | range + a telegraph ([[system-telegraphs]]) |
+| **Swarm** | overwhelm, chip, cover others | AoE, funnels, kiting arcs (§6) | trivial each, superlinear count |
+| **Support** | multiply everyone else | **kill it first** — it's the priority | a buff radius you can see |
+
+**Compositions** are where the alphabet earns its keep:
+
+| Pair | Emergent problem |
+|---|---|
+| Tank + artillery | the tank buys the artillery time; you're pressured while you dig |
+| Support + swarm | the swarm won't die until the support does — inverts your target order |
+| Skirmisher + tank | the tank pins you where the skirmisher wants you |
+| Artillery + skirmisher | ranged forces motion, flanker punishes it — a positioning vice |
+
+## Tuning levers
+
+| Lever | Effect | Watch for |
+|---|---|---|
+| **Role stat ratios** (HP/speed/range) | how sharply a role reads | roles that overlap muddy the read — keep silhouettes distinct |
+| **Threat priority** (support first) | the target-order puzzle | if killing in any order works, the roles aren't interacting |
+| **Count per role** | swarm-ness vs. elite-ness | one "swarm" unit is just a weak melee foe |
+| **Telegraph length by role** | reaction budget | artillery needs the longest tell; skirmishers the shortest |
+
+## How it wires to Hayao
+
+- An archetype is **data**: a stat block in `world.state` (`hp`, `speed`, `range`,
+  `role`) driving the shared behaviors from [[system-enemy-ai]]. Same brain,
+  different numbers — a tank is a seeker with high HP and a wide body; a kiter is
+  the ranged archetype.
+- **Spawning by role** rides the director: `WaveDef.spawn` takes a weighted set,
+  so `pollDirector(waves, state, world.time, world.rng)` (grep `docs/API.md`) can
+  roll "2 swarm + 1 support" per firing, deterministically. See
+  [`src/content/dsl.ts`](../../src/content/dsl.ts).
+- **Silhouette & palette** carry the read — distinct shapes and Kentō-palette
+  hues per role ([[world-aesthetic-direction]], JUDGE). The player must name the
+  role from the silhouette alone.
+- **Roster legibility** shares the design of [[system-unit-rosters]] — the enemy
+  roster is a roster with the same "one glance, one role" bar.
+
+## Fails when…
+
+- **Stat-only enemies.** Five foes that differ only in HP are one enemy with a
+  slider. Roles must demand *different answers*, not different patience.
+- **No priority target.** Without support (or an equivalent "kill this first"),
+  every fight is a spray — order stops mattering.
+- **Illegible silhouettes.** If you can't tell artillery from tank at a glance,
+  the read collapses ([[pattern-readability]], JUDGE).
+- **Swarm that isn't a swarm.** Too few, too tanky, and it's just chip damage with
+  extra steps — swarm fun is *many trivial* (§6).
+
+## Verify
+
+- **Each role beatable with its answer:** kiting-bot telemetry per archetype —
+  0 deaths, hp floor ≥ comfortable
+  ([FUN.md §4](../../docs/FUN.md#4-top-down-action-adventure-zelda-like)).
+- **Composition, not inflation:** assert a *skill delta* — the correct target
+  order clears far faster than a naive one (FUN.md law 2). If order doesn't
+  matter, the roles don't interact.
+- **Swarm pressure holds:** `peak alive ≥ N` so the horde feel can't silently
+  regress ([FUN.md §6](../../docs/FUN.md#6-twin-stick-horde-survival-vampire-survivors-like)).
+- **Readability gate:** telegraph-before-hitbox in [`src/verify/gates.ts`](../../src/verify/gates.ts).
+
+## Composes with
+
+- [[system-enemy-ai]] — the shared brain each archetype re-skins with stats.
+- [[system-encounter-design]] — archetypes are letters; encounters are the words.
+- [[system-counter-systems]] — roles imply near-hard counters (AoE vs. swarm).
+- [[system-unit-rosters]] — the same legibility discipline, player-side.
+- [[system-boss-design]] — a boss is often a super-archetype with phases.
+
+## See also
+
+- [`docs/FUN.md` §4/§6](../../docs/FUN.md) — readable combat; horde pressure.
+- [`src/content/dsl.ts`](../../src/content/dsl.ts) — `WaveDef`/`pollDirector` role spawning.
+- [[anchor-vampire-survivors]] — the swarm archetype as the *whole* game.
+- [[anchor-into-the-breach]] — every enemy role telegraphed as a solvable board.