dialogue-systems Checked

{
  "start": "guard_intro",
  "nodes": {
    "guard_intro": {
      "speaker": "Guard", "line": "DLG_GUARD_001",
      "choices": [
        { "text": "DLG_OPT_BRIBE", "to": "bribe", "if": "gold >= 50" },
        { "text": "DLG_OPT_LEAVE", "to": "end" }
      ]
    },
    "bribe": {
      "speaker": "Guard", "line": "DLG_GUARD_BRIBED",
      "set": { "gate_open": true, "gold": "gold - 50" },
      "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 full interpreter that walks

this graph is in references/runner.md.

### 2. Runner step (a state machine over the graph)

# The runner holds the current node and a variable store; the UI calls advance().
func present(node):
    if node.has("line"):
        ui.show_line(node.speaker, localize(node.line))
    if node.has("choices"):
        var shown = node.choices.filter(func(c): return eval_cond(c.get("if", "")))
        ui.show_choices(shown)            # only choices whose condition passes

func choose(choice):                       # called when the player clicks a choice
    apply_set(choice.get("set", {}))       # write variables
    goto(choice.to)

func goto(id):
    current = graph.nodes[id]
    apply_set(current.get("set", {}))
    if current.get("end", false): ui.close(); return
    present(current)
    if current.has("next") and not current.has("choices"):
        goto(current.next)                 # auto-advance linear nodes

### 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 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), but that 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.