@ericrisco/rsc 0.1.35 → 0.1.36

package/skills/game-design/references/mechanics-and-loops.md

@@ -0,0 +1,78 @@
+# Mechanics, verbs, loops, and feel — deep dive
+
+Engine-agnostic. This expands the SKILL.md sections on loops, MDA, verbs, and feel. No engine APIs — when a pattern needs code, it belongs to `godot` / `unity` / `unreal`.
+
+## MDA in practice
+
+Mechanics → Dynamics → Aesthetics is a lens, not a pipeline you fill in once.
+
+- **Mechanics** — the rules, entities, and numbers you literally author: gravity value, damage table, spawn rules, win condition.
+- **Dynamics** — the runtime behavior that emerges when players push on the mechanics: kiting, rushing, turtling, economy hoarding. You do not write dynamics; you *provoke* them with mechanics.
+- **Aesthetics** — the emotional response the player actually has. This is the only layer they experience directly.
+
+You author left-to-right but must **reason right-to-left**: start from the feeling you want, hypothesize a dynamic that would produce it, then author the mechanic that produces that dynamic. Playtest to see whether the real dynamic matches the intended one — it usually doesn't the first time.
+
+### The eight aesthetics (name the one you want)
+
+| Aesthetic | The feeling | Example games |
+| --- | --- | --- |
+| Sensation | Sense-pleasure, "game as toy" | *Tetris*, rhythm games, *Katamari* |
+| Fantasy | Make-believe, inhabiting a role | *Skyrim*, flight sims |
+| Narrative | Drama unfolding | *Disco Elysium*, *The Last of Us* |
+| Challenge | Obstacle course, mastery | *Celeste*, *Dark Souls*, *Trackmania* |
+| Fellowship | Social framework, cooperation | *It Takes Two*, MMOs, *Among Us* |
+| Discovery | Exploring the unknown | *Outer Wilds*, *Subnautica* |
+| Expression | Self-discovery, creation | *Minecraft*, *The Sims*, *Animal Crossing* |
+| Submission | Pastime, relaxation, "flow-off" | idle games, *Stardew Valley* farming |
+
+Most games target **two or three**, weighted. Writing them down settles arguments: a feature that serves none of your chosen aesthetics is a cut candidate, however cool.
+
+## Verbs are the game
+
+The player's verb set — the actions available — is the truest description of a design. "A game about jumping and stomping" (Mario) says more than any feature list.
+
+- **Depth over breadth.** A few verbs that interact combinatorially (chess: six piece-moves) yield more game than dozens of isolated ones. Interaction between verbs is where mastery and emergence live.
+- **Verb economy test.** Before adding anything, ask: does this add a *new verb*, *deepen an existing verb's interactions*, or merely *add a number*? Numbers rarely add game.
+- **Emergence vs progression** (Juul's distinction):
+  - *Emergent* games — simple rules, vast possibility space (chess, poker, *Spelunky*, roguelikes). Cheap to build, huge replay, hard to control the experience.
+  - *Progression* games — designer places a sequence of challenges (linear campaigns). Total authorial control, expensive per minute of play, low replay.
+  - Most games blend: an emergent core loop inside a progression frame.
+
+## Loop layering, in detail
+
+```text
+INPUT ─▶ [ moment-to-moment verb ] ─▶ immediate feedback ─▶ (repeat, seconds)
+                                            │ accrues into
+                          [ session goal / run ] ─▶ session payoff ─▶ (minutes–1h)
+                                            │ funds
+                          [ meta progression ] ─▶ lasting change ─▶ (across sessions)
+```
+
+- **Moment-to-moment must be intrinsically fun.** Test: strip every goal, reward, and score — is the raw act of doing the verb still satisfying? If not, fix this before anything else. This is Bungie's "30 seconds of fun" — perfect the small loop, and the game is that loop repeated in varied contexts.
+- **Session loop needs a shape.** Setup → rising tension → climax → resolution → hook. A run that just stops has no payoff; a run that ends on "so close" pulls the next one.
+- **Meta loop is the return reason.** It converts session output (currency, XP, mastery, unlocks) into durable change. If the meta gives only numeric inflation and no new *choices or verbs*, players feel the grind without the growth.
+- **Reward funding is the health check.** Each layer's reward should create desire for the next layer. Diagnose a "not fun" game by asking which loop is starved:
+  - Flat moment-to-moment → nothing above can save it.
+  - Empty meta → "great for an hour, then I bounced."
+  - Meta with no moment-to-moment joy → "I grind and don't know why."
+
+## Feedback loops (system dynamics)
+
+Distinct from "player feedback." These are the amplifying/damping loops in your systems.
+
+- **Positive feedback loop** — success makes further success easier (rich-get-richer). Accelerates games to a conclusion and rewards early leads. Good for *ending* a game; dangerous if unchecked mid-game (snowball, runaway leader, blowouts).
+- **Negative feedback loop** — success makes further success harder, or trailing players get help (catch-up, rubber-banding, escalating cost of dominance, *Mario Kart* items). Keeps games close and tense; overdone it punishes skill and feels unfair.
+- **Design move:** use negative feedback to keep the mid-game close and positive feedback to force a decisive end — so games stay tense but still *end*.
+
+## Game feel / juice as design intent
+
+Feel is the moment-to-moment made tactile. Decide it here; the engine implements it.
+
+- **Responsiveness first.** Immediate, legible reaction to every input beats visual fidelity. Perceived input latency destroys feel.
+- **Juice vocabulary** — specify the *intent* and *trigger*, not the code:
+  - *Hit-stop / hit-pause* — freeze a few frames on impact to sell weight.
+  - *Screenshake* — amplitude scaled to significance; gratuitous shake reads as noise.
+  - *Anticipation & follow-through*, *squash-and-stretch* — animation principles that telegraph intent and add weight.
+  - *Particles, easing/tweening curves, layered SFX* — reinforce the action's magnitude.
+- **Hidden generosity.** Coyote time (jump slightly after leaving a ledge), input buffering (queue an input landing a hair early), and forgiveness windows make a game feel *fair* and responsive without the player knowing why. These are design decisions with real numbers (frames/ms) — specify them; the engine skill wires them.
+- **Boundary:** keyframes, curves, shader passes, and timing code are engine work. Here you produce a table of "action → intended feel → effect → trigger."

package/skills/game-design/references/playtesting-and-scope.md

@@ -0,0 +1,58 @@
+# Prototyping, playtesting, scope, and docs — deep dive
+
+Engine-agnostic. Expands the SKILL.md sections on prototyping, playtesting, scope, and documenting design.
+
+## The prototyping ladder
+
+Climb only as far as each rung earns. Each rung is cheaper to change than the next.
+
+1. **Riskiest-assumption first.** Name the single thing that, if it doesn't work, sinks the game (Is the core verb fun? Does the economy hold? Is the twist readable?). Prototype *that*, not the easy parts.
+2. **Paper / cards.** Best for rules, turn order, economies, and card/board interactions. Simulate the loop by hand; you can rebalance in seconds with a pencil.
+3. **Greybox / blockout.** Untextured, programmer-art mechanics running in the engine. Proves *feel* and moment-to-moment fun. If it isn't fun in greybox, art will not make it fun — this is the single most expensive lesson to learn late.
+4. **Vertical slice.** One polished, representative sliver — one level or one loop at final quality — proving the game is worth finishing and showing what "done" looks like. Prefer this over a broad, shallow map of half-built features.
+
+**Find the fun before you buy the art.** Art and audio are the most expensive assets and the hardest to change; commit them only after the mechanic underneath is proven.
+
+## Playtesting
+
+- **Watch, don't coach.** Say as little as possible. The instant you explain a control, you have destroyed the first-time-user signal you can never recapture from that tester.
+- **Behavior over opinion.** Players are unreliable at diagnosing *what* is wrong and reliable at signaling *that* something is. When a tester says "the jump is fine" but dies to the same gap ten times, believe the deaths. Weight actions over words.
+- **Protocols:**
+  - *Think-aloud* — tester narrates their thoughts live; surfaces confusion and mental model mismatches.
+  - *First-time-user (FTUE)* — a fresh tester with zero explanation; the harshest and most valuable test of onboarding.
+  - *Post-play interview* — ask open questions ("what would you tell a friend about this?"), never leading ones.
+- **What to measure:**
+  - *Qualitative* — struggle points, boredom points, quit points, "aha" moments, emotional reactions.
+  - *Quantitative* — completion rate per section, time-per-section, death heatmaps, failure counts, and retention: **D1 / D7 / D30** (fraction returning 1/7/30 days later). Retention is the honest verdict on whether the loops hook.
+- **Cadence:** test early, test ugly, test often. A rough test this week beats a polished one next month. Rotate testers — a tester can only be first-time once.
+
+## Killing your darlings
+
+- Cut any mechanic that does not serve the core loop or a design pillar — regardless of how clever it is or how long it took. A pile of unrelated clever mechanics is not a game.
+- Signs a darling must die: it needs its own tutorial, it only shines in one contrived spot, playtesters ignore it, or defending it starts with "but it was hard to build" (sunk cost is not a design argument).
+
+## Scope: the #1 indie killer
+
+More indie games die of scope than of bad ideas, weak talent, or poor tools. The failure mode is always the same: a feature list that outruns the finish line.
+
+- **Cut features, not quality.** A finished small game beats an unfinished ambitious one, every time. Shrinking scope preserves polish; cutting polish to keep scope produces a large mediocre thing nobody finishes.
+- **Define "the one thing."** State in one sentence what the game is *about* and protect it. Everything that doesn't serve it is a candidate for the cut list.
+- **Vertical slice over horizontal sprawl.** Build one loop end-to-end at quality before widening. A deep narrow slice ships; a wide shallow map of stubs does not.
+- **A public cut list.** Keep an explicit "not doing" list next to the feature list. Naming what's *out* is as important as naming what's in — it ends the "wouldn't it be cool if…" spiral.
+- **Budget by the finish, not the ambition.** Estimate remaining work against real available time; when they don't fit, the variable you move is scope, not the ship date and not sleep.
+
+## Documenting design: the living one-pager
+
+A 100-page design bible is stale the day after it's written and read by no one. Replace it with a living one-pager that grows only where a real decision needs recording.
+
+One-page design doc contents:
+
+- **Hook / fantasy** — one sentence: what is the player's power fantasy or core experience?
+- **Pillars** — 2–4 short phrases (e.g. "tense stealth", "readable chaos", "no dead ends"). These are decision filters: every feature must serve a pillar or it is cut.
+- **Core loop** — the moment-to-moment → session → meta chain in a few lines.
+- **Verbs** — the actions the player has.
+- **Target aesthetic** — the named MDA emotion(s), weighted.
+- **MVP / vertical-slice scope** — the smallest thing worth building and playing.
+- **Out of scope** — the explicit cut list.
+
+Keep it a communication tool, not an archive: a versioned wiki page beats a locked document. Prune it as decisions settle; link deeper notes only where they earn their space.

package/skills/game-design/references/progression-and-economy.md

@@ -0,0 +1,70 @@
+# Progression, economy, and balance — deep dive
+
+Engine-agnostic. Expands the SKILL.md sections on progression, economy, difficulty, and balancing. All math here fits in a spreadsheet; no engine APIs.
+
+## Progression pacing
+
+- **Two parallel curves: difficulty and novelty.** Boredom comes from either flatlining. When difficulty must plateau (a rest area), spike novelty (a new mechanic, a set-piece); when novelty must pause, nudge difficulty. Never let both go flat at once.
+- **Teach → test → twist.** Introduce a mechanic safely, test it under mild pressure, then combine it with an earlier mechanic. This is how you build *layered* mastery instead of a pile of unrelated tutorials.
+- **Gate to control cognitive load.** Unlocks pace how many systems the player juggles at once. Front-loading every verb overwhelms; drip-feeding lets each verb be learned before the next.
+- **Unlock quality bar.** Each unlock should add a **verb** or a **meaningful choice**, not just +N%. A stat bump is progression felt as grind; a new option is progression felt as growth.
+
+## Economy: currencies, faucets, sinks
+
+- **Currency taxonomy:**
+  - *Soft currency* — earned through play, spent freely (gold, scrap). Drives the core economy loop.
+  - *Hard / premium currency* — scarce or bought, gates high-value or aspirational items.
+  - *Time / energy* — a pacing gate (stamina systems); a sink on session length.
+  - *Prestige* — meta-currency earned by resetting progress; funds the long meta.
+- **One currency, one job.** Every currency must have a distinct **sink** it exists to feed. If two currencies buy the same things, merge them. Currency without a sink is clutter and inflates.
+
+### Faucets and sinks
+
+- **Faucet** = anything that *creates* currency (quest rewards, drops, passive income).
+- **Sink** = anything that *destroys* it (shop costs, upgrades, repairs, consumables, taxes/fees).
+- The economy is healthy when total faucet output and total sink demand track each other over the play arc.
+
+Core identity to model in a sheet:
+
+```text
+net_income_rate = faucet_rate − sink_rate
+time_to_afford  = cost / net_income_rate
+
+# escalating sink — the standard way to keep pace with rising income:
+cost(n) = base × growth^n
+#   growth ≈ 1.07–1.15 for idle/incremental; higher = steeper wall
+#   solve for growth by pinning two target prices, or for base by pinning the first cost
+```
+
+Tune `time_to_afford` against desired pacing (e.g. "a new tier every ~2 sessions"). Sweep the parameters in a spreadsheet before touching the engine.
+
+### Runaway and inflation
+
+- **Symptom:** `net_income_rate` grows faster than `cost(n)` → currency piles up, prices feel free, the late game trivializes. Or the reverse: sinks outpace faucets → progress stalls, players feel taxed.
+- **Fixes for over-supply:** escalating/exponential sinks (`growth` above), consumable sinks (currency spent every session, not banked), soft/hard caps, and **prestige resets** that trade accumulated progress for a permanent multiplier and re-open the curve.
+- **Multiplayer economies** add faucet leaks (duping, botting, gold farming) and player-to-player trade that can concentrate wealth — audit total money supply over time, not just per-player rates.
+
+## Difficulty and balancing
+
+### The curve
+
+- **Sawtooth, not a straight ramp.** A rising baseline with peaks (bosses, gauntlets) and valleys (recovery, reward rooms). The valleys make the peaks legible and let the player breathe.
+- **Flow channel** (Csikszentmihalyi via game design): keep perceived challenge tracking the player's rising skill, in the band between boredom (too easy for current skill) and anxiety (too hard). As skill grows, challenge must grow with it.
+- **Perceived ≠ actual.** Telegraphing, readability, and generosity (see feel) change *perceived* difficulty without changing the numbers. A fair-feeling hard game keeps players; an unfair-feeling easy one loses them.
+
+### Tuning knobs
+
+- **Find the few high-leverage variables** — usually damage, health, spawn rate/density, resource cost, cooldown/duration. Most balance lives in a handful of them.
+- **Change one at a time.** Chasing a symptom by moving five knobs makes cause un-attributable. Move one, retest, record.
+- **Data-driven.** Put tunables in data (tables/config/spreadsheets), never hard-coded constants, so designers iterate without a rebuild and numbers are diffable and A/B-able. This skill decides *which* values are tunable and their ranges; the engine skill (`godot`/`unity`/`unreal`) builds the loader.
+
+### Dominant strategies and intransitive balance
+
+- **Dominant strategy** = an option that strictly beats the alternatives in most situations. It collapses the meta: every rational player converges on it and all other choices die.
+- **Detect it:** watch playtests and telemetry for pick-rate/win-rate outliers, and for "solved" openings. High pick + high win = nerf target.
+- **Fix toward intransitivity:** aim for rock-paper-scissors — every option is beaten by *some* other option, none beats all. Nerf the outlier or buff its counters; prefer many small changes over one sweeping one.
+- **Symmetry vs asymmetry:** symmetric balance (mirror factions) is easy to make fair but flat; asymmetric balance (distinct factions/classes) is rich but must be balanced by *outcome parity* (equal win-rates), not by identical stats.
+
+### Difficulty options & accessibility
+
+- Decouple **challenge** from **exclusion**. Difficulty modes, assist toggles (aim assist, slow-mo, invulnerability), and separate sliders for enemy damage vs enemy health widen the audience without diluting the intended experience for those who want it. Accessibility is design, not charity — it grows the reachable player base.

package/skills/game-storytelling/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: game-storytelling
+description: "Use when designing a game's STORY as an interactive system: premise, theme and narrative pillars; branching narrative and meaningful choice; dialogue trees with state and flags; quests, objectives and fail states; worldbuilding; environmental and systemic storytelling; and keeping story in harmony with play (avoiding ludonarrative dissonance). Engine-agnostic — it designs the narrative graph, variables and beats, then hands the wiring to the engine skill. Triggers: 'write my game's story/premise', 'branching narrative', 'dialogue system/tree', 'quest structure', 'worldbuilding', 'meaningful choices', 'illusion of choice', 'Ink/Yarn Spinner/Twine/articy narrative', 'story keeps fighting the gameplay'. NOT core mechanics, systems or balance (that's game-design); NOT spatial/level layout or encounter placement (that's level-design); NOT the actual dialogue-node code, save format or plugin wiring inside an engine (that's godot/unity/unreal)."
+tags: [game, narrative, story, dialogue, quest, branching, worldbuilding]
+recommends: [game-design, level-design]
+profiles: [full]
+origin: risco
+---
+
+# Game Storytelling — Narrative Design (engine-agnostic)
+
+*Design the story as a system the player operates, not a script they watch. This skill owns the narrative graph — premise, pillars, branches, choices, dialogue state, quests, and the storytelling embedded in the world — and hands the runtime wiring to the engine skill.*
+
+You produce **design artifacts**: a premise/theme/pillars doc, a branch topology, a state/flag table, dialogue in a portable format (Ink/Yarn/Twee/articy), quest specs, and environmental beats. You do **not** write engine node code, save-serialization, or plugin glue — that is `godot`/`unity`/`unreal`. A mechanic question (what the player *does*, economy, balance) is `game-design`; where things sit in space is `level-design`.
+
+## Fires on / When NOT
+
+Use when the request is about: a game's story or premise; branching or non-linear narrative; a dialogue system, tree, or conversation logic; quests, objectives, or mission structure; worldbuilding/lore for a game; meaningful choice vs. the illusion of choice; environmental or systemic storytelling; or story that "fights" the gameplay (ludonarrative dissonance).
+
+Do NOT use (delegate or decline):
+
+- Core loop, verbs, systems, progression, economy, difficulty, or balance → **game-design**.
+- Spatial layout, encounter placement, sightlines, blockout, pacing *of a space* → **level-design**.
+- Implementing the dialogue runner, save/serialize of story state, or wiring Ink/Yarn/articy into a build → the engine skill (**godot/unity/unreal**).
+- Prose fiction, a screenplay, or a novel with no interactive/branching structure → general writing.
+- Marketing copy, store page, or trailer script → **marketing**.
+
+Story is a **system in service of play**. When you catch yourself designing a great scene the mechanics can't honor, reconcile it (see Ludonarrative harmony) rather than ship the dissonance.
+
+## Premise, theme, and pillars (do this first)
+
+Nail these before a single branch or line of dialogue. They are the constraint that keeps a branching story from sprawling into incoherence.
+
+1. **Premise** — one sentence: *who*, in *what world*, wants *what*, against *what*. If it doesn't fit in a sentence, the story isn't decided yet.
+2. **Theme** — the question the game argues about (loyalty vs. survival, cost of power). Theme is the filter for every choice; a choice that doesn't press on it is decoration.
+3. **Narrative pillars** — 3–5 non-negotiables the story must always deliver (e.g. "every companion can die," "the player is never the chosen one"). Pillars kill scope arguments later.
+4. **Tone & POV** — register (grim, wry, mythic), narrative distance (silent, voiced, ensemble), tense/person for text.
+5. **Story-in-service-of-play** — write pillars so they are *expressed through the verbs the player already has*. If the theme is "trust is earned," the game needs a trust mechanic, not a paragraph asserting it.
+
+### Ludonarrative harmony (avoid dissonance)
+
+Dissonance is when the story says one thing and the mechanics say the opposite (the "caring family man" who murders a thousand henchmen). Diagnose and fix, in order:
+
+- **Verb audit.** List what the player *does* most. Does the dominant verb match the theme and the protagonist's values? If the loop is "kill," a pacifist narrative is dissonant.
+- **Reward audit.** What does the game *reward*? Rewards are the loudest narrative voice — if you reward hoarding but preach generosity, players believe the reward.
+- **Fix by moving the cheaper piece.** Usually re-frame the narrative to match the mechanic rather than re-engineering the mechanic — but flag to **game-design** when only a mechanic change resolves it.
+- **Failure & death.** Reconcile the fiction of losing (respawn, checkpoint, permadeath) with the story; unexplained respawns are the most common silent dissonance.
+
+## Narrative structures for interactivity
+
+Pick a topology deliberately; most games mix them. Full trade-offs, diagrams, and containment math → `references/branching-and-state.md`.
+
+| Structure | Shape | Player agency | Author cost | Use when |
+| --- | --- | --- | --- | --- |
+| **Linear** | one path, story beats gated by progress | low (pacing only) | low | story-driven, cinematic, tight authorship |
+| **Branching (tree)** | choices split, rarely rejoin | high, expensive | explodes fast | short, choice-showcase, replay-driven |
+| **Hub-and-spoke** | central hub, self-contained spokes, return | medium (order + selection) | moderate, scales | quests/missions, RPGs, episodic |
+| **Foldback / string-of-pearls** | branches diverge then **reconverge** at beats | feels high, stays bounded | moderate | the workhorse for long branching stories |
+| **Environmental** | story embedded in space & objects, player-assembled | interpretive | front-loaded | immersive sims, exploration, "show don't tell" |
+| **Systemic / emergent** | story generated by rules + player, not scripted | very high, uncurated | design not writing | sims, roguelikes, sandbox; the "anecdote factory" |
+
+The pragmatic default for a story-heavy game is **foldback**: let choices matter locally, then reconverge on load-bearing beats so you author a bounded number of scenes. Pure trees are a trap (see below).
+
+## Branching & choice
+
+A choice is **meaningful** only if the player can (a) form an intent, (b) foresee a plausible consequence, and (c) later *see the consequence land*. Missing any leg makes it noise. Meaningful choice vs. the deliberate, defensible **illusion of choice**, plus state modeling and the combinatorial-explosion fix → `references/branching-and-state.md`.
+
+- **Meaningful choice** changes state that the game later reads back to the player (a door, a death, a line, an ending). Track it with a **flag/variable**, not a duplicated scene.
+- **Illusion of choice** (options that reconverge to the same outcome) is a legitimate tool for *expression and tone* — but never sell a fake choice as consequential; players feel the betrayal and stop trusting every future choice.
+- **State & flags** are the spine. Model story state as named variables (`met_the_witch`, `reputation >= 3`, `betrayed_ally`). Gate content on state; don't copy-paste branches.
+- **The combinatorial-explosion trap.** N independent binary choices imply 2^N futures — unauthorable past a handful. Contain it with:
+  - **Reconvergence (bottlenecks)** — funnel branches back to shared beats; the space between bottlenecks stays small.
+  - **Gates** — require a flag/level/item to open content, pruning the live branch set.
+  - **State over structure** — one scene that reads flags and swaps lines beats ten near-duplicate scenes.
+  - **Locality** — most choices affect only the current scene ("weave"); reserve the few loud choices for global state.
+
+## Dialogue systems
+
+Every dialogue tool reduces to the same four primitives — design against these, then let the engine skill wire the chosen tool. Deep tool comparison, a "pick one" guide, and the same conversation shown in Ink / Yarn / Twee → `references/dialogue-tools.md`.
+
+- **Node** — a unit of content (a line, a passage, a knot) with an id you can jump to.
+- **Condition** — boolean over story state that gates a node, option, or line (`if hasKey`, `if trust > 2`).
+- **Variable** — the story state read/written by nodes (flags, counters, enums, inventory).
+- **Effect** — a side effect a node fires (set a flag, give an item, start a quest, emit an engine event).
+
+Tools (pointers — do not author engine glue here):
+
+- **Ink** (inkle) — writer-first scripting language: knots/stitches, diverts `->`, once-only `*` / sticky `+` choices, gathers, weave, `VAR`, `LIST`, tunnels, threads, tags. Great for prose-heavy branching; runs via `inkjs` or engine integrations.
+- **Yarn Spinner** (v3.x, current) — node-based, Twine-friendly: `<<set $var to x>>`, `<<if>>`, `<<jump>>`, commands, functions, markup. First-class Unity; Godot (C# beta, GDScript alpha); Unreal in progress.
+- **Twine** — visual node editor, publishes standalone HTML; scripting depends on the **story format** (Harlowe, SugarCube, Snowman, Chapbook). Twee is its text form — a good neutral interchange.
+- **articy:draft X** — heavyweight visual narrative DB (flow/dialogue fragments, hubs, conditions, instructions, entities); free Unity/Unreal importers and a **Generic Engine Export** (JSON) for anything else.
+
+Author in one of these formats and keep dialogue **portable**; engine binding is a separate step owned by the engine skill.
+
+## Quests & objectives
+
+A quest is a small state machine plus presentation. Spec each quest with:
+
+- **Trigger** — what activates it (talk to X, enter zone, flag set).
+- **Objective(s)** — ordered or parallel steps; each a condition over world/story state.
+- **States** — `unavailable → available → active → (step states) → complete / failed`, modeled explicitly. Ambiguous quest state is the #1 quest bug.
+- **Tracking & presentation** — what the player sees (journal, marker, count). Design the *reveal*: don't show a marker for a step the player shouldn't know yet.
+- **Rewards & consequences** — the flags/items/state the quest writes on completion *and* on failure.
+- **Fail states** — decide per quest: can it fail, and is failure a dead-end, a branch, or lost content? **Failing forward** (failure opens a different path) beats a hard fail; **soft-locking the game** is a defect — always leave an escape.
+- **Nesting & dependencies** — main/side/hidden; prerequisite flags; mutual exclusivity (faction A locks B). Track dependencies as gates, per the branching rules above.
+
+## Environmental & systemic storytelling (show, don't tell)
+
+Deliver story *through the world* so the player assembles it and feels ownership. Technique catalog, diegetic-vs-non-diegetic delivery, and the "anecdote factory" → `references/environmental-storytelling.md`.
+
+- **Show, don't tell.** Prefer a scene the player reads (a skeleton clutching a locked door) over a paragraph narrating it. Text-dumps are the fallback, not the default.
+- **Environmental storytelling** — set dressing, aftermath/traces, spatial sequencing, object placement, and readable item descriptions that imply events without narrating them. Coordinate with **level-design** for the space itself.
+- **Systemic / emergent storytelling** — let rules + player generate stories you didn't script ("that time my colonist starved defending the fridge"). You design the *conditions and vocabulary* for stories, not the stories — a **game-design** collaboration.
+- **Diegetic first.** Prefer in-world delivery (signage, barks, world change) over HUD/narrator; reserve non-diegetic (menus, codex, narrator) for what the world genuinely can't carry.
+
+## Delivery: pacing, VO, localization-readiness
+
+- **Pace the text.** Match line length to the moment; long paragraphs in combat go unread. Chunk to the display (one box-screen), respect reading speed, never block play with unskippable text.
+- **VO considerations** *(design-side, not recording — that's audio/engine)* — write for the ear (contractions, short clauses); budget line counts early (VO is expensive and near-frozen once recorded); keep a **stable line ID** on every spoken line; don't splice recorded fragments across variables (gender/number/name concatenation breaks in most languages).
+- **Localization-readiness** *(so the loc pipeline can do its job)* — externalize all player-facing text to string tables keyed by stable id; **never concatenate** sentences or embed grammar in code (gender/plural/word-order differ per language — use full templated strings with ICU-style placeholders); allow +30–40% text expansion; keep variables as named tokens (`{playerName}`), not positional; leave translator notes per line.
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "I'll just branch it, players love choices" | Pure trees explode (2^N). Use foldback + gates; reconverge on beats. |
+| "This choice feels huge" (but nothing reads it back) | If no later node reads the flag, the choice is noise. Show the consequence or cut it. |
+| "Both options lead to the same scene, that's fine" | Only if it's expression, not stakes. Never sell a fake choice as consequential. |
+| "The story explains why he's a mass murderer" | Words don't beat verbs. Fix the ludonarrative dissonance, don't narrate around it. |
+| "Add an audio log to explain the backstory" | Text-dump is the fallback. Try to *show* it environmentally first. |
+| "We'll localize later, just hardcode the strings" | Concatenation and hardcoded text break loc. Externalize to keyed string tables now. |
+| "The quest can't be failed, simpler that way" | Sometimes; but soft-locking the game on a missed step is a defect — leave an escape. |
+| "Let me wire this Ink file into Unity real quick" | Not this skill. Author portable narrative; hand wiring to the engine skill. |
+
+## Related skills
+
+- **game-design** — the verbs, systems, economy, and balance the story must serve; call it when resolving dissonance needs a *mechanic* change, or when designing systemic/emergent story conditions.
+- **level-design** — the spatial layout and encounter flow environmental storytelling lives inside; co-own set-dressing narrative.
+- **godot / unity / unreal** — the engine that wires the dialogue runner, quest state, save/serialize, and Ink/Yarn/articy plugins. Author portable; they implement.
+- **marketing** — store page, premise pitch, trailer copy (external-facing, not in-game narrative).
+
+## Checklist
+
+- [ ] Premise (one sentence), theme, and 3–5 narrative pillars are written and agreed; every pillar is expressible through an existing player verb (no assert-only themes).
+- [ ] Verb + reward audit done; any ludonarrative dissonance is fixed or escalated to game-design.
+- [ ] A topology is chosen deliberately (default: foldback), not accidental tree sprawl; combinatorial explosion is contained (reconvergence + gates + locality) so the branch count is authorable.
+- [ ] Story state is modeled as named variables/flags; content gates on state, not duplicated scenes.
+- [ ] Every "meaningful" choice writes a flag some later node reads back to the player; no fake choice is sold as consequential.
+- [ ] Dialogue authored in a portable format (Ink/Yarn/Twee/articy); engine wiring left to the engine skill.
+- [ ] Each quest has explicit states, tracking, rewards/consequences, and a defined fail behavior (no silent soft-locks).
+- [ ] Environmental/diegetic delivery preferred over text-dumps and non-diegetic narration where the world can carry it.
+- [ ] All player-facing text externalized to keyed string tables; no concatenation; variables are named tokens; +30–40% expansion allowed.
+- [ ] VO lines have stable IDs, are written for the ear, and the script is locked before recording is proposed.
+
+## References
+
+- `references/branching-and-state.md` — topologies + diagrams, meaningful vs. illusory choice, state modeling, and the combinatorial-explosion containment kit.
+- `references/dialogue-tools.md` — Ink/Yarn/Twine/articy compared, the four primitives, a "pick one" guide, and the same conversation in three formats.
+- `references/environmental-storytelling.md` — show-don't-tell catalog, diegetic vs. non-diegetic delivery, systemic/emergent storytelling and the anecdote factory.

package/skills/game-storytelling/evals/README.md

@@ -0,0 +1,28 @@
+# Eval harness — `game-storytelling`
+
+Agent-run eval, not a shell script. A human or judge-agent drives a Claude Code
+agent and scores its behaviour against `cases.yaml`. There is no automated grader.
+
+`cases.yaml` has three blocks: `should_trigger` (7), `should_not_trigger` (5),
+and `capability` (2 scenarios with `must_include` rubrics).
+
+## A. Triggering accuracy
+
+Assert the skill fires on real narrative-design work (premise/pillars, branching
+and choice, dialogue-tool authoring, quests, environmental storytelling,
+ludonarrative harmony) and stays quiet on near-misses that belong to `game-design`
+(mechanics/balance), `level-design` (spatial layout), the engine skill (dialogue
+runner + save wiring), `marketing` (store/trailer copy), or plain prose fiction.
+Load only this skill, run each prompt in a fresh session for 3–5 trials, and score
+`should_trigger` as fire / `should_not_trigger` as don't-fire (bonus: routes to the
+named `route_to`). Pass bar: ≥90% correct decisions across all trials.
+
+## B. Capability uplift
+
+Run each `capability` scenario WITH vs WITHOUT the skill and score against its
+`must_include` rubric. The branching scenario checks the containment kit (2^N
+framing, foldback/reconvergence, gates, state-over-structure, real-vs-illusory
+choice) and engine-agnostic hand-off; the dissonance scenario checks the verb/
+reward audit and cheaper-piece fix. Pass bar: WITH the skill covers ≥80% of rubric
+points and clearly beats the baseline (which typically skips the explosion math,
+conflates fake stakes with real choice, and writes engine code instead of a graph).

package/skills/game-storytelling/evals/cases.yaml

@@ -0,0 +1,51 @@
+skill: game-storytelling
+
+should_trigger:
+  - prompt: "I'm making a narrative RPG and I want the whole story to branch based on player choices, but I'm terrified it'll balloon into thousands of scenes I can't write. How should I structure it?"
+    why: "Branching narrative + the combinatorial-explosion fear — the skill's core containment guidance (foldback, gates, reconvergence, state-over-structure). Structure of the narrative graph, not engine code."
+  - prompt: "Help me write the premise, theme, and pillars for my game before I start on any of the actual story content."
+    why: "Premise/theme/narrative-pillars foundation — the skill's 'do this first' section. Explicitly narrative-design groundwork, not mechanics or balance."
+  - prompt: "My dialogue in Ink feels like it has a hundred fake choices that all lead to the same line. How do I make the choices actually matter?"
+    why: "Meaningful choice vs. illusion of choice, in a portable dialogue format (Ink). The skill owns choice design and state; it is not Ink-engine wiring."
+  - prompt: "Players say my game's story doesn't match the gameplay — the character is supposed to be a pacifist healer but the whole loop is shooting enemies. What do I do?"
+    why: "Ludonarrative dissonance — the verb/reward audit and reconciliation is a flagship section. Non-obvious phrasing but squarely narrative-vs-mechanics harmony."
+  - prompt: "I need to design the quest structure for my game — how objectives are tracked, what happens on failure, and how side quests unlock. Can you help lay that out?"
+    why: "Quests & objectives: states, tracking, fail states, dependencies. The skill owns the quest state machine as a design artifact."
+  - prompt: "How can I tell the backstory of this abandoned station through the environment instead of dumping it all in audio logs?"
+    why: "Environmental / show-don't-tell storytelling — the skill's environmental section, preferring diegetic delivery over text-dumps."
+  - prompt: "Which tool should I use to author a branching dialogue tree — Yarn Spinner, Twine, or articy? And how do I keep it localization-ready?"
+    why: "Dialogue-tool selection (tools as pointers) plus localization-readiness — both explicit skill sections. Choosing/authoring the narrative, not wiring the runner into an engine."
+
+should_not_trigger:
+  - prompt: "Design the combat system for my game — how melee combos, stamina, and damage scaling should work and feel balanced."
+    route_to: "game-design"
+    why: "Core mechanics, systems, and balance — what the player DOES. The skill explicitly defers verbs/systems/economy/balance to game-design."
+  - prompt: "Lay out the blockout for this level — where the cover, sightlines, enemy spawns, and the sniper perch go."
+    route_to: "level-design"
+    why: "Spatial layout and encounter placement. The skill defers the geometry of a space (even story-bearing space) to level-design."
+  - prompt: "Wire my Ink story file into Unity — set up the InkRunner, bind the choices to UI buttons, and serialize the story state into my save system."
+    route_to: "unity"
+    why: "Engine integration: dialogue runner, UI binding, save/serialize. The skill authors portable narrative and hands wiring to the engine skill (here, unity)."
+  - prompt: "Write me a short story / novella set in my game's universe — just prose fiction, no choices or branching."
+    route_to: "none"
+    why: "Linear prose fiction with no interactive/branching structure is general creative writing, not interactive narrative design; the skill scopes to story-as-system."
+  - prompt: "Write the Steam store description and the launch trailer voiceover script to market my game."
+    route_to: "marketing"
+    why: "External-facing marketing copy, not in-game narrative. The skill defers store/trailer copy to marketing."
+
+capability:
+  - scenario: "A dev says: 'My branching RPG has about 12 major player choices and I want them all to matter, but I can't author 4000 scenes. And several of my choices feel fake — they lead to the same outcome.' Design the narrative structure."
+    must_include:
+      - "Names the combinatorial-explosion problem explicitly (roughly 2^N futures for N independent binary choices) as why 12 free choices is unauthorable"
+      - "Recommends a foldback / string-of-pearls topology with reconvergence (bottlenecks) so branches rejoin on load-bearing beats"
+      - "Uses gates and state-over-structure: model choices as named flags/variables and have one scene read the flag and swap lines, instead of duplicating scenes"
+      - "Distinguishes meaningful choice (a flag some later node reads back to the player) from illusion of choice, and says you may fake the outcome but never sell fake stakes as consequential"
+      - "Keeps a small budget of global/persistent choices (collapsed into summary variables for endings) while most choices stay local/weave"
+      - "Stays engine-agnostic: produces the narrative graph and a state/flag model, and hands runner/save wiring to the engine skill rather than writing engine code"
+  - scenario: "A dev says: 'Reviewers complain the story doesn't fit the game. My protagonist is written as a compassionate doctor, but the core loop is mowing down hundreds of soldiers.' Diagnose and fix."
+    must_include:
+      - "Identifies this as ludonarrative dissonance: the mechanics/verbs contradict the story the game tells"
+      - "Runs a verb audit (the dominant verb is 'kill', which contradicts 'compassionate doctor') and a reward audit (what the game rewards is the loudest narrative voice)"
+      - "Prefers fixing the cheaper piece — usually re-framing the narrative to match the mechanic — while flagging to game-design when only a mechanic change can resolve it"
+      - "Addresses reconciling failure/death fiction (respawns/checkpoints) with the story rather than leaving it unexplained"
+      - "Frames story as a system in service of play, not a layer of words bolted on to excuse the mechanics"

package/skills/game-storytelling/references/branching-and-state.md

@@ -0,0 +1,134 @@
+# Branching & state — topologies, choice, and containment
+
+Deep dive for the SKILL's "Narrative structures" and "Branching & choice" sections. This is engine-agnostic: model the graph and the state here; the engine skill (`godot`/`unity`/`unreal`) serializes and runs it.
+
+## The narrative topologies (ASCII)
+
+**Linear** — one path; agency is over pace, not direction.
+
+```
+A -> B -> C -> D -> E
+```
+
+**Branching tree** — choices split and (in the pure case) never rejoin. Author cost doubles at each fork.
+
+```
+        /-- B --< D
+A --<             \-- E
+        \-- C --< F
+                  \-- G
+```
+
+**Hub-and-spoke** — a central hub; the player picks self-contained spokes and returns. Agency is over *order* and *selection*.
+
+```
+        B
+        |
+  C --- HUB --- D      (return to HUB after each spoke)
+        |
+        E
+```
+
+**Foldback / string-of-pearls** — branches diverge, then **reconverge** at load-bearing beats ("pearls"). The between-pearl space stays small, so total scenes stay authorable while choices feel consequential. This is the workhorse for long branching stories.
+
+```
+        /-- b1 --\        /-- b3 --\
+BEAT1 --           -- BEAT2         -- BEAT3 -> ...
+        \-- b2 --/        \-- b4 --/
+```
+
+**Gauntlet / branch-and-bottleneck** — like foldback but branches can *drop out* (fail forward) into the main line rather than each reaching the bottleneck.
+
+Most shipped games are a **mix**: a foldback main line, hub-and-spoke for side content, environmental/systemic layered on top.
+
+## Meaningful choice vs. the illusion of choice
+
+A choice is **meaningful** only when all three legs hold:
+
+1. **Intent** — the player understands the options well enough to *want* one (not a blind coin-flip, unless blindness is the point).
+2. **Foreseeable consequence** — a plausible mental model of what each option does (even if the outcome surprises).
+3. **Consequence that lands** — the game later *reads the choice back*: a changed line, a locked door, a dead character, a different ending. If nothing ever reads the flag, the choice was noise.
+
+**Illusion of choice** — options that reconverge to the same outcome — is a legitimate, even essential tool, but only for the right job:
+
+| Illusion is fine for… | Illusion is a betrayal when… |
+| --- | --- |
+| **Expression / roleplay** — *how* your character says a thing (tone, personality) with the same result | it's dressed up as a **stakes** decision ("save her or let her die" → she dies either way, unacknowledged) |
+| **Pacing / tone** — letting the player set register without forking the plot | the player is told/led to believe it's consequential and later discovers it wasn't |
+| **Onboarding** — safe practice choices before real ones | you fake many in a row; players learn choices don't matter and disengage from *all* of them |
+
+Rule of thumb: **you may fake the outcome, never the stakes.** The moment a player catches a stakes-choice that didn't matter, they retroactively distrust every prior choice. Budget your few real, global choices and make them unmistakably land; let the many small choices be honest expression.
+
+### Kinds of consequence (make at least some visible)
+
+- **Immediate** — the next line/scene changes now (satisfying, cheap, local).
+- **Delayed** — pays off hours later (powerful, needs a flag and a reminder so the player *connects* it).
+- **Ambient** — world/NPC reactions, reputation, barks (cheap breadth; makes the world feel to be watching).
+- **Ending-level** — the choice(s) route the finale. Track with a small set of summary flags, not the full history.
+
+Delayed consequences only feel meaningful if the player can **attribute** them to the choice. Plant a callback ("because you spared him at the bridge…") or the payoff reads as random.
+
+## State: model it as named variables
+
+Story state is the spine of everything above. Model it explicitly; never encode meaning in duplicated scene copies.
+
+| State type | Example | Use for |
+| --- | --- | --- |
+| **Boolean flag** | `met_the_witch`, `betrayed_ally` | one-shot facts / gates |
+| **Counter** | `civilians_saved`, `times_lied` | thresholds, tallies, tone tracking |
+| **Enum / stage** | `witch_relationship = ally\|neutral\|enemy` | relationship / quest stages |
+| **Scalar / reputation** | `town_rep = -3..+3` | gradient reactions, gated content |
+| **Set / inventory** | `keys = {east, crypt}` | possession checks |
+
+Guidelines:
+
+- **Name for meaning, not mechanism** (`saved_the_child`, not `flag_37`). Future you and translators read these.
+- **Write once, read many.** A single scene that reads flags and swaps lines beats N near-duplicate scenes.
+- **Keep a state dictionary** — one table listing every variable, type, who sets it, who reads it. This is your single source of truth and your test plan.
+- **Derive, don't duplicate.** Compute "is the player a villain" from counters at read time rather than maintaining a parallel flag that can desync.
+- **Decide persistence with the engine skill.** *What* is saved (which variables survive a reload, a chapter, a new game+) is a design call you make; *how* it serializes is the engine skill's job.
+
+### A portable state-gated scene (Ink-flavored, illustrative)
+
+```ink
+VAR spared_bandit = false
+VAR town_rep = 0
+
+=== gate_market ===
+{ town_rep >= 2:
+    The guard nods you through. -> market
+- else:
+    "Your kind isn't welcome." -> turned_away
+}
+
+=== bandit_reappears ===
+{ spared_bandit:
+    The bandit you spared steps from the shadows — and returns the favor.
+- else:
+    A stranger eyes you coldly and says nothing.
+}
+-> continue
+```
+
+One scene, two behaviors, driven by state — not two authored scenes.
+
+## The combinatorial-explosion trap and how to contain it
+
+**The math:** N *independent* binary choices imply 2^N reachable states; 10 such choices is 1024 futures — unauthorable, untestable. Left unchecked, branching narrative collapses under its own content cost. Contain it deliberately:
+
+1. **Reconvergence (bottlenecks / foldback).** Funnel branches back to shared beats. Between two bottlenecks you only author the small local fan-out, not the global product. This is the single highest-leverage fix.
+2. **Gates.** Require a flag/level/item/reputation to open content. Gating *prunes the live branch set* — most branches aren't reachable in a given playthrough, so you don't pay to author their full downstream.
+3. **State over structure.** Replace divergent *scenes* with one scene that reads *variables*. You trade authored copies for conditional lines — linear content growth instead of exponential.
+4. **Locality (weave).** Keep most choices' effects inside the current scene; let them evaporate at the next bottleneck. Reserve a *small, named budget* of choices for global, persistent state (the ones that reach the ending).
+5. **Summary variables for endings.** Don't branch the finale on the full choice history; collapse it into a few axes (e.g. `mercy_score`, `faction`) and branch on those. Dozens of choices, a handful of endings.
+6. **Orthogonal, not multiplied.** Prefer choices that affect *different* subsystems (one changes a relationship, one changes the map) over choices that all modify the same outcome and must be cross-authored.
+
+### Testing a branching graph (design-side)
+
+- **Reachability** — every node reachable from start under *some* valid state; flag orphans.
+- **No dead ends / soft-locks** — every non-ending node has an exit; no state combination strands the player.
+- **Gate satisfiability** — every gated node is reachable by *some* path that can satisfy its condition (a locked door with no obtainable key is a bug).
+- **Flag hygiene** — every variable read is written somewhere first; no read-before-write.
+- **Ending coverage** — enumerate the summary-variable combinations and confirm each maps to an intended ending.
+
+Keep this list as the acceptance criteria you hand to the engine skill's implementation and QA.