@ericrisco/rsc 0.1.34 → 0.1.36

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.

package/skills/game-storytelling/references/dialogue-tools.md

@@ -0,0 +1,117 @@
+# Dialogue tools — the four primitives, a pick-one guide, and one conversation in three formats
+
+Deep dive for the SKILL's "Dialogue systems" section. **Engine-agnostic:** author dialogue in a portable format here; the engine skill (`godot`/`unity`/`unreal`) wires the runner, presenter, save/serialize, and any plugin. Do not write engine binding code in this skill.
+
+## Every tool reduces to four primitives
+
+Design against these, then map them onto whichever tool the project uses:
+
+| Primitive | What it is | Ink | Yarn Spinner | Twine (Twee) | articy:draft X |
+| --- | --- | --- | --- | --- | --- |
+| **Node** | addressable unit of content | knot `=== name ===` / stitch `= name` | node with `title:` + `===` end | passage `:: Name` | flow / dialogue fragment |
+| **Condition** | boolean over state gating content | `{ cond: ... }`, `{ cond: a \| b }` | `<<if $x>> ... <<endif>>` | `(if: $x)[...]` (Harlowe) / `<<if $x>>` (SugarCube) | condition node / expression on a pin |
+| **Variable** | the story state read/written | `VAR x = 0`, `~ x = 1` | `<<set $x to 1>>` | `(set: $x to 1)` / `<<set $x = 1>>` | global variable in the variable set |
+| **Effect** | side effect a node fires | `~ func()`, tags `#`, external funcs | `<<command>>`, functions, `<<set>>` | macros, `<<run>>` (SugarCube) | instruction node / script pin |
+
+If you can express a conversation in these four primitives, it ports to any of the tools below.
+
+## The tools (pointers, current as of 2026)
+
+### Ink — inkle's narrative scripting language
+- **Shape:** a writer-first *language* (not a visual editor). Text is the default; logic is woven in. Prose-heavy, highly expressive.
+- **Core syntax:** knots `=== name ===`, stitches `= name`, diverts `-> name`, once-only choices `*`, sticky choices `+`, gathers `-`, weave (nested choices/gathers), `VAR`, `CONST`, `LIST` (state machines / multi-value), conditionals `{ }`, tunnels `-> x ->`, threads `<- x`, functions, tags `#`, glue `<>`.
+- **Runtime:** compiles to JSON; run with **inkjs** (web/JS) or engine integrations (Unity's `ink-unity-integration`; community Godot integrations). **Inky** is the authoring editor with live preview.
+- **Best for:** branching prose, interactive fiction, dialogue with lots of state and reincorporation. Weakest as a visual overview for non-writers.
+
+### Yarn Spinner — the friendly dialogue tool (v3.x current)
+- **Shape:** node-based, screenplay-ish; friendlier to designers and non-programmers than raw Ink. Nodes edit well in a graph or plain text.
+- **Core syntax:** node = header (`title: Name`) + `---` + body + `===`; options with `->`; `<<set $x to 1>>`, `<<if>>/<<elseif>>/<<else>>/<<endif>>`, `<<jump Node>>`, `<<declare>>`, custom `<<commands>>`, functions, and inline markup `[b]...[/b]`.
+- **Runtime & engines:** first-class **Unity** support; **Godot** via official C# (beta) and GDScript (alpha) integrations; **Unreal** integration in progress for 2026. String tables export for localization are built in.
+- **Best for:** game dialogue with a designer-writer split, VO line management, and Unity projects.
+
+### Twine — visual hypertext editor
+- **Shape:** a **visual node editor** that publishes a self-contained HTML file. Lowest barrier to entry; excellent for prototyping and interactive fiction shipped as a web page.
+- **Story formats matter:** scripting depends on the chosen format — **Harlowe** (default, macro-based `(set:)/(if:)`), **SugarCube** (`<<set>>/<<if>>`, save system, richer for games), **Snowman** (JS-forward), **Chapbook** (prose-forward). Pick the format for the job.
+- **Twee** is Twine's plain-text form (`:: Passage` headers) — version-controllable and a good neutral interchange for design even if the game engine isn't Twine.
+- **Best for:** prototyping branches fast, web-delivered IF, and design-time storyboarding. Not a drop-in engine dialogue runtime for a AAA build.
+
+### articy:draft X — visual narrative database (commercial)
+- **Shape:** a heavyweight **narrative DB + flow editor**. Models flow fragments, dialogue fragments, hubs, conditions, instructions, plus a full entity/location/variable database and templates. Built for large teams and large scripts.
+- **Pipeline:** free **Unity** and **Unreal** importers pull dialogues, entities, variables, and localization in cleanly; a **Generic Engine Export** produces JSON (+ optional assets) for any custom engine. Runs on Windows and macOS.
+- **Best for:** big branching RPGs, teams that need a shared narrative database, template-driven content, and translation at scale. Overkill for a small project.
+
+## Pick one — a fast decision guide
+
+| If… | Reach for |
+| --- | --- |
+| Prose-heavy IF, lots of state, writer-driven | **Ink** |
+| Game dialogue, designer/writer split, Unity, VO + loc built in | **Yarn Spinner** |
+| Rapid prototype, web-delivered, or teaching branching visually | **Twine** (SugarCube for game-like saves) |
+| Large team, huge script, shared entity/variable DB, Unity/Unreal | **articy:draft X** |
+| You just need a portable design artifact, engine undecided | **Twee** or an Ink file (both are plain text, diff-able) |
+
+When the engine is fixed, let the **engine skill** confirm the best-supported integration; when it isn't, author in plain-text (Ink/Twee) so nothing locks you in.
+
+## The same conversation, three formats
+
+A guard who lets you pass only if `has_pass` is true; otherwise you can bribe (needs `gold >= 10`) or leave.
+
+**Ink**
+```ink
+VAR has_pass = false
+VAR gold = 0
+
+=== gate ===
+The guard blocks the door.
+{ has_pass:
+    "Pass, citizen." -> town
+}
+* [Offer a bribe] { gold >= 10:
+        ~ gold = gold - 10
+        The guard pockets it. -> town
+    - else:
+        "You're ten short." -> gate
+    }
+* [Leave] -> street
+```
+
+**Yarn Spinner**
+```yarn
+title: Gate
+---
+The guard blocks the door.
+<<if $has_pass>>
+    Guard: Pass, citizen.
+    <<jump Town>>
+<<endif>>
+-> Offer a bribe <<if $gold >= 10>>
+    <<set $gold = $gold - 10>>
+    The guard pockets it.
+    <<jump Town>>
+-> Leave
+    <<jump Street>>
+===
+```
+
+**Twee (SugarCube)**
+```twee
+:: Gate
+The guard blocks the door.
+<<if $has_pass>>Guard: "Pass, citizen." [[Town]]<<else>>\
+[[Offer a bribe->Bribe]]
+[[Leave->Street]]
+<</if>>
+
+:: Bribe
+<<if $gold gte 10>><<set $gold to $gold - 10>>The guard pockets it. [[Town]]\
+<<else>>"You're ten short." [[Gate]]<</if>>
+```
+
+Same four primitives (node / condition / variable / effect), three syntaxes. Design once; the engine skill binds it.
+
+## Delivery notes (design-side)
+
+- **Barks vs. conversations** — short, interruptible one-liners (barks) need a priority + cooldown model so they don't stack or repeat; full conversations need focus/turn-taking. Design them as different node types.
+- **Line IDs & loc** — every player-facing line carries a stable id and lives in a string table (see the SKILL's localization notes). Ink tags, Yarn's string-table export, and articy's loc columns all support this; use them.
+- **Never concatenate** sentence fragments across variables for grammar (gender/plural/word order) — author full templated lines with named placeholders.
+- **Presentation is the engine's job** — typewriter effect, portraits, camera, choice-timer UI, skip/auto — hand these to the engine skill; keep the dialogue content pure.

package/skills/game-storytelling/references/environmental-storytelling.md

@@ -0,0 +1,71 @@
+# Environmental & systemic storytelling — show, don't tell
+
+Deep dive for the SKILL's "Environmental & systemic storytelling" section. The goal: deliver story *through the world and its rules* so the player assembles meaning and owns it, instead of being narrated at. Engine-agnostic; coordinate the *space* with `level-design` and the *rules* with `game-design`.
+
+## Why show over tell
+
+Told information is received; discovered information is *earned*. A player who infers "someone died here defending this door" from a skeleton, a spent revolver, and claw marks believes it more, and remembers it longer, than the same fact in a text box. Reserve telling (codex, narrator, log dumps) for what the world genuinely cannot carry — precise numbers, distant history, abstract rules.
+
+**Show-don't-tell ladder** (prefer the top; fall back only when needed):
+
+1. **Enacted** — it happens in front of the player through play (an ally sacrifices themselves in a scripted-but-interactive beat).
+2. **Environmental** — the world's state implies the event (aftermath, traces, arrangement).
+3. **Overheard / ambient** — barks, one-sided radio, NPCs talking to each other.
+4. **Readable in-world** — item descriptions, signage, graffiti, terminals that *belong* to the world.
+5. **Collectible logs** — audio logs, diaries, notes. Useful but the most "tell"-like; easy to overuse.
+6. **Non-diegetic** — narrator, codex, cutscene exposition, HUD text. Last resort.
+
+## Environmental storytelling — the technique catalog
+
+- **Set dressing with intent.** Every prop can carry meaning: a single toy in a barracks, wedding photos in a looted home. Composition points the eye (leading lines, light, framing a key object) — coordinate with `level-design` and lighting.
+- **Aftermath / the frozen moment.** Show the scene *after* the event and let the player reconstruct it: overturned table, blood trail, a meal half-eaten. The gap between "what I see" and "what happened" is the story.
+- **Traces & evidence.** Bullet holes, scorch marks, footprints in dust, a barricade built from the wrong side. Physical cause-and-effect the player reads like a detective.
+- **Spatial sequencing.** The *order* the player encounters space tells a story: descend from opulence into rot; a triumphant mural, then the mass grave behind it. The space is a sentence; its layout is the grammar (a `level-design` collaboration).
+- **Object placement & juxtaposition.** Meaning from adjacency — a child's drawing pinned above a weapons cache; a prayer shrine facing a bricked-up window.
+- **Readable descriptions.** Item and examine text that implies a life ("Dented canteen. Someone scratched three tally marks and stopped."). Small, optional, high-flavor; rewards curiosity without gating.
+- **World-state change.** The strongest environmental beat: the space *changes* in response to the player or the plot (a hub burns, a garden regrows, a faction's banners replace another's). The player sees consequence written on the world.
+- **Absence.** What's missing tells a story too — an empty crib, a cleared-out desk, a name scratched off a roster.
+
+Guardrails:
+
+- **Legibility vs. mystery.** Give enough signal that most players read the intended gist, with deeper layers for the attentive. If *no one* gets it, it's decoration, not storytelling; if it's spelled out, it's a text box.
+- **Consistency = trust.** Once the world's props reliably mean things, players *read* every scene. One arbitrary/contradictory arrangement teaches them to stop looking.
+- **Optional, not load-bearing.** Environmental story enriches; don't hide *required* plot solely in a missable detail. Critical beats need a guaranteed channel.
+
+## Diegetic vs. non-diegetic delivery
+
+| | Diegetic (in-world) | Non-diegetic (outside the fiction) |
+| --- | --- | --- |
+| **Examples** | signage, barks, radio, environmental change, in-world terminals | narrator VO, codex/lore menu, HUD text, tutorial popups, cutscene title cards |
+| **Feel** | immersive, earned, "the world tells me" | efficient, precise, "the game tells me" |
+| **Use for** | mood, place, character, consequence, most story | exact numbers, dense history, rules the world can't show, accessibility |
+| **Cost of overuse** | can be missed/ambiguous | breaks immersion; reads as a lecture |
+
+**Diegetic first.** Push information into the world; drop to non-diegetic only for what the world can't carry. Note the honest exceptions: **accessibility** (subtitles, clear objective text, difficulty-scaled hints) and **usability** (a control prompt) are worth a non-diegetic cost — never sacrifice comprehension for purity.
+
+## Systemic & emergent storytelling — the anecdote factory
+
+Scripted story is *authored*; systemic story is *generated* by rules + player + world state producing events no writer placed. The famous colonist who starved defending the fridge, the rival who keeps hunting you across a sandbox — nobody wrote those; the systems did.
+
+You don't write these stories. You design the **conditions and vocabulary** that let them happen and be legible — an "anecdote factory." This is primarily a `game-design` collaboration; your narrative-design job is to make the output *readable as story*.
+
+Design levers:
+
+- **Legible actors** — entities with names, traits, memory, and relationships (a guard who remembers you spared him). Persistent identity turns a system event into a *character* moment.
+- **Consequence that persists** — the world remembers and reflects actions (reputation, scars, changed factions), so events chain into arcs instead of resetting.
+- **Readable causality** — the player can *see why* something happened (a needs/mood readout, a reaction bark, a kill-cam). An unexplained emergent event is just noise; a readable one is an anecdote.
+- **Framing & capture** — surfacing tools (event log, photo mode, relationship screen, killfeed, end-of-run summary) that let the player *notice and retell* the story the systems produced. The retelling is the payoff.
+- **Meaningful randomness** — variety within authored bounds (curated event pools, weighted tables) so runs differ without becoming incoherent.
+- **Interacting systems** — emergence needs ≥2 systems that touch (fire + wind + wood; hunger + weather + AI). One system alone produces events, not stories.
+
+Guardrails:
+
+- **Coherence budget.** Pure emergence drifts into nonsense; pure authorship can't surprise. Set authored guardrails (tone, bounds, curated pools) inside which systems play.
+- **Framing is half the work.** An emergent event the player never notices or can't interpret isn't a story. Invest in the surfacing/retelling tools as much as the simulation.
+- **Name things.** Named actors, places, and factions convert anonymous system state into story the player cares about and repeats.
+
+## Where this hands off
+
+- **`level-design`** — owns the physical space, blockout, sightlines, and encounter flow that environmental beats live inside. Co-own set-dressing that carries narrative.
+- **`game-design`** — owns the systems whose interaction produces emergent story; you specify what must be *legible* and *persistent* for those events to read as narrative.
+- **the engine skill** (`godot`/`unity`/`unreal`) — implements world-state changes, triggers, bark systems, event logs, and the persistence that makes consequence stick.