The Dialog Flow component turns a text file into a dynamic, interactive branching dialog.
Dialog Flow Scripts are syntactically similar to (although not exactly the same as) the basic SugarCube v2 format for Twine/Twee. Unlike Twine stories, Dialog Flow Scripts are not HTML files and do not support Javascript. But the core syntax is similar enough that a SugarCube story can be converted to a Dialog Flow Script without too much trouble.
Dialog Flow Scripts are made up of “blocks” of text that look like this:
Dialog Script sample
:: WhatIsStrange
[Rebecca]
What do you think is strange about this scene?
[[The couple.|Couple]]
[[The poison.|Poison]]
[[The location.|Location]]
:: Couple
[Rebecca - Sad]
We’ve been assuming it’s a love suicide because of the way that the boides are found, but isn’t it strange that nobody has ever seen these two together before? None of their friends knew that either was in a serious relationship. It seems like if you love somebody so much you’d kill yourself for them, you’d probably talk to your friends or family first.
Script Format
A block is a single entry in the dialog conversation, similar to a node in Twine and other dialog systems. At a minimum, a block requires two elements:
- An action, usually to indicate the speaker, and
- Text to display for this block.
Actions are enclosed in braces, like this: [Action Name]. Actions cause a new block to start and immediately invoke an Action Sequence of the same name, defined in an Action Library selected by a Dialog Flow component. As a best practice, you can name your actions after the speakers in your dialog, and write your Script like a film script. In the example above, there are two blocks defined by two different actions: “Rebecca” (which selects the Rebecca character and gives her a neutral expression), and “Rebecca - Sad” (which changes her expression to a sad one). The text to display follows the action and will be shown in the text box selected by the Dialog Flow component.
Blocks may optionally have a label. Normally blocks are executed in sequence from the top of the file to the bottom, but labeled blocks can be used for branching choices. Labels are defined at the beginning of a block with a double colon followed by the label name: :: Label Name In the example above “WhatIsStrange” and “Couple” are the labels of the two nodes.
The flow of the conversation can be controlled by jumping directly to a label instead of just going on to the next one in the file. [->Label Name] at the end of a block will move to the label specified for the next block. Jumps can also be conditional on the output of a calculation. For example, [timesAsked < 3->Ask Again] will only jump to the “Ask Again” label if the “timesAsked” variable is less than 3.
Labels are also used for choices. When a block contains a choice, the conversation will stop moving forward until the choice is selected (see below). Choices are indicated by double brackets, the text to display for the choice, followed by a vertical bar, followed by the label of the block to jump to if that choice is selected. [[Choice text|Label name]].
Variables (object, scene, or project) may also be manipulated in a block using the form [variableName = value or equation]. For example, [timesAsked = 0] will set the timesAsked variable to zero, while [timesAsked = timesAsked + 1] adds one to it. For a complete reference of supported math functions, see Math Functions.
Detailed Example
Here is the Dialog Flow Script for a conversation sequence. In this dialog, Rebecca asks the player to consider several aspects of a murder before moving on. This example uses variables to track which aspects have already been talked about and continues the conversation only when all topics have been considered.
| Script | Meaning |
|---|---|
| :: Start | Label for the first block |
| [Rebecca] | Triggers the “Rebecca” action |
| OK, let’s recap what we know so far. <p>The bodies of a man and a woman were found on this beach. The police have decided it was a love suicide, since the two were lying peacefully next to each other. A bottle of juice mixed with cyanide was found nearby. | Text displayed for the first block |
| [[It just doesn’t add up.|AddUp]] | Presents a choice with only one option, that proceeds to the “AddUp” block when selected |
| :: AddUp | Starts the second block and names it “AddUp” |
| Yes, I agree. | Text for the second block |
| [choice1 = 0] | Sets the variable “choice1” to 0 |
| [choice2 = 0] | Sets the variable “choice2” to 0 |
| [choice3 = 0] | Sets the variable “choice3” to 0 |
| [->WhatIsStrange] | Jumps to the block named “WhatIsStrange” |
| :: WhatIsStrange | Defines a new block labeled “WhatIsStrange” |
| [Rebecca] | Triggers the “Rebecca” action |
| What do you think is strange about this scene? | Text for this block. |
| [[The couple.|Couple]] | Creates a choice option that jumps to the “Couple” block if selected |
| [[The poison.|Poison]] | A choice that jumps to “Poison” |
| [[The location.|Location]] | A choice that jumps to “Location” |
| :: Couple | Begins the block labeled “Couple” |
| [Rebecca - Sad] | Triggers the “Rebecca - Sad” action, which sets her appearance to a sad expression. |
| We’ve been assuming it’s a love suicide because of the way that the boides are found, but isn’t it strange that nobody has ever seen these two together before? None of their friends knew that either was in a serious relationship. It seems like if you love somebody so much you’d kill yourself for them, you’d probably talk to your friends or family first. <p>Definitely strange. | |
| [choice1 = 1] | Changes the variable “choice1” to 1 to indicate that the “Couple” choice has been seen by the player |
| [choice1 + choice2 + choice3 < 3->WhatIsStrange] | If the sum of variables “choice1”, “choice2”, and “choice3” is less than 3, jump back to “WhatIsStrange” |
| [->MoveOn] | Otherwise, jump to “MoveOn” |
| :: Poison | The “Poison” block |
| [Rebecca - Shocked] | Triggers the “Rebecca - Shocked” action |
| I guess it’s pretty easy to get cyanide. But police didn’t find any fingerprints on the bottle, which seems weird. Almost like it had been wiped clean. | |
| [choice2 = 1] | Sets “choice2” to 1 |
| [choice1 + choice2 + choice3 < 3->WhatIsStrange] | If the sum of variables “choice1”, “choice2”, and “choice3” is less than 3, jump back to “WhatIsStrange” |
| [->MoveOn] | Otherwise, jump to “MoveOn” |
| :: Location | The “Location” block |
| [Scary Pan] | Triggers the “Scary Pan” action. Pans the camera across the landscape and applies a scary visual effect |
| You know, this beach is kind of nice during the day, but I think it would be windy and cold at night. It’s just a little inlet, you can’t even see the ocean. It seems like an exceptionally lonely place. Why would a couple choose to die here? | |
| [choice3 = 1] | Sets “choice3” to 1 |
| [Reset Scene] | Begins a new, unlabeled block that happens immediately after “Location” is finished. Triggers the “Reset Scene” action, which moves the camera back to its normal location. |
| [choice1 + choice2 + choice3 < 3->WhatIsStrange] | If the sum of variables “choice1”, “choice2”, and “choice3” is less than 3, jump back to “WhatIsStrange” |
| [->MoveOn] | Otherwise, jump to “MoveOn” |
| :: MoveOn | Begins the block labeled “MoveOn” |
| OK, let’s move on to the next question. If this really is a murder, who would want these two dead? |