Godot Open Dialogue

About

The project

The Godot Open Dialogue is a non-linear conversation system created by J. Sena and released as CC-BY. The current version of the system requires the 3.1 (or newer) version of the Godot Engine. You can change the code to make it work on previous versions but things may not work as they should.

The license

I put a lot of time and effort on this project to make sure it is bug free (as much as possible), easy to use and fits the needs of most projects. By releasing it under the CC-BY license I don't intend to have my name included in the credits of your game (it would be awesome if you do but you don't have to). Just make sure to credit me if you share the code of your project (i.e. game jam projects). Feel free to get in touch to tell me you're using my script on a project. It will greatly help me to keep myself motivated and release new versions.

The block types

In order to define the various possible behaviors during a conversation the system has a few sets of parameters called blocks. Each block has its own ways to be customized and connected to other blocks in order to create a rich dialogue experience. You can see below the block types and the way they can be used.

1. text updated

The most common type of dialogue block probably will be the text one. This is the simplest way to print a string in the players screen.

The parameters

type	Must be set to "text".
content	Here goes the string to be parsed and printed.
avatar	Must be a string with the avatar's relative path to the "/img/characters/" folder.
name	Must be a string with the characters name.
position	Must be set to "left" or "right" to indicate where the player's avatar and name will appear.
animation_in	Must be a string with the animation to be played at the beginning of the block's execution. Current available animations are "shake_weak_short", "shake_weak_medium", "shake_weak_long", "shake_regular_short", "shake_regular_medium", "shake_regular_long", "shake_strong_short", "shake_strong_medium", "shake_strong_long", "fade_in", "fade_out" (doesn't make any sense in this case but can be used), "move_in", "move_out" (again, can be used regardless of making any sense), "on", "off" (you know...).
animation_out	Must be a string with the animation to be played at the end of the block's execution. Current available animations are "shake_weak_short", "shake_weak_medium", "shake_weak_long", "shake_regular_short", "shake_regular_medium", "shake_regular_long", "shake_strong_short", "shake_strong_medium", "shake_strong_long", "fade_in", "fade_out", "move_in", "move_out", "on", "off".
next	You can set the name of the next dialogue block. If the current block doesn't have a "next" parameter it will be the last dialogue block to be shown.

Code example:

"block_name": {
        "type": "text",
        "name": "Jimmy",
        "avatar": "jimmy/01.png",
        "position": "left",
        "animation_in": "shake_weak_short",
        "animation_out": "off",
        "content": "This string will be parsed and printed",
        "next": "next_block_name"
        }

2. divert

This type can be used when you want to show certain blocks based on conditions.

The parameters

type	Must be set to "divert".
condition	Can be "boolean", "equal", "greater", "less" or "range".
dictionary	Name of the dictionary containing the "variable" to check.
variable	Name of the variable to check.
value	Unless your "condition" is set to "boolean" you must specify a value to perform the check. Important: If you are using "equal" as condition you can set the "value" to any type (i.e. string, array, int, float). If you are using "greater" or "less" it needs to be int or float. If you are using "range" it must be an array with two values (int or float)
true	The name of the block to be called if the check returns true.
false	The name of the block to be called if the check returns false.

Code example for "boolean":

"block_name": {
        "type": "divert",
        "condition": "boolean",
        "dictionary": "variables",
        "variable": "variable_name",
        "true": "block_name_if_true",
        "false": "block_name_if_false"
        }

Code example for "equal":

"block_name": {
        "type": "divert",
        "condition": "equal",
        "dictionary": "variables",
        "variable": "variable_name",
        "value": "string example",
        "true": "block_name_if_true",
        "false": "block_name_if_false"
        }

Code example for "greater":

"block_name": {
        "type": "divert",
        "condition": "greater",
        "dictionary": "variables",
        "variable": "variable_name",
        "value": 5,
        "true": "block_name_if_true",
        "false": "block_name_if_false"
        }

Code example for "less":

"block_name": {
        "type": "divert",
        "condition": "less",
        "dictionary": "variables",
        "variable": "variable_name",
        "value": 5,
        "true": "block_name_if_true",
        "false": "block_name_if_false"
        }

Code example for "range":

"block_name": {
        "type": "divert",
        "condition": "range",
        "dictionary": "variables",
        "variable": "variable_name",
        "value": [3, 6],
        "true": "block_name_if_true",
        "false": "block_name_if_false"
        }

3. question updated

This type allows you to have a question with multiple options for the player to choose. Based on the answer you can call another block of any type.

The parameters

type	Must be set to "question".
text	Here goes the question string to be parsed and printed as a question. If the typewriter effect is active the player will only be allowed to select an option once the script has done printing the entire text.
options	Here goes an array of strings to be displayed as choices. You can use as many options as you like.
avatar	Must be a string with the avatar's relative path to the "/img/characters/" folder.
name	Must be a string with the characters name.
position	Must be set to "left" or "right" to indicate where the player's avatar and name will appear.
animation_in	Must be a string with the animation to be played at the beginning of the block's execution. Current available animations are "shake_weak_short", "shake_weak_medium", "shake_weak_long", "shake_regular_short", "shake_regular_medium", "shake_regular_long", "shake_strong_short", "shake_strong_medium", "shake_strong_long", "fade_in", "fade_out" (doesn't make any sense in this case but can be used), "move_in", "move_out" (again, can be used regardless of making any sense), "on", "off" (you know...).
animation_out	Must be a string with the animation to be played at the end of the block's execution. Current available animations are "shake_weak_short", "shake_weak_medium", "shake_weak_long", "shake_regular_short", "shake_regular_medium", "shake_regular_long", "shake_strong_short", "shake_strong_medium", "shake_strong_long", "fade_in", "fade_out", "move_in", "move_out", "on", "off".
next	Here goes an array of strings with the names of the blocks to show based on the player's answer. Important: This array must have the same size of "options".

Code example:

"block_name": {
        "type": "question",
        "name": "Jimmy",
        "avatar": "jimmy/01.png",
        "position": "left",
        "animation_in": "shake_weak_short",
        "animation_out": "off",
        "text": "String to be parsed and printed.",
        "options": ["Text for option 1", "Text for option 2"],
        "next": ["block_for_option_1", "block_for_option_2"]
        }

4. action updated

This type allows you to perform an action without having to print anything.

The parameters

type	Must be set to "action".
text	Here goes a string to be parsed and printed. If the block has no "text" parameter it will execute the action and then, if available, go to the "next" block.
operation	The operations available for now are "variable" and "random".
dictionary	If you choose to perform the "variable" operation you must specify the dictionary containing the variable to be updated.
value	If you want to perform the "variable" this parameter should be an array of arrays (even if you are only updating one variable) the subarrays having the variable name as the index 0 and the value as the index 1. In case you choose to perform the "random" operation this parameter must be an array of strings contaning the names of the blocks to be randomly picked.
avatar	Must be a string with the avatar's relative path to the "/img/characters/" folder. Important: This will not have any effect if you choose to perform the "random" operation.
name	Must be a string with the characters name. Important: This will not have any effect if you choose to perform the "random" operation.
position	Must be set to "left" or "right" to indicate where the player's avatar and name will appear. Important: This will not have any effect if you choose to perform the "random" operation.
animation_in	Must be a string with the animation to be played at the beginning of the block's execution. Current available animations are "shake_weak_short", "shake_weak_medium", "shake_weak_long", "shake_regular_short", "shake_regular_medium", "shake_regular_long", "shake_strong_short", "shake_strong_medium", "shake_strong_long", "fade_in", "fade_out" (doesn't make any sense in this case but can be used), "move_in", "move_out" (again, can be used regardless of making any sense), "on", "off" (you know...). Important: This will not have any effect if you choose to perform the "random" operation.
animation_out	Must be a string with the animation to be played at the end of the block's execution. Current available animations are "shake_weak_short", "shake_weak_medium", "shake_weak_long", "shake_regular_short", "shake_regular_medium", "shake_regular_long", "shake_strong_short", "shake_strong_medium", "shake_strong_long", "fade_in", "fade_out", "move_in", "move_out", "on", "off". Important: This will not have any effect if you choose to perform the "random" operation.
next	You can set the name of the next dialogue block. If the current block doesn't have a "next" parameter it will be the last dialogue block to be shown. Important: This will not have any effect if you choose to perform the "random" operation.

Code example for "variable":

"block_name": {
        "type": "action",
        "operation": "variable",
        "dictionary": "variables",
        "text": "Optional string to be parsed and printed.",
        "value": [["var_1", true], ["var_2", "oranges"]],
        "next": ["next_block_name"]
        }

Code example for "random":

"block_name": {
        "type": "action",
        "operation": "random",
        "text": "Optional string to be parsed and printed.",
        "value": ["block_name_1", "block_name_2", "block_name_3"]
        }

F.A.Q.

Can I use bbcode?

Yes. You can use all the bbcode functions available in Godot but you should always use @ (or any other character you set in the script configuration variables) to indicate line breaks. If you use \n or just put the text in different lines it will mess with the typewriter effect

Correct way of using multiple lines:

"text": "This text goes in the first line.@This one goes in the second line."

How can I set pauses?

You can indicate pauses during the text by just putting a | (or any other character you set in the script configuration variables) in the places you want the text to pause for a while. You can use as many pauses as you want but they will not if there are the last characters in the string.

Correct way of using pauses:

"text": "Hi.| This is how we use pauses.| You can use multiple pauses for||| ...dramatic effect!"

What are the features planned for the next version?

I actually don't have a classic roadmap for this project. I have several features in mind but they will only be implemented if they match these conditions:

Be possible to implement without needing to rewrite the core functionalities of Godot (i.e. shaking text will not be available since it is not possible using the RichTextLabel node);

Be useful for many types of games (I will not spend time trying to make a specific functionality to be used only for two or three developers).

Is this project still being developed?

If you are reading the online version of this page, the answer is yes.

When the next version is going to be released?

I honestly have no idea. It can be tomorrow, next week or next month. Since I'm working on this project on my free time I cannot tell for sure when the next version is going to be availabe. Be sure to follow me on Twitter and/or favorite the official repository to know when it is available.

I have some ideias. How can I contact you?

If you have any suggestions you can open an issue in the official repository of contact me via Twitter but do not expect your suggestions to be accepted unless they are really useful.

My game have some specific needs that may not fit the project. Are you available for hiring?

Yes. I'm available as a freelancer programmer (for Godot only). Contact me via Twitter and we'll talk about your project. ;)

Changelog

v1.2May 10th, 2019

Added:

Project now supports avatars and names
Avatars have animations (using the "Tween" node) to be played at the beginning and at the end of each block

Updated:

Project updated to Godot 3.1
"Main.tscn" scene updated for better UX
initiate() function now has an optional second parameter that can be used to start the dialogue from a specific block

Fixed:

So many small execution bugs
"first" block can be any type now without any problem
ContinueIndicator doesn't stay on screen anymore if the last block called was a "action" one

v1.1Jan 14th, 2019

Added:

Open-source Adobe Source Sans Pro font family included under the SIL Open Font License 1.1
"random" operation to the block type "action"
"equal", "greater", "less" and "range" operations added to the block type "divert"
"AnimationPlayer" added to the "Dialogue.tscn" scene
"ContinueIndicator" added to the "Dialogue.tscn" scene
Dialogue frame size can be set changing the "frame_width" and "frame_height" variables
Dialogue frame vertical aligment can be set changing the "frame_position" variable
Dialogue frame vertical margin can be set changing the "frame_margin_vertical" variable
Label margin can be set changing the "label_margin" variable
Choices vertical margin can be set changing the "choices_margin_vertical" variable
Choices horizontal margin can be set changing the "choices_margin_horizontal" variable
Choices horizontal text alignment can be set changing the "choices_text_alignment" variable
"Choices" horizontal node alignment can be set changing the "choices_node_alignment" variable
"BetaStuff.tscn" scene and "beta_stuff.gd" script added to test upcoming features without affect the stable ones

Updated:

Project updated to Godot 3.1 beta 1
The whole project file structure has been updated for better consistency and ease of use
All the signals are now connect via GDScript for better customization
Dialogue examples cleaned and updated
"variable" condition renamed to "boolean" in the "action" block type
Choices now are aligned to the bottom right corner of the dialogue frame by default
If typewriter effect is active all choices are now grey by default until the question is completely displayed
All operations using variables must specify a dictionary

Fixed:

Using multiple lines now works properly. Just use @ instead of \n

Removed:

"Position2D" removed from "Choices" node in "Dialogue.tscn" scene

v1.0Jan 7th, 2019

First release