godot-dialogue-system

Dialogue System

Data-driven dialogue routing — not beginner typewriter tutorials.

NEVER Do in Dialogue Systems

• NEVER hardcode dialogue text in GDScript — Store lines in Resources / JSON / CSV so localization works.
• NEVER show choices the player has not unlocked — Hide (or intentionally gray) gated options.
• NEVER use unvalidated loose strings for node transitions — Typos in next_node_id soft-lock mid-convo; assert / registry IDs.
• NEVER force a typewriter without skip — Click/confirm must finish the line immediately.
• NEVER drive reveal with per-character Timer / OS.delay_msec() — Use visible_ratio / visible_characters + Tween (see typebox_effect.gd).
• NEVER store dialogue cursor state only in the UI node — Scene changes drop the player; keep progress in the manager Autoload / session object.
• NEVER get_node() from NPCs into Dialogue UI — Start via manager signals (start_dialogue(res)).
• NEVER invent regex for BBCode — Prefer RichTextLabel BBCode / custom effects.
• NEVER save/load inside a dialogue node Resource — Nodes are data; persistence belongs to SaveSystem.
• NEVER hardcode portrait paths in code — Assign textures on node Resources or a portrait database.

---

Decision Tree: Authoring Engine

Authoring need	Engine	MANDATORY scripts	Do NOT Load
Designer-friendly .tres graphs in-repo	Resource Autoload graph	dialogue_resource.gd → dialogue_manager_singleton.gd → dialogue_ui_controller.gd → typebox_effect.gd	dialogue_engine.gd JSON path
External writers / spreadsheet → JSON	JSON graph engine	dialogue_engine.gd (+ optional dialogue_manager.gd) → UI + typebox	Resource Autoload stack
Visual node editor in-project	GraphEdit authoring	Keep runtime on Resource or JSON export; GraphEdit is editor-only tooling	Shipping GraphEdit as the runtime walker
Conditions / quest gates	Either	branching_condition_validator.gd	Embedding flag checks in UI buttons
Portraits / expressions	Either	dialogue_portrait_manager.gd	—
Localization keys	Either	localized_dialogue_resource.gd	Hardcoded language if trees
Quest / gameplay hooks from lines	Either	dialogue_event_bridge.gd	Side effects inside UI controller

Default golden path: Resource Autoload → UI controller → typebox_effect. Pick one runtime engine; do not run Resource manager and JSON engine in parallel.

Available Scripts (single catalog)

Runtime (golden path)

• dialogue_resource.gd — conversation tree Resource
• dialogue_node_data.gd — single line / speaker / portrait metadata
• dialogue_option_data.gd — choice + conditions
• dialogue_manager_singleton.gd — MANDATORY Autoload walker + signals
• dialogue_ui_controller.gd — MANDATORY labels / choice buttons
• typebox_effect.gd — MANDATORY skip-safe Tween visible_ratio reveal

Supporting

• dialogue_event_bridge.gd — fire gameplay events from nodes
• branching_condition_validator.gd — flag/stat gates
• localized_dialogue_resource.gd — translation keys
• dialogue_portrait_manager.gd — expression swaps

Alternate engines (load only if decision tree says so)

• dialogue_engine.gd — JSON graphs + BBCode [trigger:] tags
• dialogue_manager.gd — alternate data-driven walker
• dialogue_graph_editor.gd — @tool GraphEdit auditor (editor-only)
• dialogue_lipsync.gd — TTS boundary lipsync helper
• dialogue_stat_logger.gd — choice analytics Logger

Typewriter Contract (skip-safe)

Use typebox_effect.gd: set full text, tween visible_ratio (or RichTextLabel visible_characters) from 0→1. On skip input: kill tween and snap visibility to complete. Do not spawn a Timer per character.

Elite Deltas

• GraphEdit auditor: dialogue_graph_editor.gd (@tool) — export to Resource/JSON for runtime.
• Audio-driven lines: dialogue_lipsync.gd — TTS boundaries; still allow skip.
• Analytics: dialogue_stat_logger.gd — [CHOICE] log prefix; no PII.

MANDATORY for GraphEdit tooling, TTS/lipsync, analytics, and moved inline manager/UI tutorials: elite-dialogue-patterns.md. Do NOT Load for Resource Autoload golden path only.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Resources — Why dialogue graphs belong in Resource / .tres data instead of hardcoded strings in scripts.
• BBCode in RichTextLabel — Native markup for speaker emphasis, custom tags, and effects without rolling your own parser.
• RichTextLabel — visible_characters / image helpers and BBCode APIs the dialogue UI should drive for typewriter and portraits.
• Internationalizing games — tr() / TranslationServer workflow so line text stays key-based across locales.
• Localization using spreadsheets — CSV translation tables that map cleanly onto dialogue text_key fields.
• Importing translations — How Godot imports CSV/PO so localized dialogue resources resolve at runtime.
• Using signals — Emit line/choice/end events upward so UI, quests, and audio never hard-reference the manager internals.
• Singletons (Autoload) — Register a DialogueManager that survives scene changes and owns traversal state.
• Tween — Drive visible_ratio / character reveal timing without blocking the main thread.
• Text-to-speech — DisplayServer TTS callbacks for placeholder VO and lipsync-adjacent timing.
• GraphEdit — Editor surface for authoring branching dialogue graphs when .tres lists become unwieldy.
• JSON — Parse external dialogue graph files when designers prefer JSON over Resources.

Related Skills

Prerequisites

• godot-project-foundations — Autoload registration, input for advance/skip, and project layout dialogue UI scenes plug into.
• godot-gdscript-mastery — Typed Resources, signals, await, and Callables required before branching engines and UI bridges.
• godot-resource-data-patterns — Canonical patterns for DialogueLine / graph Resources, exports, and avoiding duplicated mutable state.
• godot-autoload-architecture — Singleton ownership and boot order for a global DialogueManager that must outlive scene swaps.

Complements

• godot-signal-architecture — Signal-up / call-down contracts for line_displayed, choice selection, and narrative event bridges.
• godot-ui-rich-text — RichTextLabel BBCode, custom effects, and image embedding beyond the basics used in typewriter UIs.
• godot-ui-containers — Layout choice buttons and dialogue panels without fighting Control sizing and focus.
• godot-tweening — Skip-safe Tweens for character reveal, portrait entry, and panel transitions.
• godot-audio-systems — Voice-line players, bus ducking during dialogue, and subtitle sync with spoken audio.
• godot-quest-system — Quest flags and objectives that gate conditional choices and fire from dialogue event bridges.
• godot-save-load-systems — Persist dialogue flags / seen-node state outside UI nodes so progress survives reloads.

Downstream / consumers

• godot-genre-visual-novel — Full VN presentation loops consume this skill’s graph traversal, portraits, and choice UI patterns.
• godot-inventory-system — Dialogue effects often grant/require items; keep grant logic in inventory, not inside line Resources.
• godot-monte-carlo-balancer — Simulate skill-check / branching choice trees when narrative gates or reward paths need balance passes.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns narrative, UI, or quest concerns.