Writing Game Scripts and Dialogue Trees
A game script is not a film script with blanks for lines. It's a technical document with states, conditions, and branches that is read simultaneously by a narrative designer and parsed by the dialogue engine. Writing a script that sounds good while correctly executing without an army of flags and hardcoding—a task requiring understanding of architecture from both sides.
Dialogue Tree Structure: Nodes, Edges, Conditions
A dialogue tree is a directed graph, not a tree in strict sense: one node can have multiple incoming edges, and can be reached from different narrative points. Each DialogueNode stores: speaker ID, line text, list of outgoing edges (DialogueEdge[]), optional list of entry conditions, and list of actions (game world event triggers).
Conditions are game state checks: QuestFlag("rescued_merchant") == true, PlayerLevel >= 5, Reputation("thieves_guild") > 30. If no condition of an incoming line is met—the branch is hidden or replaced with fallback line.
Actions are game world impacts: give quest, add item, change reputation, play animation, start cutscene. Actions attach to nodes or edges (when selecting answer option).
This separation of conditions and actions is the foundation of any narrative system. Doesn't matter if implemented in Yarn Spinner, Ink, Dialogue System for Unity, or custom editor—the logic is the same.
Yarn Spinner and Ink: Real Difference
Yarn Spinner is a text format with syntax close to Twine. Conditions are written right in script: <<if $player_level >= 5>>. Commands: <<jump NodeName>>, <<set $flag = true>>. Good for linear dialogs with branches, easy to edit for writers without technical background. Integrates into Unity via official package with DialogueRunner component.
Ink is a more powerful language with "knots" and "diverts" concepts, support for visit counters (visited, visit_count) and weave-structure for parallel narrative flows. Used in Disco Elysium, 80 Days, Heaven's Vault. For complex narratives with interaction history tracking, Ink is usually cleaner.
Tool choice depends on narrative complexity: for 200 lines of dialog in action-RPG, Yarn Spinner suffices; for narrative game with 100k+ words and branching story—Ink or custom solution.
Writing Lines That Work Technically
Each line must function without previous context—because player can reach this node from different branches. Verified simply: read the line in isolation. If unclear—need fallback context or restructuring.
Answer options shouldn't be semantically empty. "Yes," "No," "Tell more"—bad options: they don't convey character. "I've heard this already" / "Go on, I'm interested" / "No time—what's needed?"—these are character-voiced options.
Localization keys. Each string gets unique ID (NPC_MERCHANT_GREETING_01)—not ordinal number. In localization, translator sees context in ID, not guessing what string #847 is. Standard practice with LocalizationTable in Unity Localization package.
Narrative Design: Quests and Structure
Separate scope—writing quest dialogs with quest states in mind. One NPC can have different lines depending on QuestState: NotStarted, InProgress, ObjectiveComplete, Turned In, Failed. This is minimum 5 dialogue tree versions per quest, or one tree with conditional branches for each state.
Typical mistake: write dialogs only for NotStarted and InProgress, forget Turned In—player after quest submission hears task assignment again. QA catches it, but fixes require both narrative and programmer work.
Dialog as mechanic teaching. Most effective tutorial dialogs don't say "press X to attack"—they embed teaching in narrative: "Show me how you handle a sword" with following forced encounter. Script and level design are written together.
Timeline Guidelines
| Scale | Volume | Timeframe |
|---|---|---|
| Small | 1–3 quests, ~500 lines | 1–2 weeks |
| Medium | Main story + side quests, ~3000–5000 lines | 1–2 months |
| Large | Full narrative system, 20k+ lines | 3–6 months |
Script Development Process
Start with narrative document: who's the character, what are their motivations, what should player learn and feel after dialog. Only then—node structure in tool (Yarn Spinner Visual Editor or Articy:Draft). Draft dialog → technical review for condition/action feasibility → revision → final text.
Mandatory stage—manually test all branches in editor with logs enabled: which node loaded, which condition triggered. This finds "dead" branches with no path, and nodes without exit, hanging dialog.