Index of every page on this site: llms.txt
All skills
jame581 avatar

/dialogue-manager

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

Use when using the Dialogue Manager addon — .dialogue files with cues, responses, conditions and mutations, runtime balloons, actionable nodes, and C# support

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/dialogue-manager

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈45 tokens for metadata: the name and description. ≈3.7k when used: this file. ≈1.6k more on demand in 1 file.

Description uses 2.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈177 characters, or 2.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. Godot AssetLib → search "Dialogue Manager" → Download. Or copy addons/dialogue_manager/ from the GitHub repo into res://addons/dialogue_manager/.
  2. Project → Project Settings → Plugins (Project Settings → Addons → Plugins on 4.8) → enable "Dialogue Manager". This adds a Dialogue main-screen tab and registers the DialogueManager autoload automatically — no manual autoload step.
  3. 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"
  1. C# projects need no NuGet package — using DialogueManagerRuntime; is enough (§4).
  2. 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?
=> END

Responses (- ) 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_cue

A 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 = true

Built-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 picked

Variables 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 touches Instance, 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 DialogueManager autoload); Godot 4.6+ for v4
  • .dialogue resources loaded via load()/preload(), not parsed by hand
  • Every get_next_dialogue_line / GetNextDialogueLine call is awaited
  • Manual loops detect the end via the null return (while line: / line != null), never {}
  • Response conditions are self-closing [if condition /], placed before any => cue jump
  • Custom UIs skip responses whose is_allowed is false
  • Mutations use $> / [$> …]; [$>> …] when the caller shouldn't block
  • Scene state exposed with DialogueStateContext; extra_game_states entries 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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts7d3 checks · Risk SAFE
  • Gen Agent Trust Hub7d

    This skill provides a comprehensive guide for using the Dialogue Manager addon for the Godot game engine. It contains GDScript and C# code snippets for managing branching dialogue. No malicious patterns such as credential theft or obfuscation were found. The skill describes a data-driven system that processes external files containing logic and method calls (mutations), which represents a potential indirect prompt injection surface if the dialogue files are provided by an untrusted source.

  • Socket7d

    No alerts

  • Snyk7d

    Risk: LOW · No issues

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last week

README badge

README badge for jame581/godotprompter/dialogue-manager