Dialog Addon for Godot

A lightweight narrative dialog system for Godot 4 with a custom .dialog scripting format, branching choices, character/background control, audio hooks, and gettext localization support.

This repository includes:

• The addon source in addons/dialog
• A playable demo scene (example_scene.tscn)
• Example dialog scripts (example_dialogs)

Features

• Simple, human-readable dialog scripting language that supports:
  • Text/narration lines
  • Command calls with arguments
  • Labels for flow control
  • Branching choices
  • Variable storage and interpolation
• We made some UI hooks (addons/dialog/nodes) and features for typical visual novel style dialog, but the system is flexible and easily extended to support different presentation styles and game genres.
• Editor integration:
  • .dialog syntax highlighting.
  • Gettext extraction support for localization.

Requirements

• Godot 4.x (project configured for 4.6)

Installation

1. Copy the addons/dialog folder into your project.
2. In Godot, go to Project > Project Settings > Plugins.
3. Enable the Dialog plugin.

When enabled, the plugin:

• Registers an autoload singleton named Dialog
• Registers a .dialog resource loader
• Registers a translation parser for .dialog files
• Registers syntax highlighting for dialog scripts in the script editor

Quick Start

1) Create a dialog script

Create a file like res://dialogs/intro.dialog:

label start

set hero "Alex"

speaker _
    Welcome to the game.
    I'm the narrator.

speaker hero
    Hi! I'm {hero}.
    And I'm the hero of this story.

choose
    Continue -> continue_label
    Quit -> end_label

label continue_label
    Great, let's continue.
jump end_label

label end_label
hide_dialog

2) Start the dialog from code

Dialog.start("intro")

intro is the filename without extension (intro.dialog). Notice that dialog files (*.dialog) are automatically loaded as resources on startup, so you can reference them by ID (filename) without manual loading.

3) Connect your UI/game to Dialog signals

At minimum, connect:

• Dialog.say(text) to your dialog text UI
• Dialog.choose(options, labels) to your choice UI
• Dialog.update_speaker(speaker, speaker_id) to your speaker UI

And call:

• Dialog.step() when the player advances dialog
• Dialog.jump(label) when the player selects a choice

Use the demo scene as a full wiring reference.

You can make custom UI and connect to any of the Dialog signals to implement your own presentation style. The system is designed to be flexible and extensible. Or you can use any of the included UI nodes under addons/dialog/nodes as a starting point.

• background.tscn: background image controller
• characters.tscn: characters sprites controller
• choose_box.tscn: choice UI
• dialog_box.tscn: dialog text box with typewriter effect
• dialog_music_player.tscn: music player with fade transitions
• dialog_sound_player.tscn: sound effect player

Dialog Script Language

Line Types

• Narration/Text: indented lines
• Command calls: identifier arg1 arg2 ...
• Labels: label my_label
• Choices:

speaker _
    What do you want to do?
choose
    Option text -> target_label
    Another option -> other_label

Variables

Set variables:

set player "Mary"

Interpolate in text:

speaker player
    Hello {player}!

Comments

Use # for comments:

# This is a comment

Built-in Runtime Commands

The Dialog singleton handles these command identifiers:

• wait <seconds>
• background <image_or_var> [transition]
• speaker <speaker_id_or_name>
• show <character_id> [variation] [position] [transition]
• hide <character_id> [transition]
• update <character_id> [variation] [transition]
• move <character_id> [position] [transition]
• jump <label>
• dialog <dialog_id> [label]
• return
• play_sound <sound_or_var>
• play_music <music_or_var> [transition]
• stop_music [transition]
• set <name> <value>
• hide_dialog

Unknown commands emit Dialog.unhandled_command(identifier, args) so you can implement custom behavior externally.

Runtime Signals

Core signals exposed by the Dialog singleton:

• started(dialog_id)
• ended(dialog_id)
• say(text)
• choose(options, labels)
• update_background(background, transition)
• update_speaker(speaker, speaker_id)
• show_character(character_id, variation, position, transition)
• hide_character(character_id, transition)
• update_character(character_id, variation, transition)
• move_character(character_id, position, transition)
• play_sound(sound)
• play_music(music, transition)
• stop_music(transition)
• hide_dialog_box
• unhandled_command(identifier, args)

Important: After receiving the following signals, you must call Dialog.step() to advance the dialog execution:

• say
• choose
• update_background
• show_character
• hide_character
• update_character
• move_character
• hide_dialog

This allows you to control the pacing and ensure commands are fully processed before moving on.

Localization (Gettext)

The addon includes a translation parser plugin that scans .dialog files and extracts:

• Spoken lines (say)
• Choice option texts

Speaker context is included for spoken lines when available.

Typical workflow:

1. Ensure .dialog files are included in your POT extraction settings.
2. Generate/update POT/PO files in Godot.
3. Add translations in Project Settings and switch locale at runtime.

The included examples (example_localizations) demonstrate this flow.

Included Demo Content

• example_scene.tscn: playable demo UI with dialog controls and language switch
• example_dialog.dialog: core features (speaker, variables, choices, characters, audio)
• example_dialog_2.dialog and example_dialog_3.dialog: cross-dialog flow (dialog/return)
• Reusable UI nodes under addons/dialog/nodes:
  • Background controller
  • Character controller
  • Dialog box with typewriter effect
  • Choice box
  • Sound player
  • Music player

Architecture Overview

• Tokenizer (dialog_tokenizer.gd): turns raw script into tokens
• Parser (dialog_parser.gd): compiles tokens into opcode-based ParsedDialog
• VM (dialog_vm.gd): executes opcodes and emits semantic events
• Runtime Singleton (dialog_singleton.gd): command handling, state, variables, and Godot-facing signals
• Resource Loader (resource_loader.gd): loads .dialog as DialogResource
• Gettext Parser (dialog_gettext_parser.gd): extracts translatable strings from dialog scripts

Notes

• Dialog IDs are derived from .dialog filenames (basename).
• The singleton recursively loads .dialog files from res:// on startup.
• Use variable keys for assets (images/audio) to keep scripts readable and configurable.

License

See the repository LICENSE file.