The simplest way to show dialogue in your game is to call DialogueManager.show_dialogue_balloon(resource, title) with a dialogue resource and a title to start from. This will show the example balloon by default but you can configure it in Settings to show your custom balloon.
It's up to you to implement/customise any dialogue rendering and input control to match your game but there are a few example balloons included to get you started with some of the more common things.
Once you get to the stage of building your own balloon you'll need to know how to get a line of dialogue and how to use the dialogue label node.
A global called DialogueManager is available to provide lines of dialogue.
To request a line, call await DialogueManager.get_next_dialogue_line(resource, title) with a dialogue resource (*.dialogue file) and a starting title (you can also call get_next_dialogue_line on the resource directly, see below). This will traverse each line (running mutations along the way) and returning the first printable line of dialogue.
For example, if you have some dialogue like:
~ start
Nathan: Hi! I'm Nathan.
Nathan: Here are some options.
- First one
Nathan: You picked the first one.
- Second one
Nathan: You picked the second one.
And then in your game:
var resource = load("res://some_dialogue.dialogue")
# then
var dialogue_line = await DialogueManager.get_next_dialogue_line(resource, "start")
# or
var dialogue_line = await resource.get_next_dialogue_line("start")Then dialogue_line would now hold a DialogueLine containing information for the line Nathan: Hi! I'm Nathan.
To get the next line of dialogue you can call get_next_dialogue_line again with dialogue_line.next_id as the title:
dialogue_line = await DialogueManager.get_next_dialogue_line(resource, dialogue_line.next_id)
# or
dialogue_line = await resource.get_next_dialogue_line(dialogue_line.next_id)
Now dialogue_line holds a DialogueLine containing the information for the line Nathan: Here are some options.. This object also contains the list of response options.
Each option also contains a next_id property that can be used to continue along that branch.
For more information about DialogueLines see the API documentation.
The addon provides a DialogueLabel node (an extension of the RichTextLabel node) which helps with rendering a line of dialogue text.
This node is given a dialogue_line (mentioned above) and uses its properties to work out how to handling typing out the dialogue. It will automatically handle any bb_code, wait, speed, and inline_mutation references.
Use type_out() to start typing out the text. The label will emit a finished_typing signal when it has finished typing.
The label will emit a paused_typing signal (along with the duration of the pause) when there is a pause in the typing and a spoke signal (along with the letter typed and the current speed) when a letter was just typed.
The DialogueLabel typing speed can be configured in your balloon by changing the seconds_per_step property. It will also automatically wait for a brief time when it encounters characters specified in the pause_at_characters property (by default, just ".").
If your game has its own method of managing what the "current scene" is then you might want to pass an overridden Callable to DialogueManager.get_current_scene. The built-in implementation looks at get_tree().current_scene before assuming the last child of get_tree().root is the current scene. If that doesn't work for you game then you can pass in a Callable that returns a Node that represents what the current scene is.
If you need to construct a dialogue resource at runtime you can use create_resource_from_text(string):
var resource = DialogueManager.create_resource_from_text("~ title\nCharacter: Hello!")This will run the given text through the parser.
If there were syntax errors the method will fail.
If there were no errors then you can use this ephemeral resource like normal:
var dialogue_line = await DialogueManager.get_next_dialogue_line(resource, "title")