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 nextnodeid 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.delaymsec() — Use visibleratio / visiblecharacters + Tween (see [typeboxeffect.gd](scripts/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 getnode() from NPCs into Dialogue UI — Start via manager signals (startdialogue(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

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)

• [dialogueresource.gd](scripts/dialogueresource.gd) — conversation tree Resource
• [dialoguenodedata.gd](scripts/dialoguenodedata.gd) — single line / speaker / portrait metadata
• [dialogueoptiondata.gd](scripts/dialogueoptiondata.gd) — choice + conditions
• [dialoguemanagersingleton.gd](scripts/dialoguemanagersingleton.gd) — MANDATORY Autoload walker + signals
• [dialogueuicontroller.gd](scripts/dialogueuicontroller.gd) — MANDATORY labels / choice buttons
• [typeboxeffect.gd](scripts/typeboxeffect.gd) — MANDATORY skip-safe Tween visible_ratio reveal

Supporting

• [dialogueeventbridge.gd](scripts/dialogueeventbridge.gd) — fire gameplay events from nodes
• [branchingconditionvalidator.gd](scripts/branchingconditionvalidator.gd) — flag/stat gates
• [localizeddialogueresource.gd](scripts/localizeddialogueresource.gd) — translation keys
• [dialogueportraitmanager.gd](scripts/dialogueportraitmanager.gd) — expression swaps

Alternate engines (load only if decision tree says so)

• [dialogueengine.gd](scripts/dialogueengine.gd) — JSON graphs + BBCode [trigger:] tags
• [dialoguemanager.gd](scripts/dialoguemanager.gd) — alternate data-driven walker
• [dialoguegrapheditor.gd](scripts/dialoguegrapheditor.gd) — @tool GraphEdit auditor (editor-only)
• [dialoguelipsync.gd](scripts/dialoguelipsync.gd) — TTS boundary lipsync helper
• [dialoguestatlogger.gd](scripts/dialoguestatlogger.gd) — choice analytics Logger

Typewriter Contract (skip-safe)

Use [typeboxeffect.gd](scripts/typeboxeffect.gd): set full text, tween visibleratio (or RichTextLabel visiblecharacters) from 0→1. On skip input: kill tween and snap visibility to complete. Do not spawn a Timer per character.

Elite Deltas

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

MANDATORY for GraphEdit tooling, TTS/lipsync, analytics, and moved inline manager/UI tutorials: [elite-dialogue-patterns.md](references/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 — visiblecharacters / 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 visibleratio / 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.