Dialogue systems
Model conversations as a graph: nodes hold lines, choices branch the flow,
conditions gate options, and variables remember what the player did. The first
real decision is build vs. buy — adopt a proven authoring tool (Ink or
Yarn Spinner) or write a small data-driven runner. This skill owns both Ink
and Yarn; the visual-novel and rpg genres consume it.
When to use
- Use to design branching conversations, choice menus, or narrative state
(flags, relationship values) that affect later dialogue.
- Use to decide between Ink, Yarn Spinner, and a custom JSON/resource format.
- Use to wire a dialogue script into your game loop (advance line, present
choices, run commands, resolve variables).
When not to use: for engine UI (text boxes, portraits, choice buttons), use
godot-ui-control or the engine's UI skill. For persisting narrative variables
across sessions, use save-systems. For data-as-resources in Godot/Unity, see
godot-resources / unity-scriptableobjects.
Core workflow
- Choose the authoring approach.
- Ink — prose-first, writer-friendly, weave/gather flow; great for
dialogue-heavy or CYOA narrative. Integrate via ink runtime / inkle plugins.
- Yarn Spinner — node-based, explicit
<<commands>>, strong for
game-driven dialogue with lots of engine hooks.
- Custom runner — a JSON/resource graph + a small interpreter when you need
full control or minimal dependencies. Don't build a language; build a graph.
- Define the node contract. A node yields one of: a line (speaker + text),
a set of choices, a command/side-effect, or an end/jump. The runner advances
through nodes and hands lines/choices to the UI.
- Separate variables from flow. Keep a variable store (booleans, numbers,
strings) the dialogue reads/writes; gate choices with conditions over it.
- Localize from the start. Author with line IDs, not raw strings, so the
displayed text comes from a string table keyed by locale.
- Drive it from the game loop. The runner is a state machine:
current node
→ emit content → wait for input (continue or choice) → advance.
- Verify by walking branches. Exercise each choice path; confirm conditions,
variable writes, and that every branch reaches an end or a valid jump.
Patterns
1. Engine-neutral dialogue graph (data, not code)
{
"start": "guard_intro",
"nodes": {
"guard_intro": {
"speaker": "Guard", "line": "DLG_GUARD_001",
"choices": [
{ "text": "DLG_OPT_BRIBE", "to": "bribe", "if": "gold >= 50",
"set": { "gold": "gold - 50" } },
{ "text": "DLG_OPT_LEAVE", "to": "end" }
]
},
"bribe": {
"speaker": "Guard", "line": "DLG_GUARD_BRIBED",
"set": { "gate_open": true },
"next": "end"
},
"end": { "end": true }
}
}
line/text are string-table IDs (localization), not literal text. if
gates a choice; set mutates the variable store. The gold cost sits on the
choice, so it is paid once per pick even if the bribe node is revisited; the
idempotent gate_open write can live on the node. A string set value is an
expression, so a literal string needs inner quotes: "mood": "'angry'". The full
interpreter that walks this graph is in references/runner.md.
2. Runner step (a state machine over the graph)
# Godot 4.7. The runner holds the current node and a variable store. Every line
# waits for the player: the UI calls choose() or the continue callback.
func goto(id: String) -> void:
current = graph.nodes[id]
apply_set(current.get("set", {}))
if current.get("end", false):
ui.close()
return
if current.has("line"):
ui.show_line(current.get("speaker", ""), localize(current.line))
if current.has("choices"):
var shown = current.choices.filter(func(c): return eval_cond(c.get("if", "")))
ui.show_choices(shown) # only choices whose condition passes
elif current.has("next"):
var next_id: String = current.next
ui.show_continue(func(): goto(next_id)) # advance when the player continues
func choose(choice: Dictionary) -> void: # called when the player picks a choice
apply_set(choice.get("set", {})) # write on the transition (revisit-safe)
goto(choice.to)
3. Ink — branching with knots, choices, and variables (inkle)
// Ink: '*' = once-only choice, '+' = sticky. [bracketed] text shows only in the
// choice, not the printed result. '->' diverts; '-> END' stops the flow.
VAR gold = 60
-> guard_intro // the story starts at the top: divert into a knot
=== guard_intro ===
The guard blocks the gate.
* {gold >= 50} [Offer 50 gold] "Here, take it."
~ gold = gold - 50
The guard pockets it and steps aside. -> END
* [Leave] You turn back. -> END
Ink tracks how often each knot was seen, so {visited_knot} is a built-in
condition. Variables are global (VAR) or temporary (~ temp).
4. Yarn Spinner — nodes, options, and commands (Yarn Spinner 3.x)
title: GuardIntro
---
<<declare $gold = 60>>
<<declare $gate_open = false>>
Guard: You can't pass.
-> Offer 50 gold <<if $gold >= 50>>
<<set $gold = $gold - 50>>
Guard: ...fine. Go on through.
<<set $gate_open to true>>
-> Leave
Guard: Good choice.
===
Yarn lines may start with Speaker:; options use ->; <<set>>/<<declare>>
manage $variables; <<if>> gates an option; <<jump NodeName>> moves between
nodes. Interpolate values in text with {$gold}. Declare every variable before first
use: an undeclared one still compiles (Yarn infers its type and a zero/false/empty
start value) with only a warning, which hides typos. These constructs are unchanged from
Yarn Spinner 2.x.
Pitfalls
- Hardcoding display strings instead of line IDs makes localization a
rewrite. Author against a string table from day one.
- Inventing a scripting language for a simple branching tree. If you only
need lines + choices + flags, a JSON/resource graph plus a 50-line runner beats
a parser you must maintain. Use Ink/Yarn when writers need real flow control.
- Variables coupled to the UI: store narrative state separately so the same
dialogue works in cutscenes, menus, and tests. Persist it via
save-systems.
- Unreachable or dead-end nodes: a node with no
next, choices, or end
silently stalls. Validate that every node terminates or branches.
- Mutating state in a line node the player can revisit double-applies (
gold
drained twice). Apply set on the transition, or guard with a seen-flag.
- Mixing Ink's
* (once-only) and + (sticky) by accident: looped menus
need sticky + choices or the options vanish after one use.
References
references/ink-and-yarn.md — side-by-side syntax cheat sheet (choices,
diverts/jumps, variables, conditions, includes) and integration notes.
references/runner.md — a complete custom dialogue runner: graph schema,
condition/expression evaluation, variable store, and localization lookup.
Related skills
save-systems — persist narrative variables and seen-flags.
godot-resources, unity-scriptableobjects — store dialogue as engine data.
godot-ui-control — render text boxes, portraits, and choice buttons.
visual-novel, rpg — genres that compose this skill.
1---2name: dialogue-systems3description: >4 Build branching dialogue and narrative — a node/choice graph with conditions,5 variables, and localization hooks — and choose between authoring tools Ink and6 Yarn Spinner or a custom data-driven runner. Engine-neutral. Use when the user7 mentions dialogue system, branching dialogue, conversation tree, choices,8 Ink (.ink), Yarn Spinner (.yarn), or NPC dialogue.9metadata:10 source: https://skillmd.com/skills/junmystery/dialogue-systems11---1213# Dialogue systems1415Model conversations as a **graph**: nodes hold lines, choices branch the flow,16conditions gate options, and variables remember what the player did. The first17real decision is *build vs. buy* — adopt a proven authoring tool (**Ink** or18**Yarn Spinner**) or write a small data-driven runner. This skill owns both Ink19and Yarn; the `visual-novel` and `rpg` genres consume it.2021## When to use2223- Use to design branching conversations, choice menus, or narrative state24 (flags, relationship values) that affect later dialogue.25- Use to decide between Ink, Yarn Spinner, and a custom JSON/resource format.26- Use to wire a dialogue script into your game loop (advance line, present27 choices, run commands, resolve variables).2829**When *not* to use:** for engine UI (text boxes, portraits, choice buttons), use30`godot-ui-control` or the engine's UI skill. For persisting narrative variables31across sessions, use `save-systems`. For data-as-resources in Godot/Unity, see32`godot-resources` / `unity-scriptableobjects`.3334## Core workflow35361. **Choose the authoring approach.**37 - **Ink** — prose-first, writer-friendly, weave/gather flow; great for38 dialogue-heavy or CYOA narrative. Integrate via ink runtime / inkle plugins.39 - **Yarn Spinner** — node-based, explicit `<<commands>>`, strong for40 game-driven dialogue with lots of engine hooks.41 - **Custom runner** — a JSON/resource graph + a small interpreter when you need42 full control or minimal dependencies. Don't build a *language*; build a graph.432. **Define the node contract.** A node yields one of: a line (speaker + text),44 a set of choices, a command/side-effect, or an end/jump. The runner advances45 through nodes and hands lines/choices to the UI.463. **Separate variables from flow.** Keep a variable store (booleans, numbers,47 strings) the dialogue reads/writes; gate choices with conditions over it.484. **Localize from the start.** Author with **line IDs**, not raw strings, so the49 displayed text comes from a string table keyed by locale.505. **Drive it from the game loop.** The runner is a state machine: `current` node51 → emit content → wait for input (continue or choice) → advance.526. **Verify by walking branches.** Exercise each choice path; confirm conditions,53 variable writes, and that every branch reaches an end or a valid jump.5455## Patterns5657### 1. Engine-neutral dialogue graph (data, not code)5859```json60{61 "start": "guard_intro",62 "nodes": {63 "guard_intro": {64 "speaker": "Guard", "line": "DLG_GUARD_001",65 "choices": [66 { "text": "DLG_OPT_BRIBE", "to": "bribe", "if": "gold >= 50",67 "set": { "gold": "gold - 50" } },68 { "text": "DLG_OPT_LEAVE", "to": "end" }69 ]70 },71 "bribe": {72 "speaker": "Guard", "line": "DLG_GUARD_BRIBED",73 "set": { "gate_open": true },74 "next": "end"75 },76 "end": { "end": true }77 }78}79```8081`line`/`text` are **string-table IDs** (localization), not literal text. `if`82gates a choice; `set` mutates the variable store. The gold cost sits on the83*choice*, so it is paid once per pick even if the `bribe` node is revisited; the84idempotent `gate_open` write can live on the node. A string `set` value is an85expression, so a literal string needs inner quotes: `"mood": "'angry'"`. The full86interpreter that walks this graph is in `references/runner.md`.8788### 2. Runner step (a state machine over the graph)8990```gdscript91# Godot 4.7. The runner holds the current node and a variable store. Every line92# waits for the player: the UI calls choose() or the continue callback.93func goto(id: String) -> void:94 current = graph.nodes[id]95 apply_set(current.get("set", {}))96 if current.get("end", false):97 ui.close()98 return99 if current.has("line"):100 ui.show_line(current.get("speaker", ""), localize(current.line))101 if current.has("choices"):102 var shown = current.choices.filter(func(c): return eval_cond(c.get("if", "")))103 ui.show_choices(shown) # only choices whose condition passes104 elif current.has("next"):105 var next_id: String = current.next106 ui.show_continue(func(): goto(next_id)) # advance when the player continues107108func choose(choice: Dictionary) -> void: # called when the player picks a choice109 apply_set(choice.get("set", {})) # write on the transition (revisit-safe)110 goto(choice.to)111```112113### 3. Ink — branching with knots, choices, and variables (inkle)114115```ink116// Ink: '*' = once-only choice, '+' = sticky. [bracketed] text shows only in the117// choice, not the printed result. '->' diverts; '-> END' stops the flow.118VAR gold = 60119-> guard_intro // the story starts at the top: divert into a knot120121=== guard_intro ===122The guard blocks the gate.123* {gold >= 50} [Offer 50 gold] "Here, take it."124 ~ gold = gold - 50125 The guard pockets it and steps aside. -> END126* [Leave] You turn back. -> END127```128129Ink tracks how often each knot was seen, so `{visited_knot}` is a built-in130condition. Variables are global (`VAR`) or temporary (`~ temp`).131132### 4. Yarn Spinner — nodes, options, and commands (Yarn Spinner 3.x)133134```yarn135title: GuardIntro136---137<<declare $gold = 60>>138<<declare $gate_open = false>>139Guard: You can't pass.140-> Offer 50 gold <<if $gold >= 50>>141 <<set $gold = $gold - 50>>142 Guard: ...fine. Go on through.143 <<set $gate_open to true>>144-> Leave145 Guard: Good choice.146===147```148149Yarn lines may start with `Speaker:`; options use `->`; `<<set>>`/`<<declare>>`150manage `$variables`; `<<if>>` gates an option; `<<jump NodeName>>` moves between151nodes. Interpolate values in text with `{$gold}`. Declare every variable before first152use: an undeclared one still compiles (Yarn infers its type and a zero/false/empty153start value) with only a warning, which hides typos. These constructs are unchanged from154Yarn Spinner 2.x.155156## Pitfalls157158- **Hardcoding display strings** instead of line IDs makes localization a159 rewrite. Author against a string table from day one.160- **Inventing a scripting language** for a simple branching tree. If you only161 need lines + choices + flags, a JSON/resource graph plus a 50-line runner beats162 a parser you must maintain. Use Ink/Yarn when writers need real flow control.163- **Variables coupled to the UI**: store narrative state separately so the same164 dialogue works in cutscenes, menus, and tests. Persist it via `save-systems`.165- **Unreachable or dead-end nodes**: a node with no `next`, choices, or end166 silently stalls. Validate that every node terminates or branches.167- **Mutating state in a line node the player can revisit** double-applies (`gold`168 drained twice). Apply `set` on the transition, or guard with a seen-flag.169- **Mixing Ink's `*` (once-only) and `+` (sticky)** by accident: looped menus170 need sticky `+` choices or the options vanish after one use.171172## References173174- `references/ink-and-yarn.md` — side-by-side syntax cheat sheet (choices,175 diverts/jumps, variables, conditions, includes) and integration notes.176- `references/runner.md` — a complete custom dialogue runner: graph schema,177 condition/expression evaluation, variable store, and localization lookup.178179## Related skills180181- `save-systems` — persist narrative variables and seen-flags.182- `godot-resources`, `unity-scriptableobjects` — store dialogue as engine data.183- `godot-ui-control` — render text boxes, portraits, and choice buttons.184- `visual-novel`, `rpg` — genres that compose this skill.