# Dialogue System > >- - **Type:** Skill - **Install:** `agentstack add skill-firzus-agent-skills-dialogue-system` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Firzus](https://agentstack.voostack.com/s/firzus) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Firzus](https://github.com/Firzus) - **Source:** https://github.com/Firzus/agent-skills/tree/main/skills/dialogue-system ## Install ```sh agentstack add skill-firzus-agent-skills-dialogue-system ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](./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](./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](./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](./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](./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](./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](./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 `|plural()`/`|gender()` | | 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](./runtime.md) and [pipeline.md](./pipeline.md). ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Firzus](https://github.com/Firzus) - **Source:** [Firzus/agent-skills](https://github.com/Firzus/agent-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-firzus-agent-skills-dialogue-system - Seller: https://agentstack.voostack.com/s/firzus - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.