Table of Contents

DialogueDown overview

DialogueDown is an engine-agnostic C# library that compiles branching game dialogue written in Markdown. You author a script in a Markdown-inspired syntax; DialogueDown lowers it through a pipeline of compiler stages into a validated model, reporting precise diagnostics as it goes — with no dependency on any game engine.

Note

DialogueDown is in early development. The compiler pipeline is implemented, and it emits a portable playbook; the first passes of the runtime that plays one — stepping through it and waiting on the host — ship too. Conditions, world reads, saves, and engine adapters are still in progress.

Table of contents

The compiler pipeline

DialogueDown lowers a script through distinct, independently testable stages, behind one IScriptCompiler facade:

flowchart LR
    Src["Markdown<br/>script"] --> MD["Markdown<br/>AST"] --> DA["Dialogue<br/>AST"]
    DA --> DS["Desugared<br/>AST"] --> SM["Semantic<br/>model"]
    SM --> GR["Dialogue<br/>graph"] --> PB["Playbook"] --> RT["Runtime<br/>runner"]
  • Markdown front-end parses the source into a Markdown AST.
  • Transpiler turns that into a Dialogue AST — speakers, speech, choices, jumps, tags, and game calls.
  • Desugar normalizes the Dialogue AST, assembling jumps and filling the default speaker.
  • Semantic analysis resolves speakers, scenes, and jumps into a validated semantic model and reports invalid references.

Each stage has a design note; read them in pipeline order in the design notes.

Script representations

Dialogue content moves through three representations:

  1. Source — a Markdown-inspired script an author writes in a text file. See the script language specification.
  2. Compiled model — the ASTs, the validated semantic model, and the dialogue graph the compiler builds along the pipeline above.
  3. Playbook — the portable JSON artifact one compile emits, which a runtime loads and plays. See the playbook format.

The words for the playing side: the runtime loads a playbook and plays it, the runner is the part that steps through it, and the host is the game that answers its queries and performs its effects.

What is implemented

  • Compiler pipeline: parse → transpile → desugar → analyze, behind IScriptCompiler (wire it up with AddDialogueDown() for DI, or ScriptCompilerFactory.CreateDefault()).
  • Diagnostics: every problem is a located diagnostic with a stable DLG#### code; the compiler collects them and continues where it safely can. See the error codes.
  • Configuration: a project's dialogue.toml declares its speakers and the compilation mode. See project configuration.
  • CLI and visualization: the ddown CLI compiles a script and renders every compiler stage as an interactive report.
  • Runtime: a compile emits a playbook, and the C# runner loads one, steps through it, and waits on its host for effects. A language-neutral conformance corpus pins the sessions a runtime must reproduce.
  • In progress: conditions, effects and world reads, saves, and thin engine presentation adapters.
Edit this page