@ericrisco/rsc 0.1.35 → 0.1.36

package/skills/level-design/evals/README.md

@@ -0,0 +1,35 @@
+# Eval harness — level-design
+
+These evals assert two things about the `level-design` skill. **Triggering:** it
+fires on level layout, pacing, encounter, guidance, and reward requests, and
+stays out of systemic mechanic/economy design (`game-design`), narrative
+(`game-storytelling`), and engine-specific level tooling (`godot`/`unity`/
+`unreal`). **Capability:** when engaged, it delivers the craft — the
+blockout→art pipeline, the sawtooth intensity graph with breathers, the
+introduce→develop→twist→combine teaching pattern, light/color/affordance
+guidance, and observe-don't-coach playtesting — rather than generic advice.
+
+## How to run
+
+Run through an agent harness with skills loadable on demand; `cases.yaml` is the
+fixture. Use the same model for every trial; vary only which skills are loaded.
+
+- **Triggering:** load the full catalog so the agent can route to siblings; feed
+  each `should_trigger` / `should_not_trigger` prompt verbatim and record which
+  skill fires. Run 3–5 trials per prompt (the choice is stochastic).
+  - Pass: `should_trigger` selects **level-design** in the majority of trials;
+    `should_not_trigger` does not (ideally routes to the listed `route_to`).
+  - Bar: **≥90%** trigger accuracy across all prompts.
+- **Capability:** run each scenario WITH only level-design loaded vs WITHOUT any
+  skill (baseline), 3 times each. Grade responses against the `must_include`
+  rubric, one point per checkable item genuinely present.
+  - Bar: WITH covers **≥80%** of items on average AND beats WITHOUT by **≥25**
+    percentage points (a skill that doesn't move the needle fails).
+
+## Notes / honesty
+
+- LLM-graded and stochastic — re-run on edits; treat small deltas as noise.
+- `route_to` targets assume the sibling skills (`game-design`,
+  `game-storytelling`, `godot`, `unity`, `unreal`) exist in the catalog; a
+  missing sibling can cause a near-miss to mis-route without it being a
+  level-design fault — note it, don't count it against this skill.

package/skills/level-design/evals/cases.yaml

@@ -0,0 +1,58 @@
+skill: level-design
+
+should_trigger:
+  - prompt: "I've built the first level of my platformer but playtesters say it's boring in the middle and then brutal at the end. How do I fix the pacing?"
+    why: "Direct pacing complaint on a built level — the intensity-graph / sawtooth + breather guidance. 'Boring in the middle, brutal at the end' is a flat-then-spike curve the skill diagnoses."
+  - prompt: "Players keep getting lost in my second map — they wander into dead ends and can't find the exit. What am I doing wrong?"
+    why: "Navigation/readability failure ('players get lost') — the skill's guidance layer: landmarks, light-led critical path, denying wrong turns visually. Lostness is a readability bug the skill owns."
+  - prompt: "How should I lay out the blockout for a new FPS arena before I start making art?"
+    why: "Explicit blockout request and the blockout->greybox->playtest->art pipeline plus metrics block and arena-shape design. Core Use-when trigger."
+  - prompt: "I want to teach the player how a new grappling-hook mechanic works through the level itself, without a tutorial popup. How do I structure that?"
+    why: "Teaching a mechanic through space = introduce->develop->twist->combine. The mechanic itself is game-design's, but structuring the SPACE that teaches it is level design."
+  - prompt: "Where should I put the secret rooms and the best loot in my dungeon so exploring feels rewarding but not frustrating?"
+    why: "Reward & secret placement + risk/reward + breadcrumbing. 'Rewarding but not frustrating' is exactly the reward-the-observation-not-the-pixel-hunt guidance."
+  - prompt: "My combat arena feels like everyone just hides behind one wall and pokes out. How do I make the fights more dynamic?"
+    why: "Arena-shape design: static peek-war means missing flanks/verticality and bad cover rhythm. The skill's encounter/arena section addresses this directly."
+  - prompt: "How do I guide players toward the objective using lighting and color instead of a giant waypoint marker?"
+    why: "Guidance without hand-holding via light/color/composition and the reserved interact-color language. Explicit 'instead of a waypoint' framing is the skill's core."
+
+should_not_trigger:
+  - prompt: "How high should the player be able to jump and how much should double-jump cost stamina? I'm balancing the movement system."
+    route_to: "game-design"
+    why: "This is the movement RULE/economy itself (systemic mechanic + stamina cost tuning), which game-design owns. Level design consumes the jump metric; it doesn't set or balance it."
+  - prompt: "Write the environmental storytelling and the audio-log script for the abandoned lab area to reveal the backstory."
+    route_to: "game-storytelling"
+    why: "Narrative content — what the space SAYS (backstory, audio-log writing). Level design places the beat; game-storytelling authors it."
+  - prompt: "How do I bake the nav mesh and set the agent radius so enemies path around my level geometry in Unity?"
+    route_to: "unity"
+    why: "Engine-specific level tooling (nav-mesh bake, agent radius in Unity). Explicitly out of scope; the engine skill implements the layout the design decided."
+  - prompt: "My Godot TileMap isn't showing collision on the ground layer and the player falls through. How do I fix it?"
+    route_to: "godot"
+    why: "Engine tooling bug — TileMap collision setup in Godot. This is implementation, not the craft of layout/pacing/readability."
+  - prompt: "How should I design the loot rarity tiers and drop-rate curves for the whole game's economy?"
+    route_to: "game-design"
+    why: "Loot-table / economy systems design across the whole game — a systemic concern game-design owns, not the placement of a reward within one level's space."
+  - prompt: "How do I optimize the frame rate in my Unreal level — the shadows and draw calls are tanking performance?"
+    route_to: "unreal"
+    why: "Engine performance/rendering optimization (draw calls, shadow cost) is engine tooling, owned by the unreal skill, not level-design craft."
+
+capability:
+  - scenario: "A designer says: 'My level's first playthrough is fun but by the middle testers get bored and then the final room feels unfairly hard. It's already fully textured and lit. How do I fix it?'"
+    must_include:
+      - "Diagnoses a flawed intensity curve (flat/boring middle, spike at the end) and prescribes a sawtooth: peaks with breathers/safe rooms between, difficulty trending up with checkpoint resets."
+      - "Recommends adding a breather/safe room after peaks so intensity drops and the next peak reads, and varying encounter length/spacing to kill the monotony."
+      - "Flags that the level is already textured/lit as a process problem — layout changes should be validated in blockout/greybox, and warns that art-first makes pacing fixes expensive."
+      - "Frames the final-room spike as a telegraph/difficulty-curve issue (signpost the ramp, reset at a checkpoint) rather than just lowering difficulty."
+  - scenario: "A developer asks: 'Players keep getting lost in my level and walk right past the exit. I don't want to add a waypoint arrow. How do I guide them?'"
+    must_include:
+      - "Treats lostness as a readability/guidance bug, not player error, and keeps guidance diegetic (no waypoint)."
+      - "Uses light to lead (players move toward light/contrast; light the critical path, objective, and exit; keep dead-ends dim)."
+      - "Establishes a dominant landmark per area for self-location and frames the exit with composition/leading lines."
+      - "Recommends a reserved, consistent accent color for interactables/path used nowhere decoratively, and consistent affordances."
+      - "Prescribes watching a fresh, uncoached playtester (and/or position/dwell heatmaps) to locate exactly where players hesitate or diverge, without answering 'where do I go?'."
+  - scenario: "A designer asks: 'I have a new mechanic — a portal gun — and I want the level to teach it without any text tutorial.'"
+    must_include:
+      - "Lays out the introduce -> develop -> twist -> combine progression (or equivalent teach-through-space structure)."
+      - "Introduces the mechanic somewhere it cannot hurt the player (safe, zero-risk first encounter) before any real stakes."
+      - "Builds up through low-stakes use, a recontextualizing twist, and a final combine/mastery test that layers earlier learning."
+      - "Notes that the space itself teaches (no tutorial popup) and that the mechanic's rules belong to game-design while the teaching layout is level design."

package/skills/level-design/references/blockout-to-art.md

@@ -0,0 +1,118 @@
+# Blockout to art — the pipeline in detail
+
+The single most expensive mistake in level design is committing art before the
+space is proven. This reference details each stage, the metrics block that
+everything is built from, how to playtest a grey box, and the handoff to the
+engine skill and art team.
+
+## Why art goes last
+
+A blockout is minutes to change; a finished, textured, lit set-piece is days.
+Layouts *always* change under playtest — a corridor is too long, a fight needs a
+flank, a landmark isn't visible from the entrance. If that geometry is already
+art, every fix throws away work and creates pressure to *not* fix it. Art-first
+levels ship with known layout problems because nobody wants to redo the art.
+So: prove the space grey, then dress it.
+
+## Stage 1 — Blockout (whitebox)
+
+Build the level from **primitive geometry at true scale** — boxes, planes,
+cylinders, ramps. No materials beyond a flat neutral, no props, no final
+lighting. A single neutral mid-grey with a subtle grid texture is ideal: it
+shows scale and stops you from judging the level on looks it doesn't have yet.
+
+You are answering three questions:
+
+1. **Flow** — can the player move through the intended route without snagging?
+   Are the loops, gates, and shortcuts where you planned?
+2. **Timing & distance** — how long is the walk between beats? Are jumps and
+   gaps possible and fair? Is a corridor a slog or a snappy connector?
+3. **Legibility** — from each decision point, is the next objective findable by
+   shape and layout alone (before any lighting/color tricks)?
+
+Block out the **critical path first**, walk it end to end many times, then add
+exploration branches and encounters. Keep everything modular and snapped to a
+grid so pieces move cheaply.
+
+## The metrics block (lock this before any geometry)
+
+Every dimension in the level is a multiple of the player's capabilities. Define
+these **first**, in engine units, and build to them. Guessing metrics is how you
+get gaps that feel wrong and cover that doesn't protect.
+
+| Metric | What it governs | Typical relationship |
+|---|---|---|
+| **Player height (standing)** | Ceiling clearance, door height, sightline height | The base unit; doors ~1.3–1.5× |
+| **Crouch height** | Vents, low cover, crawl spaces | ~0.5–0.6× standing |
+| **Eye height** | What sightlines actually reveal (camera, not feet) | Slightly below standing top |
+| **Shoulder / capsule width** | Corridor and doorway minimum width | Corridors ≥ 2× so two can pass / strafe |
+| **Jump height** | Max step-up, ledge height, low-cover top | Cover just below eye so you can peek |
+| **Jump distance (gap)** | Platform spacing, chasm width | Design gaps at ~70–85% of max so they read as fair |
+| **Reach / grab height** | Climbable ledge height, mantling | Set the climb-ledge trim to this exact height |
+| **Run speed** | Travel time between beats, breather length | Distance = speed × intended seconds |
+| **Weapon/threat effective range** | Arena sightline length, cover spacing | Long lanes for ranged, short for melee |
+
+Write these into `02-DOCS/wiki/stack/level-design.md` (see the SKILL.md grounding
+section) so every level in the project shares one metrics block. When a metric
+is a *rule* of the game (how high the player jumps at all), that number is owned
+by `game-design`; level design *consumes* it here and builds space to fit.
+
+## Stage 2 — Greybox
+
+Refine the blockout just enough to test *reading* and *feel*:
+
+- **Temp neutral materials** to distinguish floor/wall/hazard/interactable by
+  value, not decoration.
+- **Placeholder lighting** used as a *design* tool — light the path, the
+  objective, and the exit; keep non-paths dim. This is where guidance is
+  authored, long before final art lighting.
+- **Stand-in enemies, cover, pickups, and interactables** at real metrics so
+  encounters and the reserved interact-color language can be tested.
+
+Now the questions are: does the space *read*? Does the encounter work? Is the
+pacing right? Greybox is still cheap — you are still iterating layout, not
+protecting art.
+
+## Stage 3 — Playtest the grey box
+
+Do this early and often, on the blockout/greybox, because fixes are cheap. Full
+observation protocol and telemetry live in `guidance-and-readability.md`; the
+blockout-specific loop is:
+
+1. Sit a **fresh, uncoached** player down. Say only "play". Stay silent.
+2. Log every **hesitation** (readability gap), **wrong turn** (navigation gap),
+   **repeated death** (telegraph/difficulty gap), and **skipped area** (reward
+   or guidance gap).
+3. Never answer "where do I go?" — that question is your top finding.
+4. Change the grey geometry/lighting, re-test. Repeat until it plays.
+
+Only when the greybox plays well for players you didn't coach do you unlock art.
+
+## Stage 4 — Art pass (and the handoff)
+
+Art *serves the proven layout*. The reserved interact-color, the light-led path,
+the framed landmark, the readable silhouettes — art must **reinforce** the
+guidance the greybox already established, never fight it. If the art pass makes
+the level prettier but harder to read, it failed.
+
+Hand off to the engine skill (`godot` / `unity` / `unreal`) for the tooling that
+turns the layout into a shippable level:
+
+- Nav-mesh generation and agent radius (must match the capsule width above).
+- Occlusion culling / visibility and streaming volumes.
+- Final lighting: lightmap/GI bakes, reflection probes, light-leak fixes.
+- Collision meshes distinct from render meshes; blocking volumes replacing the
+  greybox's implicit walls.
+- LODs, mesh instancing, and performance budgets.
+
+### Art-pass handoff checklist
+
+- [ ] Layout is locked — no pending "this fight might move" notes.
+- [ ] Metrics block is final; art meshes respect door/corridor/cover heights.
+- [ ] Critical path, landmark, and interact-color language are decided and
+      documented so art reinforces (never contradicts) them.
+- [ ] Greybox lighting intent (path lit, dead-ends dim) is captured for the
+      final lighting pass to honor.
+- [ ] Collision/nav requirements handed to the engine skill with the capsule
+      dimensions.
+- [ ] A greybox reference build is kept for A/B readability comparison after art.

package/skills/level-design/references/guidance-and-readability.md

@@ -0,0 +1,152 @@
+# Guidance & readability — direct the player without hand-holding
+
+How to make a player always know where to go, understand what they can do, and
+feel clever for exploring — using the environment instead of arrows. Also
+covers the playtest protocol, traversal telemetry, and reward/secret placement,
+because those are how you *diagnose and fix* readability.
+
+## The layers of guidance (strongest to weakest)
+
+The eye is drawn, roughly in this priority, to: **motion → light/brightness →
+high contrast → saturated color → the different/odd → framed shapes.** Stack
+these on the path you want taken; strip them from paths you don't.
+
+### Light leads
+
+Players move toward light — the moth effect — and toward higher value contrast.
+
+- Light the **critical path, the objective, and the exit**; keep dead-ends,
+  non-paths, and cut branches dim.
+- A bright opening at the end of a dark corridor is an irresistible pull.
+- Use light *in greybox* as a design tool, not a final-art afterthought — the
+  guidance is authored in placeholder lighting and art merely honors it.
+- Contrast beats absolute brightness: a shaft of light in gloom guides harder
+  than a uniformly bright room.
+
+### Color as language
+
+Reserve **one saturated accent color** to mean "you can interact / go here" and
+use it *nowhere else*.
+
+- Precedents: Mirror's Edge's "runner red" for the traversal path; Dishonored's
+  faint glint on usable objects; the near-ubiquitous "yellow = climbable/grab"
+  convention.
+- The value of the convention *is its consistency*. The moment the interact
+  color appears on decoration, you've lied — the player learns to distrust it
+  and starts checking everything, which is the opposite of guidance.
+- Keep the rest of the palette desaturated relative to the accent so it pops.
+
+### Composition
+
+Compose the space like a photographer composes a shot.
+
+- **Leading lines** — rails, beams, roads, pipes, tiling that point toward the
+  objective.
+- **Framing** — arches, doorways, foreground silhouettes that box the eye onto
+  the target.
+- **Negative space** and **contrast** to isolate what matters.
+- From every decision point, the critical path should be the most-framed,
+  highest-contrast, best-lit option.
+
+### Affordances & signifiers
+
+(Norman/Gibson.) An affordance is what the environment *lets* you do; a signifier
+is the visual cue that advertises it.
+
+- A ledge that looks grabbable **must** be grabbable; a wall that looks solid
+  **must** be solid. A door-shaped thing that never opens teaches the player to
+  ignore doors.
+- Establish the visual language **early** and hold it: if a specific trim, decal,
+  or material means "climb here," that cue appears **only** where you can climb.
+- Inconsistent affordances are the #1 source of "I didn't know I could do that"
+  and "I thought I could do that and died." Consistency > cleverness.
+- Prefer **diegetic signifiers** (a rope, scuff marks, a worn path, a ladder)
+  over UI prompts; save prompts for genuinely non-obvious systemic actions.
+
+### Landmarks & self-location
+
+- One **dominant landmark** per area — a large, distinct, distant silhouette
+  (Disney's "weenie": the visual magnet that pulls you forward). It answers
+  "where am I / where's the goal" without a minimap.
+- Keep landmarks visible from key decision points; if the player can't see the
+  landmark when they need to choose, it isn't doing its job.
+- **Deny wrong turns visually** — subtle dead-ends, unlit gaps, a distinct
+  "not-a-path" material — rather than relying on invisible collision, which
+  feels arbitrary and cheap.
+
+### The critical-path readability self-test
+
+Stand at each decision point in the greybox and ask: *with no HUD and no prior
+knowledge, is the intended next step the most obvious thing here?* If you have
+to argue for it, a fresh player will get lost. Fix with light/framing/landmark
+before reaching for a waypoint.
+
+## Playtesting — observe, don't coach
+
+You cannot see your own level fresh; your knowledge of it is the one thing a
+player won't have.
+
+1. **Fresh, uncoached tester.** Say "play." Then stay silent.
+2. **Log four signals:**
+   - **Hesitation / stopping** → readability gap (they can't tell where to go).
+   - **Wrong turn / backtrack** → navigation gap (guidance points wrong or is
+     absent).
+   - **Repeated death** → telegraph or difficulty gap (threat unfair or
+     unreadable).
+   - **Skipped content** → reward-placement or guidance gap.
+3. **Never answer "where do I go?"** — that question *is* the finding. Answering
+   it destroys the data and hides the bug.
+4. **Ask after, not during**: "Where did you think you were supposed to go? What
+   did you expect that button to do? Where did you feel stuck?" Open questions,
+   no leading.
+5. Test on the **greybox**, early and often — fixes are cheap while it's grey.
+
+## Traversal telemetry & heatmaps
+
+Turn anecdote into pattern by logging player data across many sessions:
+
+| Metric | What it shows | The fix when it's bad |
+|---|---|---|
+| **Position heatmap** | Where players spend time; **cold zones** they never enter | Cold zone = dead space: re-light it, add a landmark/reward, or cut it |
+| **Death heatmap** | Where players die; **clusters** = unfair/unreadable threats | Fix the telegraph, the arena, or the difficulty — not the player |
+| **Path traces** | Are they on the golden path or lost? | Divergence from intended path = guidance failure at that fork |
+| **Dwell time** at forks | Long dwell = unclear guidance | Add light/framing/landmark to make the choice obvious |
+| **Look / aim heatmap** | Did they even *see* the landmark or reward? | If not looked-at, it's mis-placed or out-competed — reposition |
+| **Time-to-objective** | Pacing vs intent (too fast/slow) | Adjust distance, breather length, or beat spacing |
+
+Read the map as instructions: a branch nobody takes needs a visible reward at
+its mouth; a region everyone avoids isn't pulling them — fix the pull or remove
+the region.
+
+## Reward & secret placement
+
+- **Reward the wandering eye.** Put secrets where a *curious* player naturally
+  looks — behind the waterfall, up the ledge you already lit and framed, down
+  the branch you breadcrumbed. Reward **observation**, not pixel-hunting.
+- **Breadcrumb every secret.** A glint, an out-of-place object, a suspicious
+  seam, an odd bit of geometry visible from the path. The player should feel
+  clever — which means the game showed them the thread first. A secret with no
+  breadcrumb is just frustration.
+- **Never hide mandatory progression like a secret.** A required key or door
+  disguised as optional is a stuck-player generator. Secrets are optional by
+  definition; the critical path stays legible.
+
+## Risk vs reward
+
+- Gate the **best** optional reward behind the **biggest** optional risk or
+  detour — a hard side-arena, a long climb, a resource gamble, a no-checkpoint
+  stretch.
+- Keep the **critical path rewarding on its own** so risk-averse players aren't
+  punished for playing it safe; put the *extra* behind the *extra* effort.
+- Make the risk and the reward both *visible before committing* so the choice is
+  informed: the player should see the treasure across the deadly gap and decide.
+
+### Reward taxonomy (vary these so exploration stays fresh)
+
+| Type | Example | Notes |
+|---|---|---|
+| **Power / upgrade** | new ability, weapon, permanent buff | Strongest pull; use sparingly |
+| **Resources** | ammo, health, currency | Steady exploration incentive |
+| **Lore / collectible** | note, audio log, vista, cosmetic | For the curious; light them in breathers |
+| **Shortcut unlock** | a door back to the hub, a lowered ladder | Best long-term reward — reshapes the level, cuts backtracking |
+| **Spectacle** | a view, a scripted moment, an Easter egg | Pure delight; costs no systemic balance |

package/skills/level-design/references/pacing-and-encounters.md

@@ -0,0 +1,142 @@
+# Pacing & encounters — rhythm, arenas, and teaching through space
+
+A level is a piece of music, not a list of rooms. This reference covers the
+intensity graph, the breather, the difficulty curve, the encounter template, the
+introduce→develop→twist→combine teaching pattern, and arena-shape design.
+
+## The intensity graph
+
+Plot intended intensity (danger + cognitive load + stimulus) against time for
+the whole level. The target shape is a **sawtooth trending upward**: a peak
+(combat, chase, platforming gauntlet, tense stealth), a sharp drop to a valley
+(a breather), then a higher peak. Overall the line climbs, ending on the level's
+hardest, most spectacular moment.
+
+```text
+intensity
+  ^                                        ___/\   <- climax (hardest, last)
+  |            ___/\           ___/\      /
+  |     __/\  /     \    __/\  /     \___/
+  |  __/    \/       \__/    \/            <- breathers (valleys)
+  +---------------------------------------------> time
+     intro  peak  rest  peak  rest  build  climax
+```
+
+Two failure shapes to avoid:
+
+- **Flat-high** — sustained maximum intensity. The player fatigues and the peaks
+  stop reading as peaks; it flattens into undifferentiated noise. This is the
+  most common "my level is exhausting / boring despite lots of action" cause.
+- **Flat-low** — long stretches with no tension or stimulus. Reads as padding
+  and boredom even if each individual moment is competent.
+
+Draw this graph *before* building encounters; it tells you where fights go and
+how long the gaps between them should be.
+
+## The breather (safe room)
+
+After each peak, a valley: a **safe room** with no threat, low stimulus, and
+usually a save point and/or restock. The breather does three jobs:
+
+1. **Lets adrenaline drop** so the next peak spikes instead of blending in.
+   (Halo's cadence is often described as "thirty seconds of fun" on repeat — the
+   calm between is what makes the fun read.)
+2. **Rewards observation** — a quiet room is where lore, a secret, or a vista
+   lands, because the player has attention to spare.
+3. **Sets up the next escalation** — telegraph what's coming (a locked blast
+   door, distant sound, a corpse) so the next peak feels earned, not random.
+
+Vary breather length with the peak that preceded it: a brutal fight earns a
+longer rest; a light skirmish gets a short beat.
+
+## Difficulty curve within a level
+
+The macro trend is up, but it **resets at checkpoints** — the sawtooth again.
+Let the player re-enter a checkpoint competent and confident, then ramp. A curve
+that only climbs with no resets feels punishing; one that never climbs feels
+trivial. Signposting difficulty (a visibly tougher enemy, a bigger arena) lets
+the player brace, which is fairer than a surprise spike.
+
+## Encounter design
+
+An **encounter = enemy composition × space × objective × available resources.**
+Change any single factor to create a fresh encounter without new assets:
+
+- **Composition** — which enemy types, how many, in what waves.
+- **Space** — the arena shape (below); the same enemies feel new in a new arena.
+- **Objective** — kill all / survive N seconds / reach the exit / protect / hold
+  ground / retreat. The objective reshapes how the space is used.
+- **Resources** — ammo, health, cover, high ground the player can seize.
+
+### The encounter template
+
+```text
+ENCOUNTER — <name>
+  Teaches / tests ..... which mechanic or threat (and which of I/D/T/C beat)
+  Space ............... arena shape, sightline length, cover, flanks, verticality
+  Composition ......... enemy types + counts + wave timing
+  Objective ........... win condition (kill / survive / reach / hold / escort)
+  Resources ........... ammo/health/cover/high-ground and where they sit
+  Entry / exit ........ how the player arrives (telegraph) and leaves (release valve)
+  Intensity ........... where this sits on the level's graph (peak height)
+```
+
+## Introduce -> develop -> twist -> combine
+
+The four-beat progression that teaches a new element through space, without
+text. (The pattern behind Portal's test chambers, Half-Life 2's set-pieces, and
+much Nintendo level craft.)
+
+1. **Introduce** — meet it where it cannot hurt you. A turret across a safe gap;
+   one tile of the new hazard with a wall to watch from. Zero-risk learning.
+2. **Develop** — use it for real, low stakes. The turret now guards a corridor
+   you must cross; the hazard is a gap you must jump.
+3. **Twist** — recontextualize it. Two turrets flanking; the turret behind glass
+   you must lure enemies past; the hazard now moves. The rule you learned bends.
+4. **Combine** — the mastery test: the new element + everything learned earlier,
+   at full intensity, as the section's climax.
+
+### Worked example — a "gravity plate" that flings the player upward
+
+- **Introduce**: one plate in a safe room; step on it, get flung to a ledge with
+  a reward. No threat. Player learns "plate = launch."
+- **Develop**: cross a pit by chaining two plates — miss and you just fall back,
+  retry. Low stakes, real use.
+- **Twist**: a plate launches you *into* a turret's line of fire — now you must
+  time the launch, or use the plate to reach the turret's flank.
+- **Combine**: an arena where plates are the only way to reach high cover, under
+  fire, while enemies also use them. Everything at once.
+
+## Arena shape — the geometry is the difficulty knob
+
+The shape a fight happens in matters as much as the enemies:
+
+- **Sightline length ↔ threat range.** Long lanes favor ranged play and
+  sniping; tight rooms favor shotguns/melee and force close engagements. Set the
+  lane length to the range you want to be dominant.
+- **Cover rhythm.** Space cover so the player *advances in beats* — peek, move,
+  peek — rather than turtling in one spot. Low cover (peek over) vs full cover
+  (peek around) change the fight's tempo.
+- **Flanks.** Give at least one flank route so a fight isn't a static peek-war;
+  a flank forces the player to move and makes the space three-dimensional in
+  play, not just in geometry.
+- **Verticality.** High ground is pressure and reward. The Doom (2016) arena
+  is the reference: multi-tier, with resources and enemies placed to pull the
+  player *through* and *up* the space rather than hunker in a corner.
+- **Chokepoints + release valves.** A choke concentrates danger (good for a
+  last stand); always pair it with an exit or a way to break the standoff, or
+  the fight stalls into a stalemate.
+- **Entry and exit.** Telegraph the fight before the player commits (see the
+  arena from a safe threshold), and give a clear release when it's won.
+
+### Arena patterns
+
+| Pattern | Shape | Good for |
+|---|---|---|
+| **Corridor / lane** | Long, narrow, few flanks | Tension, forced pace, ranged duels |
+| **Open arena** | Wide, multi-cover, multi-flank | Skill expression, mobile fights |
+| **Vertical arena** | Stacked tiers, ramps/lifts | High-ground contests, push-forward combat |
+| **Hub** | Central space, spokes off it | Wave defense, "hold ground" objectives |
+| **Pinch** | Wide → choke → wide | Escalation, last-stand beats |
+
+Match the pattern to the encounter's job on the intensity graph, not to habit.