Dialogue system

Dialogue System

Build the dialogue layer of a game — graph, runtime, narrative-design mechanics, presentation, and the authoring/VO pipeline. In-world dialogue focus: cutscenes are out of scope (cinematic-system); procedural dialogue cameras live in camera-system. References: BotW/TotK + Genshin (datamined graph/text/conditions), Valve GDC 2012 (barks), and the Western-RPG canon (Disco Elysium, Baldur's Gate 3, Mass Effect, Witcher 3, Oxenfree) for narrative mechanics.

The architecture rule

Flow, text, and conditions are three separate stores — the graph never contains text, only references. Both reference games ship this separation, and it is the foundation of localization, VO, and versioning.

GRAPH       flow only — line nodes + nextDialogs edges; a choice is fan-out;
            BotW: 5 event types (Action/Switch/Fork/Join/Sub-flow) suffice
TEXT        per-language tables addressed by stable key; rich-text control tags
            (color, pauses, ruby, gender variants) live IN the text
CONDITIONS  queries on world state (quest/flags/time/weather/player state)
EVENTS OUT  dialogue notifies; consumers decide (end-of-talk = a quest event)

Reference map

File	Covers
graph.md	The two datamined shapes (Genshin flat nodes, BotW 5 events), conditions, the text format, AND branching-structure patterns (Ashwell's taxonomy: time cave / gauntlet / branch-and-bottleneck / hub-and-spoke), storylet/quality-based and salience-based narrative for combinatorial control
runtime.md	The session scope (capture + finally-restore), staging as data (the BotW AISchedule gold mine), look-at, voice strategy, the bark arbiter and the Valve fact-matching model
narrative-design.md	Skill-check / dice-roll dialogue (Disco Elysium white/red checks, BG3 visible DCs), dialogue wheels vs full-text (the Mass Effect/Fallout 4 paraphrase backlash), the reactivity budget, delayed consequence (Witcher 3), timed/real-time conversation (Oxenfree), internal-voice systems
presentation.md	Typewriter reveal, auto/skip modes (the Genshin skip cautionary tale), backlog, and deep subtitle accessibility (size, speaker ID, reading speed, dyslexia, screen-reader, the cert-tag standards)
pipeline.md	Writer tools compared (Ink/Yarn/articy/Twine/in-engine), line-ID and lock-then-record VO workflow, localization depth (RTL/CJK, ICU plural/gender, expansion budgets), lip-sync tiers, AND AI/LLM-driven NPCs (the architecture, the hard problems, the SAG-AFTRA 2025 terms)
pitfalls.md	16 failure modes (symptom → cause → prevention) with real incidents, debugging order, ship checklist

The session and the barks (summary)

• A dialogue session is a scope: capture input/camera/HUD/NPC-AI on entry, restore in a finally on EVERY exit path (normal, death, teleport, load). The stuck-in-dialogue bug class is a missing finally.
• Staging is actor data, not code (the BotW lesson): turn-to-face, approach reactions, rain variants, routine resumption all live in AISchedule.
• Barks are a separate system: gameplay requests, a central arbiter decides (priority, cooldowns, history, muted during sessions). The reference is Valve's GDC 2012 fact-matching model.
• The VO strategy is a cost decision made early: partial VO (Genshin voices story quests only; BotW voices cutscenes only) with per-line soundId keys.

Full detail in runtime.md.

Build order (4 shippable tiers)

Tier 1 — Graph and session
- [ ] Line nodes + edges + choice fan-out; text as keys from day one
- [ ] The session scope (capture + finally restore); Started/LineChanged/Ended
- [ ] Typewriter reveal + advance; line-by-line skip
- [ ] Graph validation at import (every node reaches a terminal)
Tier 2 — Conditions, staging, voice
- [ ] Condition gates via the world-state store
- [ ] Staging data: turn-to-face, look-at ramp, approach reactions
- [ ] VO by line ID; voice-end advance as OPT-IN; partial-VO first-class
- [ ] Events out: end-of-talk → quest-system; mid-line actions
Tier 3 — Mechanics and presentation
- [ ] Choice UI: dead-window, separate advance/select, consequential confirm
- [ ] Narrative mechanics chosen (skill-check / wheel / reactivity model)
- [ ] Auto mode (text-aware delay), skip-with-summary, backlog
- [ ] Subtitle accessibility: ≥32px scalable to 46, speaker ID, 2×40
Tier 4 — Pipeline and scale
- [ ] Writer tool → runtime import automated, validated on every sync
- [ ] VO pipeline: text-lock before recording, files by line ID, pickup tracking
- [ ] Localization: pseudo-loc, +30–40% budgets, ICU plural/gender, RTL/CJK
- [ ] Lip-sync tier decision; (if used) generative-NPC tiering + guardrails

Key numbers (starting points — sourced anchors)

Parameter	Value	Anchor
Corpus scale	Genshin v4.5: 170,202 lines, 2,422 speakers; 424,011 VO files	datamine
Reading rates	adult silent ~238 wpm; subtitles 160–180 wpm; Netflix 20 cps	academic/official
Subtitle size	default ≥32px @1080p, scalable to 46px (≥200%); cert tags	Xbox/AGI
Disco Elysium check	active 2d6 + skill ≥ DC (double 1 fail / double 6 success); % shown	wiki
BG3 check	d20 + ability + proficiency ≥ DC; Inspiration reroll (cap 4)	bg3.wiki
Skip reality	Genshin still has NO general skip; HSR 3.4 skip-with-summary is the model	chronology
VO costs	SAG-AFTRA $551/h (1 voice); AI Real-Time Generation = 7.5× scale min	official
Localization	DE +10–35%, Arabic ~+30%, short strings +100–200%; ICU plural forms	industry
Generative latency	conversational gap ~200ms; >1s noticeable, ~3s collapses presence	research

Full sourced tables (with flagged "do-not-invent" gaps) in each reference file.

Engine mapping (summary)

Generic block	Unity 6	UE5 (5.4+)
Middleware	Yarn Spinner 3.x · Ink · Dialogue System for Unity	Narrative Pro · Mountea · custom DataAsset graphs (Dialogue Voice/Wave semi-abandoned)
Typewriter	TMP maxVisibleCharacters (rich-text safe)	UMG rich text + custom reveal
Text/loc	Localization package (line ID → String + Asset tables)	FText + String Tables; native `
VO audio	Vorbis + Streaming; Addressables per language	Sound Waves + Concurrency; Submix ducking
Lip-sync	uLipSync · SALSA · OVRLipSync (legacy)	MetaHuman Animator (offline/editor, no runtime)

Full detail in runtime.md and pipeline.md.