@ericrisco/rsc 0.1.35 → 0.1.37

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.