02 Using DDSL

Setting up a dialog box

DDSL does not provide a built-in dialog box, meaning one needs to be created. For this, create a new scene with the root node DialogBox. It can contain any UI needed for the dialog box. Then attach a script to it. You must implement:

• func output(sprite, text: String, options: Dictionary = {})
  • This function is used to display a message(with the portrait passed as sprite) to the player
  • After the player confirms, skips or finishes the dialog, signal outputComplete() must be emitted
• func input(type: Dialog.InputOption, branches: Array, options: Dictionary = {})
  • Used for getting input from the player. The type parameter can have any data needed to correctly set up correct input UI, so checking againt all supported input classes is needed
  • The branches argument passes all non-null branches if any matching is present
  • After input complete, must emit signal inputComplete(value: Variant), passing the player input as value In both cases, the options parameter passes additional arguments to the dialog box, not regulated by the plugin.

An example implementation can be found in the project's github

Creating a dialog script

To create a dialog script, create a text file, ending with .ddsl. You can open it in Godot's built-in script editor. It should not be highlighted by default. To enable highlighting, in the editor menu, go to Edit > Syntax Highlighter and select DDSL. After this the dialog script can be edited. The language for it is detailed in DDSL Language

Using the Dialog autoload

All interactions with the plugin are expected to be done primarily using the Dialog autoload. It has these main elements

## Emitted before starting dialog
signal dialogStarted

## Emitted after ending dialog
signal dialogEnded

## Start a dialog from file[br][br]
## [code]dialog[/code]: path to the dialog resource in DDSL syntax[br]
## [code]callback[/code]: callable executed when dialog finishes[br][br]
## [code]return[/code]: returns Dictionary[String, Variant] of internal interpreter variables[br]
func start(dialog: String, callback: Callable = Callable()) -> Dictionary

## Sets the current dialog box style[br][br]
## [code]box[/code]: The dialog box style. Must be an instantiated scene[br]
func setBox(box: DialogBox)

## Various functions for interacting with globals, shared between all scripts
func bindGlobal(thing: Variant, name: String)
func removeGlobal(name: String)
func getGlobal(name: String, default: Variant = null)

Note that if source code needs to be passed instead of a path to a script, startFromSource(source: String, callback: Callable = Callable()) -> Dictionary can be used.

For the script to be able to interact with the game's world, you should first set global variables up. After this is done, the dialog can be initiated in one of the following ways

# the simplest way to initiate a dialog
Dialog.start("res://path/to/dialog.ddsl")

# callback is executed just after the `Dialog.dialogEnded` signal is emitted
Dialog.start("res://path/to/dialog.ddsl", _some_callback)

# starting the dialog will freeze current execution until it is done, but aside from that it is the same
var variables = await Dialog.start("res://path/to/dialog.ddsl")
var variables = await Dialog.start("res://path/to/dialog.ddsl", _some_callback)