Skip to main content
This guide helps you migrate your project between different versions of Dialogue Manager for Godot.

​
Current Version Requirements

Dialogue Manager v4 requires Godot 4.4 or above. Make sure your project is using a compatible Godot version before upgrading.

​
Migrating from v2 to v3

The upgrade from v2 to v3 should be mostly seamless, but there are several important breaking changes to be aware of.

​
Breaking Changes

What changed: The “include failed responses” setting has been removed and is now the default behavior.Impact: Responses that fail their condition check will be included in the responses list. It’s now up to the balloon to filter them out.Migration steps:The provided DialogueResponsesMenu node has an option to hide failed responses if you want to maintain the old behavior.
# In your balloon script
$DialogueResponsesMenu.hide_failed_responses = true
Alternatively, filter responses manually:
func _on_responses_received(responses: Array):
    var available_responses = responses.filter(func(r): return r.is_allowed)
    # Display only available responses
What changed: The “create lines for responses with characters” setting has been removed.Impact: You’ll need to manually handle displaying character names with response text.Migration steps:
# Old behavior was automatic
# New approach - handle manually in your balloon
func display_response(response: DialogueResponse):
    if response.character:
        label.text = "%s: %s" % [response.character, response.text]
    else:
        label.text = response.text
What changed: The built-in emit mutation has been removed in favor of standard GDScript signal syntax.Impact: Old emit statements will no longer work.Migration steps:
# Old v2 syntax
emit some_signal
emit some_signal(arg1, arg2)

# New v3 syntax (GDScript standard)
some_signal.emit()
some_signal.emit(arg1, arg2)
Update all your dialogue files to use the new .emit() syntax.

​
Upgrade Process

1

Backup Your Project

Create a complete backup of your project before upgrading. Consider using version control (git) for easy rollback.
2

Remove Old Version

Delete the addons/dialogue_manager directory from your project.
rm -rf addons/dialogue_manager
3

Install v3

Download Dialogue Manager v3 from either:Extract it to your addons/ directory.
4

Update Dialogue Files

Search for and update emit statements in all .dialogue files:
  • Find: emit signal_name
  • Replace: signal_name.emit()
5

Update Response Handling

If you were relying on automatic character name display in responses, update your balloon scripts to handle this manually.
6

Test Thoroughly

Test all dialogue interactions, responses, and signals to ensure everything works as expected.
After upgrading, Godot may need to reimport resources. Allow the import process to complete before testing your dialogue.

​
Migrating from v1 to Latest

Dialogue Manager v1 was designed for Godot 3. Migrating to the latest version involves more significant changes.

​
Major Differences

  • Engine Version: v1 was for Godot 3, latest versions require Godot 4.4+
  • GDScript 2.0: Syntax changes in GDScript itself
  • Type System: Stricter typing in Godot 4
  • Signal Syntax: Connect syntax has changed
1

Upgrade Godot First

Upgrade your project to Godot 4.4+ using Godot’s official migration tools and documentation.
2

Fresh Install

Install the latest version of Dialogue Manager from scratch rather than attempting a direct upgrade.
3

Recreate Dialogue

Review and test your dialogue files. Most dialogue syntax should work, but check for:
  • Variable references
  • Function calls
  • Signal emissions
4

Update Integration Code

Rewrite your dialogue integration code using current Godot 4 and Dialogue Manager APIs.
# Godot 3 / v1 style
DialogueManager.connect("dialogue_ended", self, "_on_dialogue_ended")

# Godot 4 / v4 style
DialogueManager.dialogue_ended.connect(_on_dialogue_ended)
For Godot 3 projects, you can still use Dialogue Manager v1.x. However, new features and fixes are only added to v4.

​
Version Compatibility Matrix

Dialogue Manager VersionGodot VersionStatus
v4.x (current)4.4+Active development
v3.34.3Maintenance only
v2.x≤4.3Legacy
v1.x3.xLegacy

​
Getting Help

If you encounter issues during migration:

​
Older Versions

If you need to stay on an older version of Godot:

Build docs developers (and LLMs) love

Get started for freeTalk to us