📜 Content

• What is Dialogic 2?
• How do I get started?
• Can I upgrade from Dialogic 1 to Dialogic 2?

What is Dialogic 2?

The Dialogic plugin allows you to easily create in-game dialogs or fully fledged Visual Novels with Godot.

Let's get an overview of what Dialogic 2 can do for you!

1. Timelines!

They control the flow of your story. They can be edited in a writer-friendly Visual Editor or your editor of choice.

If you prefer to write your timelines as pure text, you can do that too! Dialogic even has a powerful text editor with autocompletion and syntax highlighting. You can use any text editor, though. Here is the same timeline in text format:

join juliet 1
juliet: Oh Romeo, what's your favourite game type?
join romeo 2
romeo: Oh Juliet, it's simple...
- Visual Novels
    jump VNs
- JRPG
    jump other_timeline

No threads attached; you can mix and match as you please!

2. Events

Each timeline contains events, and Dialogic equips you with many built-in ones to get your story started today! And when you reach their limit, you can easily create more.

3. Customization by design

Cannot find the right Event? Need more options for your character portraits? You want to simplify how your designer can adjust the theme of your game?

It's all here and ready for you. Dialogic 2 is easy to use for writers and powerful but intuitive to extend for programmers.

Create your own specific Events with very little code, and your designers can instantly use them as if they were part of Dialogic.

4. Character system and editor

An entire system to create and manage your characters, with a built-in editor inside Dialogic. No need to program anything; just create your characters and use them in your timelines.

There is more!

We are just scratching the surface of what's possible.
Here is a small list of other things you can do:

• Create events and timelines in code!

• Use built-in "text actions", for instance [speed], [pause], [signal], [portrait].

• Easy-to-use variables in your timelines!

• Create a glossary for words and let your players hover over them to discover their definition.

• Translate characters and timelines with the integrated CSV file system!

• Seamlessly create Custom Events; they are all scripts! (.gd).

• Access functionality from code, for instance, "Dialogic.Portraits.change_portrait(Emilio, "happy"), Dialogic.Backgrounds.update_background("res://icon.png")

How do I get started?

First, let's get Dialogic up and running! After this step, the numerous pages on the left-side navigation bar will aid you with your dialog-driven game adventure!

Need further details? Try the search or open an issue on the GitHub repository!

Can I upgrade from Dialogic 1 to Dialogic 2?

There are several problems to overcome when upgrading from Dialogic 1.

First, Dialogic 1 is exclusively for Godot 3, while Dialogic 2 requires Godot 4.1 or higher. Hence, your project must work in Godot 4.1, it's a very different engine with plenty of changes.

If you have already made a lot of progress in your game, there is no reason to upgrade. We recommend you stick to Godot 3 and Dialogic 1.

This tutorial teaches you how to install Dialogic and gives a quick overview of the necessary elements you need to know for making a dialog appear in your game.

📜 Content

• 1. Installation & Activation
• 🚧 How to install the latest WIP Version 🚧
• 2. Meeting the editor
• 3. Creating a timeline
• 4. Creating a character
• 5. Adding dialog to your game
• You have got started!

1. Installation & Activation

Dialogic 2 requires Godot 4.2 or higher. If you don't know what version you have installed, take a look at the bottom of your Godot Editor.

Let's install Dialogic 2:

• Download the ZIP file here for your desired Dialogic version: GitHub Dialogic Releases.
• Extract the addons folder from this ZIP-file, it contains Dialogic.
• Move the addons folder to your Dialogic project folder.

Now, let's verify you have correctly installed Dialogic:

• You have this folder path res://addons/dialogic
• Head to Project > Project Settings
• Click the Plugins tab.
• Tick the enabled button next to Dialogic.
• Restart Godot

🚧 How to install the latest WIP Version 🚧

2. Meeting the editor

You can now access the dialogic interface by clicking the new tab at the very top (next to 2D, 3D, Script and AssetLib).

You will be greeted by the dialogic home screen. At the top you can see the different editors dialogic has, at the left a sidebar that will contain recently used characters and timelines.

In the top right, there are some helpful buttons:

• Add Timeline
• Add Character
• Reference Manager
• Play Timeline

We will start by using the first one.

3. Creating a timeline

To create a timeline, press the Add Timeline button. You will need to select a folder to put the timeline in and enter a file name. Timelines will be saved as *.dtl files.

Once you hit Save, you can start adding events from the panel to the right of the editor.

Tip: You can learn more about each event and its settings by right-clicking on the event and selecting Documentation.

If you like, you can switch to the text editor by clicking on the Text Editor button at the top right. You can find out more about writing timelines in text format here: Writing timelines in text format.

You can test the timeline by clicking the Play Timeline button at the top right.

4. Creating a character

To create a new character, press the Add Character button at the top right.

As for timelines, you need to select the place to save to and a name.

Once your character is created, you will see the character editor. This editor has four main sections.

You can learn more about portraits, custom portraits, and the character settings in this tutorial: Characters & Portraits

5. Adding dialog to your game

The last important step is to actually have your dialog show up in your game.

For that, we need two things:

• A) to have nodes that can display our timeline
• B) to start the execution of the timeline.

Luckily for us, Dialogic provides a method that does both of those: Dialogic.start(timeline_name_or_path)

So the code to start your dialog when an input is pressed could look like this:

func _input(event: InputEvent):
    # check if a dialog is already running
    if Dialogic.current_timeline != null:
        return

    if event is InputEventKey and event.keycode == KEY_ENTER and event.pressed:
        Dialogic.start('chapterA')
        get_viewport().set_input_as_handled()

You have got started!

Congratulations! You now know the basics of Dialogic. There is much more to learn, though. Here is a list of tutorials you might want to explore next:

• Writing timelines in text format
• Characters and Portraits
• Creating timelines in code
• Styles and Layouts

📜 Content

• May I use Dialogic in one of my projects?
• How can I change the input?
• How to make the dialog show up in the game?
• Why are my portraits not showing up?
• Why isn't this part of Godot?
• How do I start and stop background music?
• How do I find the current speaker or its portrait index?
• How can I find the name of the current timeline?
• I cannot see or press my buttons?
• My input action to start dialog conflicts with the advancing input action
• I change the timeline text, but the game shows old text?
• How do I hide and show the text-box?
• I encounter a small lag or freeze when starting the dialogue!
• How to transition from dialog to gameplay?

May I use Dialogic in one of my projects?

Yes, you may use Dialogic to make any kind of game - even commercial ones! The project is developed under the MIT License. All we ask is that you please remember to credit us in your project!

If you want to be featured on the "Made with Dialogic"-page, get in touch with us on Emilio's Discord server!

How can I change the input?

Dialogic uses a Godot InputAction for the so-called "Input Action". By default, this is the dialogic_default_action which is automatically created when enabling the plugin. You can either edit this action or use a different input action by changing the setting in the dialogic settings Text section.

How to make the dialog show up in the game?

The easiest way to make the dialog appear in your game is to call Dialogic.start("res://path/to/timeline.dtl") in your game. This will both create a layout scene and start the timeline.

Why are my portraits not showing up?

When using the Visual Novel layout, to make the characters show up on the screen, you need to make them join your current scene using the Character event (Join mode).

Why isn't this part of Godot?

The plugin is cool! Why is it not shipped with Godot?

I see numerous people saying that the plugin should come with Godot, but I believe this should stay as a plugin since most of the people making games won't be using it. I'm flattered by your comments, but this will remain a plugin :)

How do I start and stop background music?

Use a Music event to set a resource and then cancel it with a Music event with no resource.

This example will fade in the music over 4 seconds and then fade it out over 5 seconds.

How do I find the current speaker or its portrait index?

The following snippet will give you the current speaker and its portrait information, including the index.

var current_speaker: DialogicCharacter = Dialogic.Text.get_current_speaker()
var portrait_info := Dialogic.Portraits.get_character_info(current_speaker)
var speaker_portrait_index := portrait_info.position_index

How can I find the name of the current timeline?

Timelines have no name, they are pure text.
However, you can access the resource path:

var timeline_path := Dialogic.current_timeline.resource_path

I cannot see or press my buttons?

You might have UI elements that you want to appear on top of a dialog that is playing, but they can't be clicked or are hidden behind the background. In that case these nodes should be in a Canvas Layer with a higher index! Learn about using canvas layers here: Godot Docs about Canvas Layers

My input action to start dialog conflicts with the advancing input action

Many people start their dialog with some kind of "interaction" key, which can be the same as the Dialogic Input Action (e.g. Enter or X, etc.). In that case it can happen that a new dialog starts whenever you want to advance or on the last input of the dialog. It's easy to solve these issues with simple checks in your code, for example:

func _input(event):
    if player_is_in_area and Input.is_action_pressed("start_interaction"):
         # Only start a new dialog if no dialog is currently active
         if Dialogic.current_timeline == null:
              Dialogic.start("ARelevantTimeline")

I change the timeline text, but the game shows old text?

If you have enabled translation, you will have to update the CSVs.
Once your timeline events have translation IDs, matching CSV rows will take priority.
Disabling the translation until you are done with most of the text is recommended.

How do I hide and show the text-box?

The following code allows you to check if the text box is visible and then act based on its state.

if Dialogic.Text.is_textbox_visible():
    Dialogic.Text.hide_textbox()
else:
    Dialogic.Text.show_textbox()

I encounter a small lag or freeze when starting the dialogue!

Preloading a style can be very useful using its prepare method.
This can be called on all styles you will need during the splash screen of your game.

var style: DialogicStyle = load("res://path/to/my/style.tres")
style.prepare()

On top of this, you can preload an empty timeline during your loading segment of your game.

Last, be aware that Godot's shader compiler runs on demand; whenever new shaders need to be loaded in a style (or any resource), it will compile, causing a freeze.
Hence, it's recommended to compile these ahead of time if you run into problems still.

How to transition from dialog to gameplay?

When your dialog ends and you want to switch to a different context (e.g. gameplay) you will have to decide how to deal with the current dialog layout. In Settings/General you will find the Layout Node Behaviour setting, which you can switch between Delete, Hide and Keep.

If you plan to have a transition that is managed outside of dialogic, you might have to use Hide and then manually show it again and hide it later. E.g.:

func _on_dialogic_timeline_ended() -> void:
    var layout := Dialogic.Styles.get_layout_node()
    layout.show()
    # do my transiton
    await transtion_finished
    layout.hide()

Or you trigger the transition from within the timeline, so that the timeline only ends once the transition asks for it. Then you can use the Hide or Delete modes. Here is an example scene transition code snippet (on an autoload), that is then called from the timeline:

func change_scene(scene_path: String):
    Transition.fade_out()
    await Transition.fade_out_completed
    get_tree().change_scene_to_file(scene_path)

The character editor allows you to edit character resources (.dch). It has four sections.

📜 Content

• 1. Main Settings
• 2. Portrait list
• 3. Preview
• 4. Portrait settings

1. Main Settings

The character resource has a number of settings:

1.1 General

• Display Name:   This string will be shown on the name label. Notably this can be a variable if you want the display name to change during the game. Just put the variable name in curly brackets.

• Nicknames:   These strings (comma separated) will also be considered for the Autocolor names option (in the text settings).

• Description:   Does nothing. Could help you remember what this character was for.

1.2 Portraits

• Default Portrait:   The portrait that will be used if none is specified (for Character event Join mode or text effect [portrait]). This does not affect Text events without a portrait specified! In that case, there will be no change.

• Portrait Settings:   Scale, offset and mirror settings that will be applied to all portraits. Note that scale, offset and mirror can also be set individually per portrait.

1.3 Style

• Style:   If you set a custom style, it will be used whenever this character is speaking. As this can result in rapid style changes, we suggest using the same layout for variations like this.

1.4 Typing Sounds

• Sound Moods:   A sound mood is a folder of sounds, and a random one is played for each letter these characters say. You can have different sound moods for different portraits.

2. Portrait list

The portrait list allows you to add portraits to your character. A portrait is a scene that will be instanced and moved around by Dialogic when you use the Character event.

A character can have unlimited portraits, but each has to have a unique name.

1. Add a new portrait
2. Add a new portrait group
3. Import a folder of images as portraits
4. Rename a portrait or group (or double-click or use F2)
5. Duplicate a portrait
6. Delete a portrait or group (or Delete key)

Note: Groups are not actually saved. This means empty groups will get lost when leaving the editor.

3. Preview

The preview shows the selected portrait (or nothing, if you don't have a portrait). You can switch between a Full view that will size the character so it's fully visible and a Real size view that shows the character at full scale.

4. Portrait settings

The portrait section consists of multiple sections, each containing settings for the currently selected portrait.

The most important setting is the scene a portrait uses. The default scene allows you to select an image. However, you can also use the Layered Portrait scene.

Learn more about how to create a custom portrait here: Custom portraits

For any portrait, you can set a scale, offset and mirror setting. These are additive to the main scale, offset and mirror. You can choose to ignore the main character scale to work around this.

When you use a custom portrait, you can override its exported variables here.

This page describes when and how to create a custom scene to use for one, multiple, or all portraits in your game.

📜 Content

• 1. Introduction
• 2. Requirements
• 3. Overwriting methods
• 4. Export overrides
• 5. Tips and Tricks
• 6. Examples

1. Introduction

Oftentimes, you want something more complex than a simple image: an animated image (e.g., AnimatedSprite), a rigged and animated character, a character with a single body but many face variations, or something entirely different.

To achieve these, you will have to create a custom portrait scene.

If you want to use a layered portrait, take a look here: Layered Portrait

One scene can be used for one or multiple portraits. If a scene is used for multiple portraits, switching between them will not re-instance the scene and only call _update_portrait(portrait_name) on that scene (see more below). This allows you to even animate from one portrait to the next.

2. Requirements

There are not many requirements for portrait scenes:

• Root needs to be Node2D or Control: The root nodes need a position and scale property, so they must be a Node2D or Control node (or a subclass). Because the root will act as the "pivot point," it's suggested to use a simple node like Marker2D and have all functional nodes (like sprites, animation players etc.) be children of it.
• Root script extends DialogicPortrait: The root node script should extend the DialogicPortrait class and overwrite some of its methods.

3. Overwriting methods

You can customize the behavior by adding a script to the root node and adding specific methods to it.

Like _ready or _process these will be called automatically by dialogic when needed, and if implemented:

• _update_portrait(character: DialogicCharacter, portrait_name: String) -> void
  This method is called when the portrait is instanced and when a change to another portrait using the same scene is performed. For example, you could play a specific animation in an AnimatedSprite based on the portrait name or show a specific image.

• _set_mirror(is_mirrored: bool) -> void
  Different scenes might want to mirror differently (AnimationSprite.flip_h; self.scale.x = -1, etc.). Thus, you will have to implement this functionality yourself.

• _get_covered_rect() -> Rect2:
  This is used for correctly sizing your scene, as it's mostly impossible to know the size of your portrait. If you implement this and return a rect2 that covers your portrait (relative to the root node's position), the portrait_containers size modes and the character editors Full View will work.

• _set_extra_data(data: String) -> void
  The Character event Join/Update mode allows specifying some extra information in the text editor. If this extra information is provided, this method will be called. This can be very useful to enable certain things. For example, your character could have different modes or items. Using CustomPortraitFaceAtlas under addons/dialogic/Example Assets/Portraits as an example, to show the character's alien you can use a Character Update event: update Character [extra_data="alien"].

• _should_do_portrait_update(character: DialogicCharacter, portrait: String) -> bool
  Rarely needed, but if overridden, this will be checked if the portrait change is performed to a portrait with the same scene. If you return false, then this instance will be deleted and a new instance will be made. If not implemented, this defaults to true, meaning this instance will be used for the portrait update too.

• _highlight() -> void
  Invoked when the character becomes the active speaker.

• _unhighlight() -> void
  Invoked when the character is no longer the active speaker, e.g., another character started talking.

4. Export overrides

If you add exported variables to your scene's script, you can change their values in the portrait settings in the character editor. This allows you to change these values for different portraits that use the same scene.

@export_file var image := ""
@export var modulation := Color.WHITE

This will add an image and modulation setting to all portraits using this scene.

If you define an export group called Main all the settings in it will be displayed above the others (which are grouped under Settings):

5. Tips and Tricks

In most portraits, you should call apply_character_and_portrait() the first thing in your _update_portrait() method. This method simply sets the character and portrait and will switch the portrait string to the default portrait if the portrait is not valid.

func _update_portrait(passed_character:DialogicCharacter, passed_portrait:String) -> void:
    apply_character_and_portrait(passed_character, passed_portrait)

Simple image-based scenes (that use Sprite or TextureRect) can use the apply_texture method, which takes the displaying node and an image path. If you do so, the portrait class will also automatically handle _get_covered_rect() and _set_mirror() for you.

func _update_portrait(passed_character:DialogicCharacter, passed_portrait:String) -> void:
    apply_character_and_portrait(passed_character, passed_portrait)
    
    # $Portrait is a TextureRect or Sprite
    # image is an exported string
    apply_texture($Portrait, image)

6. Examples

Besides the DefaultPortrait scene (in addons/dialogic/Other) there are some example scenes in addons/dialogic/Example Assets/Portraits, that implements some or all of these methods to achieve different effects.

Take a look at them if you feel unsure how to implement a valid portrait scene!

This page describes how to create and use layered portrait scenes.

📜 Content

• 1. Introduction
• 2. Rundown
• 2.1. Preparation
• 3. Creating the Base Layered Portrait Scene
• 4. Filling the scene
• 5. Controlling the Layers from the timeline
• 5.1. Layer Command Syntax
• 6. FAQ
  • 6.1. My Portrait's Position is wrong
  • 6.2 Do I have to use CanvasGroup as Root Node?

1. Introduction

If you want to have a character with multiple layers, like a body, a head, and a mouth, you can use the custom Layered Portrait scene. This scene allows creating a character from many sprites and then allows showing, hiding and switching between these sprites from the timeline!

If you are eager to learn more about how dialogic uses scenes to create portraits and the requirements for creating a custom portrait, please refer to the Custom Portraits page.

2. Rundown

First, you will learn how to create a new layered portrait scene and set it up correctly.

Finally, you will learn how to control the layers of the portrait using the timeline.

2.1. Preparation

I will use a character named Agustina, if you want to follow along, you can download the assets from https://dejinyucu.itch.io/agustina-visual-novel-sprite.

Heads up: The character is available as a PSD file; you will have to pick the layers and export them as image files.

You will also have to have a character. You can use an existing one or create a new one for this. On that character (in the Character Editor) add or select a portrait.

3. Creating the Base Layered Portrait Scene

In the Character Editors "Portrait Settings" section, head to the Scene section.

Click the little arrows icon to change the portrait scene.

In the popup that opens select the Layered Portrait and then click Customize This Scene.

This will promt you to save the new scene somewhere in the file system. Navigate to a place that makes sense in your file oranization and adjust the file name if necessary. Then click Save.

You can now open this scene with the little arrow icon button (or from the file system).

4. Filling the scene

At the beginning the scene will have only a few nodes to get you started:

You will usually have a "Base" layer, which should be the first Sprite we add. So we select the first Sprite, rename it to "Base", and drag our base texture into the inspectors Texture property.

For anything you have "variations" of, in this case for example the Eyes, Eyebrows, Mouths and Clothes, you'll want to have a "Group", like the one that is already in the scene. A group will later allow us to easily switch between these variations.

By adding more Groups (Node2D) and Sprites (Sprite2D), naming them properly (we will use these later) and setting the textures, we will get something like this:

Note: The Sprites of the Augustina example all fill the same rectangle. This means they are automatically all correctly positioned on top of each other. If your sprites cover different regions of the character, you might have to manually move them to be positioned correctly.

Save the scene and head back to the character editor. If everything went right, you should now see your scene there:

Hurray!

5. Controlling the Layers from the timeline

You can control these layers from the character event (when joining or updating). Any communication with the portrait scene happens via the extra_data parameter, for example like this:

join Agustina center [extra_data="set Mouth/Happy"]
[wait_input]
update Agustina [extra_data="set Eyes/Wink, set Mouth/Laugh, set Clothes/Outfit2"]

In the visual editor you can use the same commands in the "Extra Data" field.

5.1. Layer Command Syntax

Here is a list of valid commands you can use in the extra_data parameter:

# Show an entire group:
show Group1

# Show a layer, does not hide others:
show Group1/Layer1

# Hide a group:
hide Group1

# Hide a layer:
hide Group1/Layer1

# Show only one layer and hide the others:
set Group1/Layer1

If you want to use multiple commands in one extra_data parameter, you can separate them with a comma:

update agustina [extra_data="show Glasses/Normal, set Emote/Shock"]

6. FAQ

6.1. My Portrait's Position is wrong

The layered portrait calculate the combined size of all the layers. If your layers have different sizes/positions, make sure no layer extends further then needed. Try enabling all of your layers and select all nodes, you will be able to see all boundaries in the editor window of your scene.

By default the Layered Portraits scripts fix_offset parameter (in the inspector under Layered Portrait/Private/fix_offset) is on. This will adjust the position based on the first sprite on the assumption that it will be the base sprite. For many portraits that makes it easier, but for more granular control you can turn it off. In that case your sprites should be positioned so that the top-left corner of your character is at the scene origin!

6.2 Do I have to use CanvasGroup as Root Node?

No, but it's the best at handling transitions.

This page is all about how dialogic can display timelines in your game using Styles, Layouts and Dialogic Nodes.

📜 Content

• 1. Introduction
• 2. Working with styles
• 3. Custom Styles & Layouts

1. Introduction

One important aspect of Dialogic is how it allows you to display your timelines. To achieve this, there are a number of systems working together: Dialogic Nodes, Layout Scenes and Styles.

Dialogic Nodes are nodes that can be placed in any scene. These nodes will be activated by dialogic and do wildly different things, from displaying text, labels or choices to playing sounds or defining a clickable area.

Layout Scenes are scenes that contain both Dialogic Nodes, other Godot Control nodes, and custom scripts and provide a standalone UI-part. For example, there is a VisualNovel Textbox Scene, a Glossary Popup Scene or a Centered Choices Scene.

Dialogic Styles are a resource that holds a combination of layout scenes and allows for setting them. This is the easiest way to modify the look of Dialogic, as styles can be edited in Dialogic's Style Editor.

2. Working with styles

You can find a video walkthrough of Dialogic styles here: Dialogic 2 - New Style System - YouTube

A style is made up of:

• One Base layout scene (of type DialogicLayoutBase) and settings for that scene.

• A list of Layer layout scenes (of type DialogicLayoutLayer) and settings for each layer.

In the style editor, you can

• Add new styles (either starting empty or from a premade style)

• Rename Styles

Add, replace, or remove layers (both premade scenes and custom scenes)

• Set all kinds of settings on any of the scenes that are part of that style

• Make one of the premade layers or a whole style custom

• Make an inherited style from another style (inherits scenes and default settings)

• Change the default style

2.1 Using styles in game

You can switch between different styles with the Change Style event, by calling Dialogic.Styles.load_style() before calling Dialogic.start(), or by assigning a style to a character.

3. Custom Styles & Layouts

You can customize all parts of this "Displaying" part of Dialogic.

3.1 Custom styles

The simplest is creating a custom style by combining different layers and changing their settings.

3.2 Custom Layout Scenes

The next step would be to customize part of your layout (one of the scenes) beyond what's possible with the provided settings.

An easy way to do this is to use the "Make Custom" button above the layer list and select "Current Layer".
This will create a copy of that layer's scene, which you can edit in Godot. This is what you would do if you generally like, e.g., the text box, but would like to change something about it that's impossible with just the settings.

Alternatively, you can start a custom layout scene from scratch.

• Your scene's root node has to have a script that extends from either DialogicLayoutBase or DialogicLayoutLayer depending on your use-case.

• In your scene root script, you can export variables, which will appear as settings in Dialogic's style editor. Grouping them with @export_group and @export_subgroup makes it even nicer. Note that not all types are supported here.

• If you want to utilize Dialogic's style system, then you should apply any @exported settings in a method called _apply_export_overrides() which is called whenever the style changes.

You can add your custom scene effortlessly by either using Add Layer or Replace Layer above the layer list.

3.3 Custom nodes

While Dialogic's modules usually expect the nodes that display them to be made in a certain way, that doesn't prevent you from actually customizing the nodes themselves. Each dialogic node is just a normal control node with a script attached to it. Usually, dialogic nodes interact with dialogic subsystems through a group they add themselves to.

Note that in most cases, reacting to some Dialogic signals (or signals of existing dialogic nodes) can be way easier than creating a custom version of a dialogic node.

Dialogic Nodes are custom nodes provided by Dialogic that handle the presentation of your timelines in your game.

📜 Content

• 1. Introduction
• 2. What is a Dialogic Node?
• 3. Using Dialogic nodes

1. Introduction

Usually, this means Dialogic will add a layout scene made of DialogicNodes. This is what happens if you call Dialogic.start() and can be set in the Style editor. It is also possible to integrate DialogicNodes into your existing UI.

This topic is closely related to Styles and Layouts, so take a look at that page if you haven't done so yet.

You can find all Dialogic nodes in our Node Class Reference Index.

2. What is a Dialogic Node?

Many events have nodes that you need if you want them to actually affect the game:

• Text event: DialogText, NameLabel, NextIndicator, TypingSound

• Character event: PortraitContainer

• Choice event: ChoiceButton, ChoiceSound

• Background event: Background

• Text Input event: TextInput

If you want to find all Dialogic nodes, check out the Node Class Reference Index.

Here are some things to know about Dialogic nodes:

• Dialogic Nodes provide very different functionality. Hence, they have very different properties. Learn more about each Dialogic Node by adding it to your scene and taking a look at the inspector.

• Some Dialogic Nodes use settings from the dialogic settings page.   A general rule-of-thumb is that settings that should be the same for all instances of a Dialogic node are usually a Dialogic setting, while things that might change from node to node are properties.

3. Using Dialogic nodes

You can add these nodes with the usual Add Node window.

It's not relevant where they are placed in the tree, as they will be recognized by the group they are automatically added to.

Some Dialogic nodes require a special setup. For example, the TypingSound node expects to be the child of a DialogText node.

Variables are a good way to keep track of all kinds of things during your game. Dialogic has an easy-to-use and beginner-friendly variable system built in. However, Dialogic allows you to use outside variables (or Autoload Singletons) just as easily. You can also access the Dialogic variables from outside scripts.

To fully utilize these variables, this page contains all you need to know.

📜 Content

• 1. The Dialogic variable editor
• 2. Using variables in the timeline
• 3. Using variables for other cool stuff
• 4. Using variables outside Dialogic

1. The Dialogic variable editor

Dialogic variables can be set up in the "Variables" tab. Each variable consists of a name and an initial default value.

Variables can be grouped together in folders, which just have a name.

Important: Inside a folder, no item (variable or folder) can have the same name.

2. Using variables in the timeline

2.1 Variables in texts

In text events, you can insert the value of a dialogic variable by typing {variable_name}. If your dialogic variable is inside a folder (or multiple folders), you have to specify the whole name separated with dots: {MyFolder.variable_name} or {FolderA.FolderB.variable_name}

If you want to use a variable from an Autoload write {AutoloadName.variable}. This syntax also allows calling methods on that autoload. Whatever is returned from the method is inserted into the text: {Autoload.get_random_name()}

You can even do simple operations inside the brackets: {{Player.Health}/10.0+2}

2.2 Conditions

One of the main uses for variables is in conditions: if, elif, or conditions on choices.

Conditions: Visual Editor

In the visual editor, you can simply select the variable from the dropdown and compare it to a value of your choice. If you need something more complex, click the <E> button and use the syntax described below.

Conditions: Text syntax

In conditions, you can use all the same tricks as in text events and a couple more:

• Accessing autoloads: Autoload.property

• In these conditions, Autoloads don't have to be wrapped in {} brackets.*

• Using autoload methods: Autoload.check_info("Argument", false)

  - A condition always results in a boolean at the end, using the same rules as GDScript for type conversion.

• Using variables and typical boolean operators (==, !=, <, >, <=, >=, not, and, or, brackets):

  - {Player.Health} > 5 or {Player.Luck} > randi()%10

2.3 Set Variable event

You can change variables in a timeline with the set variable event. This can set dialogic variables as well as autoload variables.

Set Variable: Visual Editor

In the visual editor, you can simply select a variable and a value. You can also set the value of an Autoload variable by typing Autoload.variable in directly into the variable field and submitting with Enter (there is no auto-completion).

The value that it will be set to can be a

• string,

• number (float or int),

• value of another variable,

• complex expression,

• random number

Complex Expression allows you to use the full range of possibilities. Behind the scenes, all of these types are expressions; the distinction is only made for a simpler UI.

Expressions follow the syntax described below.

Set Variable: Text syntax

The set variable event has a special syntax to make it easy to write and read:

set {variable_name} = 20

set {MyFolder.variable} += 2

set Autoload.property = "Hello World"

set {Player.Health} += range(10,20).pick_random()

set Autoload.health = {Player.Health} + 2

The value is parsed as an expression, similar to what is done with {expressions} inside text events or in conditions. All the same can be done here as well, the only difference is that it won't be converted to string/bool.

2.4 Text Input event

A special kind of set variable event is the Text Input event, which allows you to capture a text input the player makes in a variable.

3. Using variables for other cool stuff

3.1 Variables as character names

A character Display Name can be a variable. That is the best way to control that character's name during the game. To achieve this, just type {MyVariableName} in the display name field in the character editor.

3.2 Variables in glossaries

You can use variables in glossary titles, texts and extras. This is the best way to control the text during the game. You can do all the same things as in the text event.

4. Using variables outside Dialogic

You might want to access variables from scripts outside dialogic.

You can do so with direct access:

Dialogic.VAR.my_variable = 20
print(Dialogic.VAR.Group.other_variable)

You can also do so by string:

Dialogic.VAR.set('my_variable', 20)
print(Dialogic.VAR.get('Group').get('my_variable'))

Folders (as well as the root "folder") have some methods that might be useful:

• folders() lists all folders in this folder (not strings but FolderObjects)

• variables(@absolute) lists the names of all the variables in that folder

• has(@variable_name) returns true if such a variable exists

This allows you to do fancy stuff like this:

var location = Dialogic.VAR.Towns.folders().pick_random().variables().pick_random()

Could pick a random house/place if your variables are set up like this:

Towns (folder)

   - Town A (folder)

      - CharacterAHouse

      - CharacterBHouse

      - Church

      - School

  - Town B (folder)

      - CharacterCHouse

      - CharacterDHouse

      - University

      - Park

Dialogic.VAR also has:

• Dialogic.VAR.reset(@variable_path="") resets the given variable or all variables if none is specified

• Dialogic.VAR.parse_variables(@string) returns the given string with variables replaced. This is what is used by the text event, etc.

Whether you write in the visual editor or text editor, inside texts you can use a bunch of special syntax to make them look and behave just the way you want.

Additionally, you can also use BBCode, about which you can learn more in the Godot docs: BBCode in RichTextLabel.

📜 Content

• What is a Text Effect?
• 1. Variables
• 2. Breaks and New Events
• 3. Speed & Pause effects
• 4. Random selection
• 5. Signal effect
• 6. Portrait & Mood effects
• 7. Auto-Advance

What is a Text Effect?

A Text Effect (or text-tag) is a written command in the form of a special BBCode. While Godot's BBCodes require a Rich Text Label, Dialogic's work inside the timeline's Text Events and do not use Godot's system for custom BBCode effects.

Dialogic's Text Effects permit you to control Auto-Advance (whether text continues automatically), waiting some time, awaiting your own signals, or changing the text speed.

1. Variables

You can use dialogic variables (and even autoload variables) in your text events easily. Learn more about how to do so here: Variables

2. Breaks and New Events

[br] Inserts a break into a text event.

[n] Visually starts a new event, requiring manual advancement by the user or by the Auto-Advance system.

[n+] Requires some sort of advance (user input or auto-advance), but will append the following text to the previous without clearing the text box.

[input] Will simply await any input. As opposed to [n+], it is not breaking the text up into multiple sections and can thus be skipped.

3. Speed & Pause effects

Text speed is a complicated topic, as it can be used in numerous ways. Dialogic has

• a letter speed that specifies the time to wait on each symbol when revealing

• a speed multiplier that will temporarily modify the letter and pause speed

• a user speed multiplier setting that will additionally modify letter and pause speed

3.1 Letter Speed

The default letter speed can be changed in the text settings. It can be changed temporarily (it will reset before the next event) with these effects:

• [lspeed=x] Sets the letter speed to x in seconds (e.g., [lspeed=0.1]). This is modified by the temporary speed multiplier and the user speed setting!

• [lspeed=x!] Sets the letter speed to x in seconds. This is not multiplied with the speed multipliers!

• [lspeed] Resets the letter speed.

3.2. Temporary Speed Multiplier

The speed multiplier is 1 by default, so it has no effect. It can be changed temporarily (it will reset before the next event) with these effects:

• [speed=x] Sets the speed to x. As this will multiply the pause length or letter delay, higher values will result in a slower reveal, and lower values will result in a faster reveal. 0 will instantly reveal the text.

• [speed] Resets the speed multiplier to 1.

3.3 Pauses

You can pause the reveal with these effects:

• [pause=x] Pauses the reveal for x seconds (e.g., [pause=0.2]). This is modified by the temporary speed multiplier and the user speed setting!

• [pause=x!] Pauses the reveal for x seconds. This is not multiplied with the speed multipliers!

Related to this are Auto-Pauses, which can be configured in the text settings to insert pause effects after certain symbols. This can be used to easily alter the flow of punctuation.

3.4 User Speed multiplier setting

Oftentimes, you might want to expose the reveal speed as a setting to the player. To easily allow this, you can use the "text_speed" setting.

You can access it via the Settings subsystem Dialogic.Settings.text_speed = 0.5. This should enable you to implement a speed slider in your settings

4. Random selection

If a text is encountered multiple times during your game, it might be nice to vary it a bit. For this, the random selection modifier allows you to insert only one option from a list like this:

• <Option 1/Option 2/Option 3> Inserts one of the options (separated with /) into the text.

  • E.g.: <Hi/Hello/Howdy> <my friend/dude/bro>, how are you doing?

5. Signal effect

If you want to notify/activate something outside Dialogic in the middle of a text event, you can use the [signal=arg] effect. It will trigger the Dialogic.text_signal signal with the given argument as a string. Learn more about the signal: Dialogic Signals

6. Portrait & Mood effects

You can change the portrait or typing mood of the speaker with these effects:

• [portrait=name] Changes the portrait of the speaker to the portrait with the given name.

• [mood=name] Changes the typing mood to the one with the given name.

7. Auto-Advance

There are the following text effects to control Auto-Advance:

• [aa] enables the Auto-Advance for the current text event.
• [aa=time] enables Auto-Advance after a fixed delay of time seconds; four seconds before Auto-Advance continues: [aa=4]
• [aa=time?] changes the fixed delay for the current text event but does not enable Auto-Advance.

Timelines are saved in a text format, which means that you can use any text-editing software to edit and create them. The built-in text editor provides useful autocompletion and syntax highlighting.

For Dialogic to register your timeline file, it has to use the .dtl extension!

📜 Content

• About short code events
• About special events
• About indentation
• Example timeline

About short code events

Most events follow a shortcodes-like style:

[background path="res://icon.png" fade="1.0"]

The order of the parameters is not relevant, but they have to be separated by at least one space. All parameters, regardless of type, have to be contained in double quotation marks.

To find all the parameters you can use on each event, check out their documentation by searching for their class in the Godot Help or this documentation.

About special events

Some events have a custom syntax to make writing them easier. This includes:

Text Event

A wonderful text event, said by noone in particular.

Emilio: Hello and welcome!

Emilio (excited): I'm excited cann you tell?

Emilio: This is a text event with \
multiple lines. Isn't that great? It is!

Ending a text event with \ will make it include the next line as well.

Character event

join Emilio (happy) center [animation="Bounce In"]

leave Emilio [animation="Bounce Out" length="0.3"]

update Emilio (excited) left [animation="Tada" wait="true" repeat="3" move_time="0.3"]

Check the Character Event documentation for more information and examples.

Choice event

- Yes
- No | [if {John.Relationship} > 23]
- Maybe | [if {Stats.Charisma} > 10] [else="disable" alt_text="Maybe [to insecure]"]

Condition event

if {Player.Wisdom} > 3:
    # dialogics syntax is indentation based!
elif {Player.Health} <= 10:
    # some events
else:
    #...

Set Variable event

set {MyVariable} += 10

Supported Operators are =, += , -= , *=, /=

Comment event

# Some comment

Label event

label LabelIdentifier

# a label with a display name
label LabelIdentifier (Display Name)

Jump event

jump LabelIdentifier

# Jump to a label in another timeline
jump TimelineName/LabelIdentifier

# Jump to the beginning of another timeline
jump TimelineName/

Return event

return

Do/Call event

do Autoload.method("argument")

About indentation

Timelines use TAB indentation to know what events belong to a choice or condition block. Only changes in indentation are considered, so it doesn't really matter how much you indent, as long as you are consistent within one block.

Example timeline

[background path="res://assets/backgroudns/dialogic_factory.png"]

join Jowan left
jowan (exited): Hello and welcome to[portrait=confused]...[pause=0.5] Wait? What is this?

join Emilio (happy) right
Emilio: Well, this is is the example timeline.

Jowan: I thought this was a cool new feature?

Emilio: Nah, sorry.

Jowan (sad): It's okay.

# Some choices jump back to this
label WhatAbout

Jowan (default): So what should this example be about?
- How to bake cookies
    Emilio (confused): Wait that hasn't to do with dialogic?!
    jump WhatAbout

- How to reach the moon | [if {Player.Name} == "NASA"]
    Jowan (angry): NASA! It's you again. This is for making dialogs!\
    Please ask someone else about the moon!.
    
    jump WhatAbout

- How to write timelines in text format
    Jowan: Oh, well it's pretty intuitive.[pause= 0.2][portrait=questioning] I hope.
    
    Emilio: Let's hope it's easy as well.

[end_timeline]

As timelines and events are just resources, you can create new timelines in code.

📜 Content

• How do I create timelines via code?

How do I create timelines via code?

Creating an empty timeline would look like this:

var timeline : DialogicTimeline = DialogicTimeline.new()
Dialogic.start_timeline(timeline)

Of course, the timeline created here doesn't contain events yet. To add events, you can do two things:

• Create an array of event resources:

var events : Array = []
var text_event = DialogicTextEvent.new()
text_event.text = "Hey, this was made in code!"
text_event.character = load("res://characters/Emilio.dch")
events.append(text_event)

var timeline : DialogicTimeline = DialogicTimeline.new()
timeline.events = events
# if your events are already resources, you need to add this:
timeline.events_processed = true
Dialogic.start(timeline)

• Create an array of Strings:

var events : Array = """
Jowan (Surprised): Wow this is interesting!
- Yes
    [background path="res://icon.png"]
    [wait seconds="1"]
    set MyAutoload.exitement += 20
- No
    set MyAutload.exitement -= 10 """.split('\n')

var timeline : DialogicTimeline = DialogicTimeline.new()
timeline.events = events
Dialogic.start(timeline)

In this case, you have to follow the syntax explained in this tutorial.

The character event is used for characters that have portraits. It allows joining, leaving and updating them and configuring how they appear in the game.

📜 Content

[TOC]

Text Syntax

# Basic join event
join MyCharacter center
# Specifying a portrait and shortcode parameters
join MyCharacter (SomePortrait) center [animation="Bounce In"]
# Character with a space in the name and a portrait that's inside a group
join "My Character" (Special/Crazy) center
# Specifying the transform manually
join MyCharacter pos=x0.5y1 size=y400px rot=20`

# Basic leave event
leave MyCharacter
# Specifying shortcode parameters
leave MyCharacter [animation="Fade Down"]
# Leaving all joined characters
leave --All--

# Update that animates the character
update MyCharacter [animation="Tada" length="2" wait="true"]
# Update that changes the position (and tweens it)
update MyCharacter left [move_time="1" move_trans="Elastic" move_ease="In"]
# Update that changes the portrait
update MyCharacter (OtherPortrait) [fade_time="0.5"]

The Main Settings

Action Setting | Join / Leave / Update

The character event knows three modes Join, Leave and Update.

Join events will add a character. They require a position/transform to be given and will use In-Animations.

Leave events will remove one or all characters. They ignore most settings and will use Out-Animations.

Update events allow you to change stuff, like the position or portrait. They can also be used to animate the character. They have a few settings that Join and Leave don't use: Fade and Fade Time, Move Time, Move Trans and Move Ease. Also the Update event will only change a setting if it has been set, so if no portrait is given the previous portrait is kept, same for the position, etc.

Text Syntax: The mode is set by starting the event with either join, leave or update

Character Setting

The character that is going to be used. In Leave-mode this can be --All-- characters.

Text Syntax: join MyCharacter , leave "My Character", leave --All--

Right after join/leave/update put the character identifier. If the identifier contains a space, you have to put the identifier in quotes.

Portrait Setting

Text Syntax: After the character identifier put the portrait in (brackets): join MyCharacter (MyPortrait)

The portrait that should be used. If none is given, Join mode will use the characters default portrait, while Update mode will just not change the portrait.

Portraits that are in groups have to be specified by full path: Group/SubGroup/Portrait

The portrait setting can be an expression inside {curly brackets}, for example a variable: {PlayerPortrait}. The experssion will be evaluated and interpreted as a string that should be the name/path of a portrait.

Position/Transform Setting

This setting defines where on screen your character is positioned. When you character is joined it will be put in a brand new PortraitContainer, which you can then change the position, size and rotation of with the transform setting. There are two ways to do so:

• Using a preset "position" you can easily copy the tranform of one of the PortraitContainers defined in your style by using one of it's identifiers. By default dialogic provides 5 of these preset positions, named "leftmost", "left", "center", "right", "rightmost".

• Using transform commands you can position, size and rotate the container with more control. For example pos=x0.5y1 size=y400px rot=20.

Using a Preset Positions

Moving the container to a preset position is as easy as writing the name of that position.

In the default "5-Portraits" style layer the defined positions are leftmost,left, center, right, rightmost.

Using Transform Commands

There are three transform commands: pos= (position), size= and rot= (rotation).

Position and size can be specified like this: x0.5 y1, x100px y1% By default x and y are interpreted as relative to the viewport size, meaning 0.5 means half the width/height of the window.

Position defines the ORIGIN of the portrait (usually the bottom center). This means a position of x0.5 y1 will position the portrait like this:

When first joining a character, the position, size and rotation will be copied from the first portrait preset found. This means if you just want to vary the position along the x axis, a simple pos=x0.3 is usually enough and all the other values will be correct by default.

Rotation is given in degrees. The portrait rotates around it's origin (usually the bottom center)!

The Other Settings

In the text editor these settings are all stored as parameters in the shortcode at the end of the event.

E.g. join MyCharacter center [animation="Bounce" length="1" mirrored="true" ]

Animation Setting

Text Syntax: animation="Bounce"

The animation setting allows you to set an animation that should be used. The selection of animations is different depending on the mode.

If no animation is given, Join and Leave will fallback to defaults that can be set in Settings>Portraits, while Update won't play any animation.

The animation name is quite forgiving meaning Fade Up, fade up in fade In Up will all point to the right animation (assuming this is a join event).

You can add animations to dialogic with extensions: Creating Extensions

Animation Length Setting

Text Syntax: length="2" / length="0.5"

If an animation is set, this defines the length of the animation in seconds.

Animation Wait Setting

Text Syntax: wait="true" / wait="false"

If an animation is set, this defines, whether to wait for the animation to finish before going to the next event.

Animation Repeat Setting

Text Syntax: repeat="2"

The animation repeat setting (exclusive to the Update mode) allows repeating the animation multiple times.

Fade Setting

Text Syntax: fade="Fade"

The fade setting (exclusive to the Update mode and only relevant if the portrait changes) defines the Crossfade animation that is used to fade from the last portrait to the next. If none is given it will fall back to a default that can be set in Setting>Portraits.

Fade Length Setting

Text Syntax: fade_length="0.5"

Defines the length of the fade in seconds.

Z-Index Setting

Text Syntax: z_index="2"

The z-index allows you to sort your characters. It is not using godot's z-index and instead sorting the characters manually!

Mirror Setting

Text Syntax: mirrored="true"

Allows mirroring the portrait.

Move Settings

Text Syntax: move_time="0.8" / move_trans="Elastic" / move_ease="In Out"

On Update events that change the position you can set the time (in seconds), transition and easing used to tween from the old to the new position.

Easings: In, Out, In Out Out In

Transitions: Linear, Sine, Quint, Quart, Expo, Elastic, Cubic, Circ, Bounce, Back, Spring

See this Easing Cheat Sheet for something more visual.

Extra Data Setting

Text Syntax: extra_data="something"

The extra data is given to the portrait scene and allows communicating with the portrait scene directly from the timeline. It can be evaluated from the _set_extra_data(data:String) method on custom portraits.

Auto-Advance allows you to advance the timeline without user input.

📜 Content

• 1. What is Auto-Advance?
• 2. Main Settings
• 3. Changing Auto-Advance from code
• 4. Modifying the reading speed
• 5. Auto-Advance Text-Effect

1. What is Auto-Advance?

Auto-Advance is an experience-changing feature in Dialogic that allows players to automatically progress through the timeline without requiring user input! It's particularly useful for providing a hands-free experience to your players, offering an alternative to traditional "click-to-advance" methods in games.

You may also know this feature by the names "auto-forward" or simply "auto".

2. Main Settings

In Dialogic's Settings tab, under the Text section, you can find the main Auto-Advance settings. Hover over the tooltip icons to learn more about each setting.

2.1 Additional Delay

One critical setting is the Additional Delay, which allows you to choose between Per Character and Per Word. These settings modify the pace at which text is displayed, adding extra delays either on character or word count.

Some languages, for instance Japanese, don't separate words by spaces. Dialogic uses the popular whitespace used by the spacebar to determine when a word ends and another begins. If you plan on providing multiple localisations, you can set both settings via the API.

Ignored Characters

These characters will be ignored when counting the characters. This feature allows you to further fine-tune your Auto-Advance experience. If you don't need it, simply toggle it off.

3. Changing Auto-Advance from code

Dialogic's Auto-Advance class can be easily accessed via the Inputs subsystem and allows you to change Auto-Advance during your game. It also has a number of settings not exposed to the dialogic interface.

All of this functionality lives in Dialogic.Inputs.auto_advance an DialogicAutoAdvance object.

3.1 Settings/Properties

There are two types of settings/properties:

Enable conditions

• enabled_until_next_event: bool
• enabled_forced: bool
• enabled_until_user_input: bool

As long as one of the enable conditions is true, Auto-Advance will continue. This allows stacking the reasons why Auto-Advance has been enabled. Imagine, the player enables Auto-Advance, but the Text event forces it on until the next event.

Thanks to the multiple enable conditions, if the player disables Auto-Advances, it will still carry on until the next event.

You can turn any of the enable-variables to true to enable Auto-Advance. If you have an Auto-Advance button, you can use the following code to enable the feature:

Dialogic.Inputs.auto_advance.enabled_until_user_input = true

Behaviour changing settings

• fixed_delay: float Same as the base delay in the Settings
• per_word_delay: float Additional delay multiplied by the word count
• per_character_delay: float Additional delay multiplied by character count
• await_playing_voice: bool If true (by default) Auto-Advance will wait until voice lines have finished

Per Character and Per Word Delays

You can see that using these properties you can have both per word and character delays which add up.

To accommodate languages without spaces between words, you can adjust the per_word_delay and per_character_delay variables when changing language.

Here's an example of how to configure these settings in your script:

# We can change the settings by directly writing to the returned dictionary.
Dialogic.Inputs.auto_advance.per_word_delay = 0.3
Dialogic.Inputs.auto_advance.per_character_delay = 0.1

3.2 Toggled Signal

If you want to be informed about changes in Auto-Advance's state, you can use the Dialogic.Inputs.auto_advance.toggled signal.

signal toggled(enabled: bool)

If you are interested in how Dialogic uses this signal internally, the Inputs subsystem connects to this signal:

Dialogic.Inputs.autoadvance.toggled.connect(_on_autoadvance_toggled)

4. Modifying the reading speed

For Visual Novels, enabling players to set their text speed is a common practice. To provide the same feature using Dialogic, consider setting Dialogic.Settings.autoadvance_delay_modifier.

This setting, located within Dialogic.Settings, allows you to fine-tune the delay modifier, multiplying "Additional Delay". By default, if this value is not set, Dialogic uses a multiplier of 1, causing no change to the delay.

5. Auto-Advance Text-Effect

By writing [aa] or [aa = 2] in your text, you can temporarily enable Auto-Advance in a text event and override the delay.

• [aa] enables Auto-Advance until (at least) the next text event

• [aa=2] enables Auto-Advance and sets the delay to 2 seconds.

  • This ignores per_word_delay and per_character_delay but respects await_playing_voice.

• [aa=2?] does not enable Auto-Advance but sets the time to 2 seconds if Auto-Advance is already enabled.

Auto-Skip allows you or the player to quickly advance the timeline.

📜 Content

• 1. What is Auto-Skip?
• 2. How to use it?
• 3. Enabling and modifying Auto-Skip
• 4. Reacting to Auto-Skip

1. What is Auto-Skip?

Auto-Skip is the concept of advancing a timeline faster than you can read it.

In Visual Novels, Auto-Skip helps to navigate already known story branches quickly. If your story is not intended to be cyclic, this feature may not be of use to you.

2. How to use it?

In Dialogic, Auto-Skip can be enabled and modified from code using the DialogicAutoSkip object that can be accessed via the Inputs subsytem (e.g. Dialogic.Inputs.auto_skip.

The most common way this feature is used, to provide the player with an Auto-Skip toggle button. This section will teach you how to implement the logic for this.

First, you can set the time each event is allowed to take via the Text settings page inside Dialogic.

However, there are many settings that are not exposed to the interface!

3. Enabling and modifying Auto-Skip

All Auto-Skip settings are variables on the DialogicAutoSkip class. This class can be accessed via Dialogic.Inputs.auto_skip. It has a bunch of useful settings:

• enabled: bool If true, dialogic will Auto-Skip.

Disable Conditions

If these settings are on, they tell dialogic to automatically disable Auto-Skip under certain conditions/at certain moments.

• disable_on_user_input: bool If true (by default) dialogic will disable Auto-Skip when the Dialogic Input Action is triggered.

• disable_on_unread_text: bool If true (by default) dialogic will disable Auto-Skip when any unread text is reached.

Enable Condition

• enable_on_seen: bool If true (by default) dialogic will enable Auto-Skip whenever a text event is reached that you visited before.

General Settings

• skip_voice: bool If true (by default) Auto-Skip will skip voice events instead of playing them.

• time_per_event: float Defines the time for each event (equivalent to the setting in the Settings>Text page).

So you can enable Auto-Skip like this:

Dialogic.Inputs.auto_skip.enabled = !Dialogic.Inputs.auto_skip.enabled

You can use this to quickly advance through your timelines, for example, for debugging purposes. For this you should disable the disable_on_unread_text setting like this:

Dialogic.Inputs.auto_skip.disable_on_unread_text = false

4. Reacting to Auto-Skip

4.1 Signals

When Auto-Skip is enabled or disabled, the class will emit the DialogicAutoSkip.toggled signal.

Here is an example on how to connect to the signal:

# Connect to the signal.
func _init():
    Dialogic.Inputs.auto_skip.toggled.connect(_on_auto_skip_toggled)

## If Auto-Skip disables, we want to stop the timer.
func _on_auto_skip_toggled(is_enabled: bool) -> void:
    # Your code reacting to Auto-Skip changes goes here!

4.2 In Custom Events

Events come in all sort of behaviours: Awaiting signals, instantly executing, a mix of conditions, playing audio, …

It's impossible to let an Auto-Skip handle all of these effects gracefully from the outside. Therefore, Auto-Skip's behaviour must be implemented by each Timeline Event.

What type of event do I have?

Does your event finish instantly? Is it playing audio? Awaiting a signal? These situations must be implemented differently.

If you await signals, you can use the DialogicAutoSkip.toggled to cause your event to react to Auto-Skip. The Text Event uses this signal to skip the text animation and then advance the timeline.

If you await a timer or perform an action lasting multiple frames, you can use the time_per_event variable to limit the time your event may take. Here is a code snippet to give you an idea:

var animation_length: float = 10.0

if Dialogic.Inputs.auto_skip.enabled:
    var time_per_event: float = Dialogic.Inputs.auto_skip.time_per_event
    animation_length = min(time_per_event, animation_length)

This code will cap the animation length to the maximum time set if Auto-Skip is enabled.

Dialogic provides a lot of signals that allow you to react to all kinds of things. If you are new to Godot's signals learn how to use them here.

In other programs, signals are often referred to as events, and they are a way to implement the Observer pattern.

📜 Content

• 1. Signal event
• 2. Text signal
• 3. Start & End signals
• 4. Subsystem signals

1. Signal event

The signal event is used to inform code outside Dialogic that something happened or should happen.

When reached, the event will emit the signal Dialogic.signal_event and pass along the argument given in the event.

Here the argument is "activate_something".

To react to the signal event, connect to it before starting your dialog:

func _ready():
     Dialogic.signal_event.connect(_on_dialogic_signal)

func _on_dialogic_signal(argument:String):
    if argument == "activate_something":
        print("Something was activated!")

2. Text signal

When using the [signal=activate_something] text effect, dialogic will emit the Dialogic.text_signal signal with the given argument.

You can connect it the same way as the signal_event signal:

func _ready():
     Dialogic.text_signal.connect(_on_dialogic_text_signal)

func _on_dialogic_text_signal(argument:String):
    if argument == "activate_something":
        print("Something was activated!")

3. Start & End signals

Using the Dialogic.timeline_ended and Dialogic.timeline_started signals (both have no arguments) lets you react to dialog ending or beginning.

Example:

func start_dialog():
    Dialogic.timeline_ended.connect(_on_timeline_ended)
    Dialogic.start("my_timeline")

func _on_timeline_ended():
    Dialogic.timeline_ended.disconnect(_on_timeline_ended)
    # do something else here

4. Subsystem signals

Dialogic subsystems have many useful signals. Here is a selection of them:

• Dialogic.Text has

  • signal about_to_show_text(info:Dictionary)
  • signal text_finished(info:Dictionary)
  • signal speaker_updated(character:DialogicCharacter)
  • signal textbox_visibility_changed(visible:bool)
  • signal animation_textbox_new_text
  • signal animation_textbox_show
  • signal animation_textbox_hide

• Dialogic.Portraits has

  • signal character_joined(info:Dictionary)
  • signal character_left(info:Dictionary)
  • signal character_portrait_changed(info:Dictionary)

• Dialogic.VAR has

  • signal variable_changed(info:Dictionary)
  • signal variable_was_set(info:Dictionary) # only on set variable events

If you want to find all signals, head over to the Subsystem Index, select a subsystem and take a look at the related Signals category.

📜 Content

• How do I pause the timeline?

How do I pause the timeline?

You can pause/resume the currently running dialog with Dialogic.paused = true and Dialogic.paused = false. This does not pause the scene tree.

Obviously, many games require the ability to save and load!

📜 Content

• 1. Built-in Saving
• 1.2 Saving Extra Info
• 1.2.1 Accessing Extra Info
• 2. Handling Savegame Slots
• 2.1 Check if a Savegame Slot exists
• 2.2 Delete a Savegame Slot
• 3. Manual Saving

1. Built-in Saving

The saving subsystem allows you to save and load Dialogic timeline states, game thumbnails (screenshots), and extra information to Savegame slots.
You want to save the player position or the last seen text? The built-in save system has it all covered!

Be aware that Savegames uses their name as a folder name; operating systems restrict the allowed characters for folder names. It's recommended to rely on the Latin alphabet, numbers, and underscores.

If you don't care about Savegame slots, you can do the following:

# Example signal handling.
func _on_save_game_button_pressed() -> void:
    Dialogic.Save.save()

func _on_load_game_button_pressed() -> void:
    Dialogic.Save.load()

However, these methods will take screenshots too, which may affect performance slightly.
If you want to prevent this from happening, it gets a bit more verbose:

# Example signal handling.
func _on_save_game_button_pressed() -> void:
    Dialogic.Save.save("", false, Dialogic.Save.ThumbnailMode.NONE)

func _on_load_game_button_pressed() -> void:
    Dialogic.Save.load()

1.1 Take a thumbnail

If you would like to use thumbnails per Savegame slot, it's recommended to take the screenshot before opening your Save & Load layer.
This can be achieved by calling Dialogic.Save.take_thumbnail() before you show the layer; for instance, in the button signal connection, open the layer.

If you go this route, you need to instruct the Dialogic.Save.save(...) method to store only and not take a screenshot.

Dialogic.Save.save(slot_name_variable, false, Dialogic.Save.ThumbnailMode.STORE_ONLY, slot_extra_info)

This snippet will automatically take the thumbnail saved at Dialogic.Save.latest_thumbnail and use it.

1.2 Saving Extra Info

By default, Savegames contain information about Dialogic's timeline and Dialogic variables. If you want to store specific information about a Savegame, we can achieve this by using Dialogic.Save.set_slot_info(slot_name:String, info: Dictionary) and Dialogic.Save.get_slot_info(slot_name: String) methods.
However, the Dialogic.Save.save(...) method can simplify our work and skip calling the set method.

Extra information is not loaded into the Dialogic state info. In other words, it solely serves to provide information about a Savegame.

In the following code snippet, we will save the last used text line and the current time as extra information.

var extra_info := {}
extra_info["text"] = Dialogic.current_state_info["text"]
extra_info["date"] = Time.get_datetime_string_from_system(false, true)

Dialogic.Save.save(slot_name, false, Dialogic.Save.ThumbnailMode.STORE_ONLY, extra_info)

1.2.1 Accessing Extra Info

Now, if you want to display your Savegames on your custom Savegame layer, you can access them via Dialogic.Save.get_slot_info.

Here is an example on how to access a specific Savegame's extra data:

# Safety check, whether our Savegame even exists.
if Dialogic.Save.has_slot(save_game_name):
     var slot_info_dictionary := Dialogic.Save.get_slot_info(save_game_name)
     var date: String = slot_info_dictionary.get("date", "")
     var text: String = slot_info_dictionary.get("text", "")

This example checks if a Savegame save_game_name exists and if so, gets its extra data. From there on, you are free to do anything with the data. For instance, display it on your custom Savegame layer.

1.3 Global data

The simple approach to storing your game data slot-independently is to use the Dialogic.Settings subsystem.
You can directly store the information on it:

Dialogic.Settings.text_speed = 0.05

On save, the data will be automatically stored in the global save file

However, if you want to write to the global save file directly, you can use the Dialogic.Save subsystem:

func set_player_name(name: String) -> void:
    # Setting a name for the key `player_name`.
    Dialogic.Save.set_global_info("player_name", name)

There is no rule for the global info key's value; being consistent is good, though.

If you are interested in storing the history of visited texts, take a look at the next chapter.

1.4 Saving Visited Events

When you play a visual novel and use multiple saves, you may find yourself discovering texts you already read, even on entirely different story branches.
By default, Dialogic does not save the events players have already visited; however, there are two main ways to get it working.

1. The first approach is via the Dialogic Editor. Head to the Settings tab and select History. From here on, you can decide if you want the already-visited events must auto-save.

2. This approach is a bit different: The following snippet will manually save the history to a file. Use this in case the player has reached the end of the game (credits?) and you want to ensure that the visited events are properly updated a last time.

var slot_name := "slot-3-page-2"

func _save_game() -> void:
     Dialogic.History.save_visited_history()
     Dialogic.Save.save(slot_name)

func _load_game() -> void:
     Dialogic.History.load_visited_history()
     Dialogic.Save.load(slot_name)

func _reset_visited_history() -> void:
     Dialogic.History.reset_already_visited_history()

If you prefer to set the configuration via code, take a look at the following snippet:

func _ready() -> void:
    Dialogic.History.save_already_visited_history_on_save = true
    Dialogic.History.save_already_visited_history_on_autosave = true

The example values will cause the visited event history to automatically save on Auto-Save and normal Saves.

2. Handling Savegame Slots

A save game slot is identified by its slot name, a unique word that you, as a developer, decide.
One way to name the slots could be by their index and the current save game page (if you intend to have many save games). This could result in slots named slot_3_page_4.

2.1 Check if a Savegame Slot exists

When you create your own save/load layer, you may want to check whether any of these slots even exist.

func load_save_game_slot(slot_name: String) -> void:
    if Dialogic.Save.has_slot(slot_name):
        # Do your logic...

However, you may also use Dialogic.Save.add_empty_slot(slot_name: String) and populate the missing slots. If you check using the snippet, it's not necessary at all, though.

2.2 Delete a Savegame Slot

You can delete a save game slot by using the Dialogic.Save.delete_slot(slot_name: String) method.

3. Manual Saving

If you want to roll your own save and load system, you can use Dialogic.get_full_state() -> Dictionary to get the state of Dialogic and then continue saving it the way you want to.
Once you are read to load the data back, you will have to use Dialogic.load_full_state(state: Dictionary) to get your data back into Dialogic.

Overall, it's better to have an idea why you want to do manual saving and take inspiration from Dialogic's save and load methods.
There is a chance that Dialogic already supports your specific loading and saving requirements.

The reference manager allows fixing broken references and renaming unique resource identifiers.

📜 Content

• 1. What kind of references are we talking about?
• 2. Broken references
• 3. Unique identifiers

1. What kind of references are we talking about?

Dialogic timelines are saved in text-syntax that often favors being readable over being specific: You do not have to specify the exact character resource every time you reference a character.

To do this, dialogic assigns each of its resources (timelines and characters) a unique identifier string. This string is initially based on the file name but can be whatever; the only important thing is: not two resources (of the same type) can have the same identifier.

There is some other name based references in dialogic, notably portraits and variables.

Dialogic provides tools to edit unique identifiers and also easily fix any broken references if you choose to rename something after having already used it in a timeline. These tools live in the Reference Manager which can be accessed via the Link button in the toolbar.

2. Broken references

The first tab allows you to fix references after you renamed something.

Dialogic will sometimes send you here. In those cases it has usually already added some renames that you should check for.

Simply click Check Selected which will scan all timelines for the references in the list above. Check if the results look like they contain the thing you want to actually replace. If not just uncheck them. Then click Replace.

The tool will automatically remove any resolved (or irrelevant) renames from the list when you close the window.

2.1 Custom replacements (Advanced)

This tool can also be used to manually replace something. This is useful if dialogic didn't correctly pick up on a rename or you would like to replace some other string in all timelines.

This can be done by clicking the Plus button.

If you select Pure Text you can enter a custom term or regex. The regex can contain a (?<replace>something) group if you would like to not replace the whole result.

Any of the other options (Variable, Portrait, Character, Timeline) will use a custom regex specialized for those types.

You can also limit a search to only lines related to a specific character (useful for portraits).

Lastly click Add. An entry will be added to the list. You can then continue like with automatically added entries.

3. Unique identifiers

Thes second tab allows you to change the unique identifiers for your characters and timelines.

You can simply double click an identifier or use the Pen button on the left.

No two identifiers in the same category can be the same.

Renaming any identifier will automatically add an entry to the "Broken References" tab which you can use to check if this rename broke anything.

Sometimes Dialogic is just not enough.

Whether it's an event, an editor, a setting or a text effect that is missing, you can add it. An extension is a folder that contains all the information about these things so that Dialogic can use it. Extensions are powerful. Actually, it's just as powerful as Dialogic's built-in stuff because they are the same.

Extensions can add:

• main editors
• events
• subsystems
• text effects & modifiers
• portrait animations
• settings
• character settings
• layout presets
• Dialogic nodes.

📜 Content

• 1. Getting started
• 2. The essential part: index.gd
• 3. Custom events
  • What is an event?
  • Your custom event
  • 4.1 Custom Saving & Loading Syntax
• 5. Custom Subsystems
  • What is a subsystem?
  • Your custom subsystem
• 6. Custom animations
  • What is an animation?
  • Creating an animation
  • Naming animations
• 7. Custom dialogic nodes
  • What are dialogic nodes?
• 8. Custom Settings Pages

1. Getting started

The best way to create an extension is to use the extension creator in the dialogic settings (General).

By clicking the Create New Extension button, you can set up an extension folder and a custom event script. Enter a name for the new module and select what you would like to add. Then click Create.

2. The essential part: index.gd

The central piece of any extension is the index.gd script. It is the only thing your extension is required to have. It has to extend DialogicIndexer and can overwrite that class's methods to let Dialogic know what things to add. For example, this code registers a custom event:

func _get_events() -> Array:
    return [this_folder.path_join('event_print.gd')]

Check out the DialogicIndexer's other methods to learn how to register other things.

3. Custom events

What is an event?

A Dialogic event is a script that defines a new class inheriting DialogicEvent. This script will define (a) how the event is represented in-editor, (b) how it is saved, and (c) what it does during timeline execution when the event is reached.

Often, events work together with subsystems.

Your custom event

The Extension Creator allows you to get a basic event script. It has already set some values for you.

These are the things you need to do to make your event fully functional:

1. Event settings:

All options for your event should be stored in variables. Define these at the top.

var print_text: String = ""
var in_game: bool = false

3.1 Execution code:

Add whatever should happen when your event is reached in the _execute() method:

func _execute() -> void:
    print(print_text)

    if in_game and Dialogic.has_subsystem('Text'):
        Dialogic.Text.update_dialog_text(print_text)
    else:
        finish()

The finish() method lets Dialogic know to continue with the next event.

3.2 General settings:

In the _init() method, you can set some base settings of your event:

func _init() -> void:
    event_name = "Printer"
    set_default_color('Color3')
    event_category = "Godot"

3.3 Saving & Loading

We will cover working with shortcodes now. They are pretty much the text view of an event inside the timeline. The following is the shortcode for the Background event.

[background arg="res://Graphics/Backgrounds/sunset.png" fade="1.5"]

To implement saving your shortcuts, return a shortcode identifier in get_shortcode() and fill out get_shortcode_parameters():

func get_shortcode() -> String:
    return "print"


func get_shortcode_parameters() -> Dictionary:
    return {
        #param_name       : property_info
        "text"            : { "property": "print_text", "default": "" },
        "ingame"          : { "property": "in_game",    "default": false },
    }

The above event might be saved as [print text="Some text to print" in_game="true"]

3.34 My Variables are not changing

If your variables are not changing despite setting values in your custom event in the timeline editor, here is a little checklist:

• Remember the name of your variable; example variable name: _audio_path.
• Check the get_shortcode_parameters:
  • This would be correct: "path" : { "property": "_audio_path", "default": "" },
  • path appears as text in the shortcode text view; this can match your variable.
  • The property value must match your variable, see _audio_path.
• Check add_header_edit including add_body_edit and others:

  • The very first parameter is the variable_name, this must match your variable.

  • An example:

    add_header_edit(
    	"_audio_path",
    	ValueType.SINGLELINE_TEXT,
    	{
    		"left_text": "File Path",
    		"mode": 1,
    	},
    )
    

After all of these values match, the visual and text modes will both change the variables in your event, and you can access them in the _execute.

4.1 Custom Saving & Loading Syntax

You can implement custom saving syntax by overriding the function to_text() -> String and from_text(timeline_event: String). The is_valid_event(event_name: String) -> bool needs to be override too, if you want to quickly check if the event name is correct.

When is custom saving and loading useful? If your shortcode has a special text syntax or is converting between values, map a word to an integer. This is what the text-, character-, choice-, condition-, and variable events do, so take a look at them if this is something you are interested in.

5. Editor fields:

Your event is now fully functional, but in the visual editor, it is still blank. You will need to override the build_event_editor() method to define the fields/texts that will appear on the event.

func build_event_editor() -> void:
   add_header_edit("print_text", ValueType.SINGLELINE_TEXT)
   add_header_edit("in_game", ValueType.BOOL, {"left_text":"(also show it in game:", "right_text":")"}, "!print_text.is_empty()")

Other methods you can use are add_header_label(), add_body_edit() and add_body_line_break(). Most of these allow setting a condition as the last parameter, allowing for adaptive visibility. In the example above, the second field will only be visible if any text is typed in the first.

If you would like to learn more about events, I strongly suggest looking at the built-in events.

5. Custom Subsystems

What is a subsystem?

A subsystem is a script that contains useful methods for game execution. Subsystems can be accessed as Dialogic.SubsystemName.method() when running the game. They should contain all of your extension's code. For example, built-in subsystems include Text, Portraits, Choices, Audio, etc.. Their methods are used by the built-in events and can be used by your events as well.

Additionally, it's good if a subsystem manages dialogic nodes. This could be done like this:

func update_my_dialogic_nodes(some_setting):
    for node in get_tree().get_nodes_in_group("dialogic_custom_nodes"):
        node.update_something(some_setting)

Your custom subsystem

A subsystem is a script inheriting DialogicSubsystem. It can override that class's methods. The most important methods you might want to override are clear_game_state() and load_game_state() for saving and loading, and pause() and resume() for pausing. If you want to save persistent data, store it in the Dialogic.current_state_info dictionary.

6. Custom animations

What is an animation?

Portrait animations are scripts extending the DialogicAnimation class. The easiest way to register them is to have them in a subfolder of your module, and then add the following code to the index.gd file:

func _get_special_resources() -> Array[Dictionary]:
    # First argument is the sub-folder, the second specifies 
    # what kind of resource this is (needed for Dialogic)
	return list_special_resources('MySubFolder', &'PortraitAnimation')

Creating an animation

Animations are little scripts inheriting the DialogicAnimation class; you can take a look at the default ones (they use tweens) at dialogic/Modules/Character/DefaultAnimations.

Your animation script should look something like this (bounce_in, for example):

Animation Example Bounce

extends DialogicAnimation

func animate():
    var tween := (node.create_tween() as Tween)
    node.scale = Vector2()
    node.modulate.a = 0

    tween.set_ease(Tween.EASE_IN_OUT)
    tween.set_trans(Tween.TRANS_SINE)
    tween.set_parallel()
    tween.tween_property(node, 'scale', Vector2(1,1), time).set_trans(Tween.TRANS_SPRING).set_ease(Tween.EASE_OUT)
    tween.tween_property(node, 'modulate:a', 1.0, time)
    tween.finished.connect(emit_signal.bind('finished_once'))

You have the following variables to work with:

• node = the node to animate. This is NOT your portrait node directly, but a Node2D that holds that portrait node
• time = the amount of time the animation should take
• end_position = where to end the animation
• orig_pos = the position you started at

Naming animations

Importantly, the name of your animation file will determine if it is a Join, Leave or Update animation! If it ends with _in or contains _in_ it is a Join animation; ending in _out or containing _out_ makes it a Leave animation, while all other names are considered Update animations (often called attention seekers in other software).

7. Custom dialogic nodes

What are dialogic nodes?

Dialogic nodes are nodes that, in some way, execute something visibly, logically or audibly. They are generally managed by a subsystem and are found because they are automatically added to a group. This makes sure it doesn't matter where they are in the scene tree or how many of them exist.

DialogicNodes does not need to be added to the index.gd file!

8. Custom Settings Pages

An extension might want to add a dialogic settings editor. This is just a UI scene that has a script inheriting DialogicSettingsPage.

• Overwrite some methods (just the ones that you need)
  • _get_title()
  • _get_priority() -> return an integer that will influence the order of settings pages
  • _refresh() -> whenever the settings are opened
  • _about_to_close() -> whenever the settings editor closes
  • _get_info_section() -> return a node in your scene that will be used as an info section Settings are usually saved either
  • in the project settings in a subcategory of dialogic (e.g. dialogic/myextension/setting):
    • ProjectSettings.set_setting('dialogic/myextension/setting', some_value)
  • You can also save/load editor settings with DialogicUtil.set_editor_setting('setting', value) and DialogicUtil.get_editor_setting('setting').
    • These depend on the project
• Remember that all scripts in this scene must be in @tool mode.

This page explains how the built-in glossary feature can be utilized.

📜 Content

• 1. What is a glossary?
• 1.1 What does a Dialogic glossary do?
• 2. How do I translate glossaries?

1. What is a glossary?

A glossary is a collection of terms with their definitions. It's a great way to keep track of your game's lore, characters, and more.

Some Visual Novels use a glossary to explain terms that may be unfamiliar to the player. For example, if your game is set in a fantasy world, you may want to explain the unique species that live in your world.

1.1 What does a Dialogic glossary do?

If a glossary contains keys, Dialogic will automatically use the name and alternatives properties of each glossary entry to highlight them and provide a tooltip with the definition if hovered over.

2. How do I translate glossaries?

Take a look at Translating Glossaries for more information.

3 Implementation

A glossary is a text resource file (tres) and after each change to the glossary, it has to be saved to the disk or the changes won't persist.

Furthermore, it has an entries property, containing an Array of Dictionarys, whereas each Dictionary represents a glossary entry.

3.1 Translation ID

Once translated, each entry will have a unique _translation_id.
The _translation_id will be added to _translation_keys glossary property, mapping glossary name properties to their entry array index.

3.2 Alias Keys

An entry key is a unique identifier for a glossary entry, either a name, an alternative (alias), or an entry translation ID (CSV key).

The aliases are used to map the entry to the true glossary entry key, allowing the code to map the glossary word to its glossary entry.

Additionally, the entry's translation ID allows the code to map a translated glossary word to its translation ID and then to the glossary entry using the _translation_keys.
The glossary entry IDs are combined, using the glossary ID and then the entry ID. This matches the translation CSV keys for translated glossaries: Glossary/3b/6c/name.

3.2 Accessing glossary properties

As a rule of thumb, if you want to access the glossary from code, do not access the _ prefixed aforementioned properties: _translation_id, _translation_keys. They may change over the course of Dialogic's development.

Instead, look for the helper methods on DialogicGlossary.

3.3 How do I get all glossary paths?

You can use the following project setting to get all glossary files:

var glossary_paths: Array[String] = ProjectSettings.get_setting('dialogic/glossary/glossary_files', [])

This page explains how Dialogic allows you to translate timelines and other important parts of your dialogs.

📜 Content

• 1. What is a translation?
• 1.1 What can Dialogic translate?
• 2. How do I translate timelines?
• 2.5 Translating Glossaries
• 2. Testing translation
• 3. Changing the Language

1. What is a translation?

Translation is a Godot and Dialogic 2 feature, allowing you to translate your game into multiple languages.

Sometimes, the word localization is used as well. Localization provides very specific regional considerations for each audience.
This includes not only the translation of the game, but also changes to the game itself to reflect specific cultural differences.

While Dialogic supports the translation of your timeline, it's better to focus on your game first and add translation later.
However, keeping translation and localization in mind is an excellent idea:

• How will you handle variables?
• Do you need the glossary?
• What images do you want to localize?
• Any features in mind that may complicate translation?

1.1 What can Dialogic translate?

Dialogic can automatically translate your timelines, character names, and glossary entries.

2. How do I translate timelines?

In Dialogic, head to the Settings tab and take a look under the Translation section. Tick the "Enable Translation" checkbox.

2.1 Setting up translation

Let's walk through the settings! You will have to pick a default locale. This locale must be the language you write the timeline in. Additionally, this locale will be used as a fallback if no translation exists for a given translatable event. The "translation file mode" allows you to store all your timelines into one file (Per Project) or into multiple files (Per Timeline).

Setting up a translation folder is a good idea; it keeps your project clean and allows you to easily find your translation files.

2.2 Writing translations

First and foremost, you will need a timeline file. Dialogic will automatically find and generate CSV files for you after you hit the "Update CSV files" button.

The CSV format is simple, and you can open it with any spreadsheet software, like Excel or Google Sheets. Even VSCode offers extensions to edit the file.
The gist of CSV files is that each line represents a row, and each column is separated by a comma.

Once Dialogic has generated the CSV file, it may look like this:

keys,en
Text/1/text,Hello World!"

The keys are locales; the en is the locale code for English. If you choose a different default locale, the locale code will be different.

You can add a new language for your game by adding a new column. The following example added "ja" for Japanese to the first row and translated the text in the second row. Pay attention to the commas!

keys,en,ja
Text/1/text,Hello World!,こんにちは世界！

That's it! You can now hit "Collect translation," and Dialogic will generate a translation file for you.
The translation file is a specific Godot file. Here is their official documentation: Internationalizing games

2.3 The Translation workflow

From now on, whenever you change the CSV file, you can hit "Collect translation" and Dialogic will update the translation files for you.
Once you are done editing your timeline, you will have to hit "Update CSV files" to update the CSV file.

To verify whether your timeline has properly inserted your text into the CSV, you can switch to the timeline Text editor. Obviously, you can check the CSV file too.

Character: Hello world! #id:14
Do you like Visual Novels? #id:15
- Yes, I do! #id:16
- No, I love them! #id:17
That's the spirit! #id:18

The #id tags at the end of each Text Event are the translation IDs. They won't be visible during text display; however,  Dialogic has inserted the text into a CSV file.

2.4 Translating Characters

Characters will be translated if they are part of a timeline. They will always get put into a per-project file. Their name and nick will be translated.

2.5 Translating Glossaries

Glossaries have a reserved property for translation: _translation_id.
They also have a reserved _translation_keys property, mapping translated words to the translation key.

These properties get automatically populated via the "Update CSV files" button.
Entries prefixed with _ (underscore) are considered private and will be ignored. Every other String property will be translated and put into the CSV.

Once translation has been enabled, and you are testing another locale, glossaries won't fall back to the default locale when an entry property has not been translated.

2. Testing translation

If everything went well, you can select a different locale in the "Testing locale" dropdown.
Hit "Play Timeline" or "Run Project" and take a look at the translated text.
This setting is editor-only and may not work in exported projects.

3. Changing the Language

The translation process is handled by Godot!

To change the locale when your game is exported, use the Godot API method on the TranslationServer class:

# Japanese's language code is "ja"
TranslationServer.set_locale("ja")

All classes from the Dialogic 2 source code.

• Subsystem

  • Audio
  • Backgrounds
  • Portraits
  • Choices
  • Animation
  • Expression
  • Input
  • Glossary
  • History
  • Jump
  • Save
  • Settings
  • Styles
  • Text
  • Text_input
  • Variables.VariableFolder
  • Variables
  • Voice

• Event

  • BackgroundEvent
  • CallEvent
  • CharacterEvent
  • ChoiceEvent
  • CommentEvent
  • ConditionEvent
  • EndBranchEvent
  • EndTimelineEvent
  • Event
  • GlossaryEvent
  • HistoryEvent
  • JumpEvent
  • LabelEvent
  • learEvent
  • MusicEvent
  • PositionEvent
  • ReturnEvent
  • SaveEvent
  • SettingEvent
  • SignalEvent
  • SoundEvent
  • StyleEvent
  • TextEvent
  • TextInputEvent
  • VariableEvent
  • VoiceEvent
  • WaitEvent
  • WaitInputEvent

• Resource

  • Character
  • CharacterFormatLoader
  • CharacterFormatSaver
  • Glossary
  • Style
  • StyleLayer
  • Timeline
  • TimelineFormatLoader
  • TimelineFormatSaver

• Node

  • BackgroundHolder
  • ButtonSound
  • ChoiceButton
  • DialogText
  • Input
  • NameLabel
  • NextIndicator
  • PortraitContainer
  • StyleLayer
  • TextBubble
  • TextInput
  • TypeSounds

• Other

  • Animation
  • AutoAdvance
  • AutoSkip
  • Background
  • BackgroundTransition
  • CharacterEditorMainSection
  • CharacterEditorPortraitSection
  • CsvFile
  • Editor
  • GameHandler
  • Indexer
  • LayoutBase
  • LayoutLayer
  • Portrait
  • ResourceUtil
  • SettingsPage
  • Subsystem
  • Util
  • VisualEditorField

All event classes from the Dialogic 2 source code.

• Event
  • BackgroundEvent
  • CallEvent
  • CharacterEvent
  • ChoiceEvent
  • CommentEvent
  • ConditionEvent
  • EndBranchEvent
  • EndTimelineEvent
  • Event
  • GlossaryEvent
  • HistoryEvent
  • JumpEvent
  • LabelEvent
  • learEvent
  • MusicEvent
  • PositionEvent
  • ReturnEvent
  • SaveEvent
  • SettingEvent
  • SignalEvent
  • SoundEvent
  • StyleEvent
  • TextEvent
  • TextInputEvent
  • VariableEvent
  • VoiceEvent
  • WaitEvent
  • WaitInputEvent

This contains the source code documentation of the class DialogicBackgroundEvent.

DialogicBackgroundEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Constants

const IMAGE = 0

No description available.

const CUSTOM = 1

No description available.

const DEFAULT = 0

No description available.

const CUSTOM = 1

No description available.

Property Descriptions

var argument = ""

var fade = 0.0

var scene = ""

var transition = ""

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_shortcode ( ) ⇒ String

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

func get_transition_suggestions ( filter: String = "" ) ⇒ Dictionary

No description available.

This contains the source code documentation of the class DialogicCallEvent.

DialogicCallEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Property Descriptions

var arguments =

var autoload_name = ""

var method = ""

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func check_arguments_and_update_warning ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func get_autoload_suggestions ( filter: String = "" ) ⇒ Dictionary

No description available.

func get_method_suggestions ( filter: String = "", temp_autoload: String = "" ) ⇒ Dictionary

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

No description available.

func update_argument_info ( ) ⇒ void

No description available.

This contains the source code documentation of the class DialogicCharacterEvent.

DialogicCharacterEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Constants

const JOIN = 0

No description available.

const LEAVE = 1

No description available.

const UPDATE = 2

No description available.

Property Descriptions

var action = 0

var animation_length = 0.5

var animation_name = ""

var animation_repeats = 1

var animation_wait = false

var character = null

var character_identifier

var extra_data = ""

var mirrored = false

var portrait = ""

var position = 1

var position_move_time = 0.0

var regex =

var set_mirrored = false

var set_portrait = false

var set_position = false

var set_z_index = false

var z_index = 0

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func get_animation_suggestions ( search_text: String ) ⇒ Dictionary

No description available.

func get_character_suggestions ( search_text: String ) ⇒ Dictionary

No description available.

func get_portrait_suggestions ( search_text: String ) ⇒ Dictionary

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

this is only here to provide a list of default values this way the module manager can add custom default overrides to this event. this is also why some properties are commented out, because it's not recommended to overwrite them this way

func has_no_portraits ( ) ⇒ bool

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func should_show_animation_options ( ) ⇒ bool

No description available.

func should_show_portrait_selector ( ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

No description available.

This contains the source code documentation of the class DialogicChoiceEvent.

DialogicChoiceEvent

Inherits: DialogicEvent

Event that allows adding choices. Needs to go after a text event (or another choices EndBranch).

Properties

Methods

Constants

const HIDE = 0

No description available.

const DISABLE = 1

No description available.

const DEFAULT = 2

No description available.

Property Descriptions

var condition = ""

var disabled_text = ""

var else_action = 2

var text = ""

Settings The text that is displayed on the choice button.

Method Descriptions

func allow_alt_text ( ) ⇒ bool

No description available.

func build_event_editor ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func get_end_branch_control ( ) ⇒ Control

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

No description available.

This contains the source code documentation of the class DialogicCommentEvent.

DialogicCommentEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Property Descriptions

var text = ""

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

No description available.

This contains the source code documentation of the class DialogicConditionEvent.

DialogicConditionEvent

Inherits: DialogicEvent

Event that allows branching a timeline based on a condition.

Properties

Methods

Constants

const IF = 0

No description available.

const ELIF = 1

No description available.

const ELSE = 2

No description available.

Property Descriptions

var condition = ""

var condition_type = 0

Settings condition type (see ). Defaults to if.

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func get_end_branch_control ( ) ⇒ Control

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func should_execute_this_branch ( ) ⇒ bool

only called if the previous event was an end-branch event return true if this event should be executed if the previous event was an end-branch event

func to_text ( ) ⇒ String

No description available.

This contains the source code documentation of the class DialogicEndBranchEvent.

DialogicEndBranchEvent

Inherits: Resource

##############################################################################

Methods

Method Descriptions

func find_next_index ( ) ⇒ int

No description available.

func find_opening_index ( ) ⇒ int

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

NOTE: This event is very special. It is rarely stored at all, as it is usually just a placeholder for removing an indentation level. When copying events however, some representation of this is necessary. That's why this is half-implemented.

This contains the source code documentation of the class DialogicEndTimelineEvent.

DialogicEndTimelineEvent

Inherits: DialogicEvent

##############################################################################

Methods

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_shortcode ( ) ⇒ String

No description available.

This contains the source code documentation of the class DialogicEvent.

DialogicEvent

Inherits: Resource

Base event class for all dialogic events. Implements basic properties, translation, shortcode saving and usefull methods for creating the editor UI.

Properties

Methods

Constants

const HEADER = 0

No description available.

const BODY = 1

No description available.

const MULTILINE_TEXT = 0

No description available.

const SINGLELINE_TEXT = 1

No description available.

const CONDITION = 2

No description available.

const FILE = 3

No description available.

const BOOL = 4

No description available.

const BOOL_BUTTON = 5

No description available.

const DYNAMIC_OPTIONS = 6

No description available.

const FIXED_OPTIONS = 7

No description available.

const ARRAY = 8

No description available.

const DICTIONARY = 9

No description available.

const NUMBER = 10

No description available.

const VECTOR2 = 11

No description available.

const VECTOR3 = 12

No description available.

const VECTOR4 = 13

No description available.

const CUSTOM = 14

No description available.

const BUTTON = 15

No description available.

const LABEL = 16

No description available.

Signals

signal event_finished ( event_resource: DialogicEvent )

Emmited when the event finish. The signal is emmited with the event resource event_resource[/code]

signal event_started ( event_resource: DialogicEvent )

Emmited when the event starts. The signal is emmited with the event resource event_resource[/code]

signal ui_update_needed ( )

Singal that notifies the visual editor block to update

signal ui_update_warning ( text: String )

No description available.

Property Descriptions

var can_contain_events = false

var created_by_button = false

var dialogic = null

var dialogic_color_name = ""

var disable_editor_button = false

var editor_list =

var empty_lines_above = 0

var end_branch_event = null

var event_category = "Other"

var event_color = Color(0.984314, 0.694118, 0.235294, 1)

var event_name = "Event"

var event_node_as_text = ""

var event_node_ready = false

var event_sorting_index = 0

var expand_by_default = false

var help_page_path = ""

var needs_indentation = false

var wants_to_group = false

Method Descriptions

func add_body_edit ( variable: String, editor_type: int = 16, extra_info: Dictionary = <unknown>, condition: String = "" ) ⇒ void

No description available.

func add_body_line_break ( condition: String = "" ) ⇒ void

No description available.

func add_header_button ( text: String, callable: Callable, tooltip: String, icon: Variant = null, condition: String = "" ) ⇒ void

No description available.

func add_header_edit ( variable: String, editor_type: int = 16, extra_info: Dictionary = <unknown>, condition: String = "" ) ⇒ void

No description available.

func add_header_label ( text: String, condition: String = "" ) ⇒ void

No description available.

func add_translation_id ( ) ⇒ String

This is automatically called, no need to use this.

func build_event_editor ( ) ⇒ void

to be overwritten by the sub_classes

func can_be_translated ( ) ⇒ bool

Returns true if there is any translatable properties on this event. Overwrite [_get_translatable_properties()] to change this.

func execute ( _dialogic_game_handler: Variant ) ⇒ void

Executes the event behaviour. In subclasses (not this one) should be overriden!

func finish ( ) ⇒ void

Ends the event behaviour.

func from_text ( string: String ) ⇒ void

loads the variables from the string stored above by default it uses the shortcode format, but can be overridden

func get_end_branch_control ( ) ⇒ Control

to be overridden by sub-classes only called if can_contain_events is true. return a control node that should show on the END BRANCH node

func get_event_editor_info ( ) ⇒ Array

No description available.

func get_property_translated ( property_name: String ) ⇒ String

Call this whenever you are using a translatable property

func get_property_translation_key ( property_name: String ) ⇒ String

No description available.

func get_shortcode ( ) ⇒ String

if this uses the short-code format, return the shortcode

func get_shortcode_parameters ( ) ⇒ Dictionary

if this uses the short-code format, return the parameters and corresponding property names

func is_string_full_event ( string: String ) ⇒ bool

has to return true if this string seems to be a full event of this kind (only tested if is_valid_event() returned true) if a shortcode it used it will default to true if the string ends with ']'

func is_valid_event ( string: String ) ⇒ bool

has to return true, if the given string can be interpreted as this event by default it uses the shortcode formta, but can be overridden

func parse_shortcode_parameters ( shortcode: String ) ⇒ Dictionary

used to get all the shortcode parameters in a string as a dictionary

func remove_translation_id ( ) ⇒ void

No description available.

func set_default_color ( value: Variant ) ⇒ void

No description available.

func should_execute_this_branch ( ) ⇒ bool

to be overridden by sub-classes only called if can_contain_events is true and the previous event was an end-branch event return true if this event should be executed if the previous event was an end-branch event basically only important for the Condition event but who knows. Some day someone might need this.

func to_text ( ) ⇒ String

returns a readable presentation of the event (This is how it's stored) by default it uses a shortcode format, but can be overridden

func update_text_version ( ) ⇒ void

Call this if you updated an event and want the changes to be saved.

This contains the source code documentation of the class DialogicGlossaryEvent.

DialogicGlossaryEvent

Inherits: DialogicEvent

############################################################################## INITIALIZE ##############################################################################

Methods

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_shortcode ( ) ⇒ String

############################################################################## SAVING/LOADING ##############################################################################

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

This contains the source code documentation of the class DialogicHistoryEvent.

DialogicHistoryEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Constants

const CLEAR = 0

No description available.

const PAUSE = 1

No description available.

const RESUME = 2

No description available.

Property Descriptions

var action = 1

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_shortcode ( ) ⇒ String

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

This contains the source code documentation of the class DialogicJumpEvent.

DialogicJumpEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Property Descriptions

var label_name = ""

var timeline

var timeline_identifier = ""

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func get_label_suggestions ( filter: String = "" ) ⇒ Dictionary

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

func get_timeline_suggestions ( filter: String = "" ) ⇒ Dictionary

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

############################################################################## SAVING/LOADING ##############################################################################

This contains the source code documentation of the class DialogicLabelEvent.

DialogicLabelEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Property Descriptions

var display_name = ""

var name = ""

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

############################################################################## SAVING/LOADING ##############################################################################

This contains the source code documentation of the class DialogiClearEvent.

DialogiClearEvent

Inherits: DialogicEvent

############################################################################## EDITOR REPRESENTATION ##############################################################################

Properties

Methods

Property Descriptions

var clear_background = true

var clear_music = true

var clear_portrait_positions = true

var clear_portraits = true

var clear_style = true

var clear_textbox = true

var step_by_step = true

var time = 1.0

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_shortcode ( ) ⇒ String

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

This contains the source code documentation of the class DialogicMusicEvent.

DialogicMusicEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Property Descriptions

var audio_bus = "Master"

var fade_length = 0.0

var file_path = ""

var loop = true

var volume = 0.0

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_bus_suggestions ( ) ⇒ Dictionary

No description available.

func get_shortcode ( ) ⇒ String

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

This contains the source code documentation of the class DialogicPositionEvent.

DialogicPositionEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Constants

const SET_RELATIVE = 0

No description available.

const SET_ABSOLUTE = 1

No description available.

const RESET = 2

No description available.

const RESET_ALL = 3

No description available.

Property Descriptions

var action = 0

var movement_time = 0.0

var position = 0

var vector = Vector2(0, 0)

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_shortcode ( ) ⇒ String

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

This contains the source code documentation of the class DialogicReturnEvent.

DialogicReturnEvent

Inherits: DialogicEvent

############################################################################## INITIALIZE ##############################################################################

Methods

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

############################################################################## SAVING/LOADING ##############################################################################

This contains the source code documentation of the class DialogicSaveEvent.

DialogicSaveEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Property Descriptions

var slot_name = ""

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_shortcode ( ) ⇒ String

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

This contains the source code documentation of the class DialogicSettingEvent.

DialogicSettingEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Constants

const SET = 0

No description available.

const RESET = 1

No description available.

const RESET_ALL = 2

No description available.

const STRING = 0

No description available.

const NUMBER = 1

No description available.

const VARIABLE = 2

No description available.

const EXPRESSION = 3

No description available.

Property Descriptions

var mode = 0

var name = ""

var value = ""

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func from_text ( string: String ) ⇒ void

No description available.

func get_settings_suggestions ( filter: String ) ⇒ Dictionary

No description available.

func get_value_suggestions ( filter: String ) ⇒ Dictionary

No description available.

func is_valid_event ( string: String ) ⇒ bool

No description available.

func to_text ( ) ⇒ String

No description available.

This contains the source code documentation of the class DialogicSignalEvent.

DialogicSignalEvent

Inherits: DialogicEvent

Settings

Properties

Methods

Constants

const STRING = 0

No description available.

const DICTIONARY = 1

No description available.

Property Descriptions

var argument = ""

var argument_type = 0

Method Descriptions

func build_event_editor ( ) ⇒ void

No description available.

func get_shortcode ( ) ⇒ String

No description available.

func get_shortcode_parameters ( ) ⇒ Dictionary

No description available.

This contains the source code documentation of the class DialogicSoundEvent.

DialogicSoundEvent

Inherits: DialogicEvent

Settings

Properties

Methods