Dialogue Manager
Related skills: dialogue-system for hand-rolled dialogue data structures, localization for translating lines, popochiu for full adventure-game workflows.
Addon: Dialogue Manager · version
v4.2.0· Godot 4.6+ (built for 4.7; Godot 4.4–4.5 → v3.10, 4.3 → v3.3, see §7) · MIT · source: https://github.com/nathanhoad/godot_dialogue_manager · GDScript with official C# support.
Godot 4.8: not yet confirmed by the addon. v4.2.0 is released "for Godot 4.7", and no open issue mentions 4.8 (checked 2026-11-12).
1. When to use Dialogue Manager
| Approach | Best for |
|---|---|
dialogue-system skill (hand-rolled Resource data) |
Full control over data shape, no addon dependency, small dialogue trees |
| Dialogue Manager | Script-like .dialogue text format, branching responses, conditions/mutations, translation pipeline, visual editor tab, official C# wrapper |
| Full adventure-game framework | Point-and-click games needing rooms/inventory/actors bundled with dialogue — Dialogue Manager only owns the dialogue layer |
Choose Dialogue Manager when writers want to author branching dialogue as readable script text (not
Inspector-edited Resources) and you want built-in conditions, mutations, random lines, and translation
templates for free. If you need dialogue as strongly-typed Resources you fully own, use
dialogue-system instead. It is not a quest or adventure framework.
2. Install & setup
- Godot AssetLib → search "Dialogue Manager" → Download. Or copy
addons/dialogue_manager/from the GitHub repo intores://addons/dialogue_manager/. - Project → Project Settings → Plugins (Project Settings → Addons → Plugins on 4.8) → enable "Dialogue Manager". This adds a Dialogue main-screen
tab and registers the
DialogueManagerautoload automatically — no manual autoload step. addons/dialogue_manager/plugin.cfg:
[plugin]
name="Dialogue Manager"
description="A powerful branching dialogue system"
author="Nathan Hoad"
version="4.2.0"
script="plugin.gd"- C# projects need no NuGet package —
using DialogueManagerRuntime;is enough (§4). - Settings live at Project Settings → General → Dialogue Manager: notably State Autoload
Shortcuts (autoload names usable without a prefix) and Balloon Path (the scene
show_dialogue_balloon()opens — empty uses the built-in example balloon).
3. .dialogue syntax
Lines are Character: text or bare text (narrator). Godot's RichTextLabel BBCode works, plus
[[A|B|C]] (random inline pick), [wait=N] / [wait="ui_accept"], [speed=N], [next=auto].
Cues and jumps — ~ name marks a cue (3.x called it a "title"); => name jumps to it;
=> END ends the flow; => END! force-ends past pending jump-and-returns; =>< name jumps and returns
here once that branch hits END. import "res://other.dialogue" as other then =>< other/cue.
Do not indent the line directly after a cue.
~ start
Nathan: Well?
- First one
- Another one => another_cue
- Start again => start
=> END
~ another_cue
Nathan: Another one?
=> ENDResponses (- ) nest by indentation. A response condition is self-closing — [if cond /] —
and any jump goes last:
Nathan: How many projects have you started and not finished?
- Just a couple
Nathan: That's not so bad.
- A lot [if SomeGlobal.some_property == true /]
Nathan: Maybe you should finish one before another.
- Another one [if SomeGlobal.some_method() /] => another_cueA response whose condition fails is still returned, with is_allowed == false — your UI filters it.
Conditions — if / elif / else, and/or/() (short-circuiting), and match/when/while:
if SomeGlobal.some_property >= 10
Nathan: That property is >= 10.
elif SomeGlobal.some_other_property == "some value"
Nathan: Or we might be in here.
else
Nathan: If neither are true, I'll say this.Inline conditions inside a line are not self-closing: Nathan: I have done this [if already_done]once again[/if],
with an optional [else]. Null-safe member access uses ?..
Mutations — $> assigns state or calls a method/emits a signal; inline [$> wave()] awaits,
[$>> wave()] does not. set / do / [do!] still parse but are deprecated:
if SomeGlobal.has_met_nathan == false
$> SomeGlobal.animate("Nathan", "Wave")
Nathan: Hi, I'm Nathan.
$> SomeGlobal.has_met_nathan = trueBuilt-ins: $> wait(1.0), $> debug(...). Signals: $> SomeGlobal.some_signal.emit("arg").
State — autoloads first; a DialogueStateContext node (alias + target) exposes a scene node while it
is in the tree; extra_game_states (pass instances, never bare classes) is the last resort.
$> locals.asked = true is a per-conversation variable implemented by the example balloon, not core.
Randomised lines — % (equal weight) or %N (relative weight); a blank line separates groups. A
condition on a random line is self-closing too: % [if cond /] Nathan: Only sometimes.
%3 Nathan: This line has a 60% chance of being picked
%2 Nathan: This line has a 40% chance of being pickedVariables and tags — {{SomeGlobal.some_property}} interpolates state. [#happy, #mood=calm]
attaches tags, read with line.has_tag("happy") / line.get_tag_value("mood").
4. Runtime API — balloons and manual traversal
Either let DialogueManager open a balloon, or pull lines with
await DialogueManager.get_next_dialogue_line(resource, cue_or_id). At the end it returns null (and
emits dialogue_ended) — test while line: / if not line: in GDScript, line != null in C#.
GDScript
# npc.gd
extends Node2D
@export var dialogue_resource: DialogueResource
func _on_interact() -> void:
# Opens Settings → Balloon Path, or the built-in example balloon.
DialogueManager.show_dialogue_balloon(dialogue_resource, "start")
func _manual_walk() -> void:
# Manual traversal for a fully custom UI.
var line: DialogueLine = await DialogueManager.get_next_dialogue_line(dialogue_resource, "start")
while line:
print("%s: %s" % [line.character, line.text])
if line.responses.is_empty():
line = await DialogueManager.get_next_dialogue_line(dialogue_resource, line.next_id)
else:
var allowed: Array = line.responses.filter(func(r: DialogueResponse) -> bool: return r.is_allowed)
if allowed.is_empty():
break # nothing selectable; end the walk
var chosen: DialogueResponse = allowed[0] # replace with real UI selection
line = await DialogueManager.get_next_dialogue_line(dialogue_resource, chosen.next_id)C#
// Npc.cs
using System.Linq;
using Godot;
using DialogueManagerRuntime;
public partial class Npc : Node2D
{
[Export] public Resource DialogueResource;
private void OnInteract()
{
DialogueManager.ShowDialogueBalloon(DialogueResource, "start");
}
private async void ManualWalk()
{
var line = await DialogueManager.GetNextDialogueLine(DialogueResource, "start");
while (line != null)
{
GD.Print($"{line.Character}: {line.Text}");
if (line.Responses.Count == 0)
{
line = await DialogueManager.GetNextDialogueLine(DialogueResource, line.NextId);
}
else
{
var chosen = line.Responses.FirstOrDefault(r => r.IsAllowed); // replace with real UI selection
if (chosen == null) break; // nothing selectable; end the walk
line = await DialogueManager.GetNextDialogueLine(DialogueResource, chosen.NextId);
}
}
}
}Other methods (the cue parameter; C# names it key): show_dialogue_balloon_scene(balloon_scene, resource, cue),
show_example_dialogue_balloon(resource, cue), set_default_balloon(scene) (runtime override of Balloon
Path), create_resource_from_text(text). C#: ShowDialogueBalloonScene, ShowExampleDialogueBalloon,
SetDefaultBalloon, CreateResourceFromText. get_next_dialogue_line's mutation_behaviour is
DMConstants.MutationBehaviour (C# MutationBehaviour): Wait (default), DoNotWait, Skip. Leave it
Wait — the example balloon only supports Wait.
5. Actionable nodes ("press to talk")
DialogueActionable2D / DialogueActionable3D (an Area2D / Area3D; the upstream docs shorten them to
Actionable2D) hold dialogue_resource + dialogue_cue. action() opens the balloon, passing
{actionable = self} and the node's owner as extra game states; dialogue_ended fires when that resource
ends. The picker adds the GDScript nodes — attach the C# scripts by hand to get the C# classes.
GDScript
# player.gd
extends CharacterBody2D
func _unhandled_input(event: InputEvent) -> void:
if event.is_action_pressed("ui_accept"):
var nearest: DialogueActionable2D = DialogueActionable2D.get_nearest_actionable_to(global_position)
if nearest:
nearest.action()C#
public override void _UnhandledInput(InputEvent @event)
{
if (@event.IsActionPressed("ui_accept"))
{
// Finds only nodes running the C# DialogueActionable2D script.
DialogueActionable2D.GetNearestActionableTo(GlobalPosition)?.Action();
}
}Both languages scan the shared dialogue_actionables group; the GDScript get_nearest_actionable_to() uses a
typed loop, so it errors in a mixed project where C# actionables are in that group too.
6. Signals, typed access, saving
DialogueLine: id, next_id, character, text, tags, static_id, responses (untyped Array of
DialogueResponse), concurrent_lines. DialogueResponse adds is_allowed and condition_as_text.
Treat id/next_id as opaque strings (they can be <uid>@<id>).
GDScript
func _ready() -> void:
DialogueManager.dialogue_started.connect(_on_dialogue_started)
DialogueManager.dialogue_ended.connect(_on_dialogue_ended)
DialogueManager.got_dialogue.connect(_on_got_dialogue)
DialogueManager.passed_cue.connect(func(cue: String) -> void: print("cue ", cue))
func _on_dialogue_started(resource: DialogueResource) -> void:
pass
func _on_dialogue_ended(resource: DialogueResource) -> void:
pass # tell the HUD the conversation is over
func _on_got_dialogue(line: DialogueLine) -> void:
print(line.character, ": ", line.text, " id=", line.static_id)
# Save/restore the current line (persisted .dialogue files only).
func save_line(line: DialogueLine) -> String:
return line.to_serialized()
func load_line(data: String) -> DialogueLine:
return await DialogueLine.new_from_serialized(data)C#
using System.Threading.Tasks;
using Godot;
using DialogueManagerRuntime;
public override void _Ready()
{
DialogueManager.DialogueStarted += (Resource resource) => { };
DialogueManager.DialogueEnded += (Resource resource) => { /* tell the HUD */ };
DialogueManager.GotDialogue += (DialogueLine line) => GD.Print($"{line.Character}: {line.Text} id={line.StaticId}");
DialogueManager.PassedCue += (string cue) => GD.Print($"cue {cue}");
}
// No C# serializer: store Id and NextId, then re-fetch the line by Id.
public async Task<DialogueLine> LoadLine(Resource resource, string id, string nextId)
{
var line = await DialogueManager.GetNextDialogueLine(resource, id);
if (line != null) line.NextId = nextId;
return line;
}mutated(mutation) / Mutated fires before a non-assignment mutation runs (calls, emits, wait) — not
assignments. Also new: waiting_for_input / waited_for_input.
⚠️ The C# events are bridged to the Godot signals lazily, on the first access to
DialogueManager.Instance. A project that subscribes from C# but drives dialogue from GDScript never touchesInstance, so the handlers never fire — add_ = DialogueManager.Instance;first.
The C# DialogueResponsesMenu script exposes ResponseSelected as a C# event. The GDScript node from
the picker does not, and its argument is the GDScript RefCounted, not the C# wrapper — connect with
Connect("response_selected", Callable.From((RefCounted r) => { var response = new DialogueResponse(r); })).
Translations. Text goes through tr(). With Use Static IDs as Translation Keys (default on), a
line's static ID (Nathan: Hi! [ID:HI_IM_NATHAN]) is the key and "dialogue" the context; ## comments
become translator notes. Export templates (PO or CSV) via Project Settings → Localization → Template
Generation, or Project → Tools → Dialogue → Simple CSV export…. Locale switching and RTL: localization.
7. Migrating from 3.x
| 3.x | 4.x |
|---|---|
"title", passed_title, titles/get_titles(), C# PassedTitle |
"cue", passed_cue, cues/get_cues(), C# PassedCue (~ name unchanged) |
- Text [if cond], % [if cond] Line |
- Text [if cond /], % [if cond /] Line |
set x = 1, do f(), [do f()], [do! f()] |
$> x = 1, $> f(), [$> f()], [$>> f()] |
translation_key / C# TranslationKey |
static_id / C# StaticId |
DialogueManager.translation_source, Dialogue-tab CSV import/export |
removed — Template Generation / Simple CSV export |
| Godot 4.3+ | Godot 4.6+ |
A 3.x response condition [if cond] still compiles in 4.x with no error: the response is always
allowed and [if cond] shows up in its text. Upgrade checklist and the full rename list:
references/migrating-from-3.md.
Implementation checklist
- Dialogue Manager plugin enabled (registers the
DialogueManagerautoload); Godot 4.6+ for v4 -
.dialogueresources loaded viaload()/preload(), not parsed by hand - Every
get_next_dialogue_line/GetNextDialogueLinecall isawaited - Manual loops detect the end via the
nullreturn (while line:/line != null), never{} - Response conditions are self-closing
[if condition /], placed before any=> cuejump - Custom UIs skip responses whose
is_allowedisfalse - Mutations use
$>/[$> …];[$>> …]when the caller shouldn't block - Scene state exposed with
DialogueStateContext;extra_game_statesentries are instances - C# state properties that dialogue reads/writes carry
[Export] - C# uses
using DialogueManagerRuntime;and PascalCase (GetNextDialogueLine,DialogueEnded,PassedCue,StaticId) - Custom balloons set Balloon Path (or
set_default_balloon) rather than forking call sites - Static line IDs (
[ID:KEY]) on any line needing voice-over or stable translation keys