Difference between revisions of "Dialog editor"

From Divinity Engine Wiki
Jump to: navigation, search
(Finished "controlling dialog flow" section)
(Finished converting the internal dialog editor wiki page)
Line 905: Line 905:
  
 
If the data type of the _Value that you're passing doesn't match the data type of the variable you will get an assert and no value will be stored.
 
If the data type of the _Value that you're passing doesn't match the data type of the variable you will get an assert and no value will be stored.
 +
 +
 +
= Searching Through Dialogues =
 +
 +
== Searching in an individual Dialogue ==
 +
The Dialogue Editor comes with a powerful Find tool that you can use to find back several pieces of information. You can access it from the ''Edit'' menu in the editor or by pressing the '''ctrl-f''' key combination.
 +
<br/>
 +
[[File:DialogFindMenu.png]]
 +
 +
When you open the Find window, you'll get an interface similar to the [[#Looking_for_a_specific_Speaker|Speaker Find]] option:
 +
<br/>
 +
[[File:DialogSearch.png]]
 +
 +
Type what you're looking for into the '''Search for''' textbox. Clicking the '''Find''' button to start looking through the current Dialogue. The Dialogue Editor will then look for the text in the locations you specified in [[#Search_Locations|Search Locations]] using the options you specified in [[#Search_Options|Search Options]]. The results and the number of results will be displayed at the bottom of the Find window. Double clicking a result line will select and center the Dialoge Editor on the Dialog Node where the result was found.
 +
 +
=== Search Locations ===
 +
The Search Locations determine where the Dialogue Editor will look for your search string. You can specify multiple locations at the same time.
 +
 +
==== Logical Name ====
 +
Look in the Logical Name property of the Dialogue Nodes.
 +
 +
==== UUID ====
 +
The UUID is the unique identifier of a Dialogue Node. Every Node comes with one and no two nodes will share the same UUID. The game will report any potential errors in Dialogue structure using this UUID.
 +
 +
==== Text ====
 +
Look in the text assigned to nodes
 +
 +
==== Flags ====
 +
Look in the Flags that are being Set and Checked on the Dialogue Nodes.
 +
 +
==== Tags ====
 +
Look at the Tags being checked and set on Dialogue Nodes as well as the Tags being checked in the Text Blocks of Dialogue Nodes.
 +
 +
=== Search Options ===
 +
These can be used to refine your search results.
 +
 +
==== Match Case ====
 +
Only returns results that have the same case as the search string.
 +
 +
== Searching through files ==
 +
To search in files, you can open the 'Find in files' window through the edit menu (Edit > Find in files) or by pressing the '''ctrl-shift-f''' key combination. All search locations and options available in the 'Find Dialog Nodes' are available in the 'Find in Files' form as well.
 +
<br/>
 +
[[File:FindInFiles.png]]
 +
 +
Before you start searching, define the folder in which you want to search. If you want to search in subfolders of that folder as well, check the 'Search in subfolders'.
 +
 +
= Testing Dialogues =
 +
To test a dialogue, open the dialogue in the dialogue editor and click the 'Play' button. This will open the 'Play window'. This will simulate the dialogue in game. It is possible to open the player without loading a level, however, dialogplayers, voices... can be more specific when a level is loaded.
 +
<br/>
 +
[[File:PlayWindow.png]]
 +
 +
To start, click the 'Play' button. The start node is chosen and the possible options are shown in the 'dialogue' tab. To review the history of the dialogue, click the 'History' tab.
 +
 +
== Advanced play ==
 +
You can start playing your dialogs in the editor with certain dialog flags already set. This could be helpful to check what dialogs look like after completing a quest for an NPC, for a specific player eg.
 +
 +
In this window you can select a set of dialog flags and tags to set on the speakers.
 +
 +
To do so, open the 'Advanced play' (File > Play advanced). This option is not available when the dialog player is playing.
 +
<br/>
 +
[[File:AdvancedPlay.png]]
 +
 +
On the left, you can see a list of available sets. The flags and tags set in the selected set are visible at the right.
 +
To create a new set, click the Create button. This will open the 'Create Flag set' window.
 +
<br/>
 +
[[File:CreateFlagSetWindow.png]]
 +
 +
Flags can be assigned to the left by double clicking on the flag or using the up and down arrows to move a flag from 'Available flags' to 'Assigned flags'. This way, you can make a node valid when playing the dialog in the dialog player.
 +
 +
The following node for example checks if the speaker 'Magister' doesn't have the Character flag 'TUT_ShakeCamera' and has the Character flag 'TUT_CollaringPriest_Kill'. By setting those flags in the 'Create Flag set' window, that node becomes a valid node.
 +
<br/>
 +
[[File:FlagsToCheck.png]]
 +
 +
You can do the same for tags. Following text is only chosen when speaker 2 has the tag 'RED PRINCE'. By assigning the tag 'RED PRINCE' in the 'Create flag set' window, this text will be valid when playing the dialog in the dialogplayer.
 +
<br/>
 +
[[File:TaggedText.png]]
 +
 +
= Templates =
 +
 +
== Using a template ==
 +
If a certain combination of nodes is used multiple times, you can convert it to a template. A new dialog can be created from a template (File > New > From Template), but you can add a template to an existing dialog as well (''right-click in the grey area'' > Insert Template...).
 +
<br/>
 +
[[File:InsertTemplate.png]]
 +
 +
A template can have different parameters. Before inserting the template, you need to fill in a value for each parameter. Those parameters can be custom flags (see [[#Adding_Flag_checks|Adding Flag checks]]) or tags.
 +
 +
== Creating a template ==
 +
To create a template, create a dialog as described previously. Save it as a template (File > Save > Save as template). Select all flags and tags that you want to turn into parameters and give those a proper name.
 +
<br/>
 +
[[File:CreateDialogTemplate.png]]
 +
 +
Provide a template name and path. If you don't want the text of the nodes to be exported as well, uncheck the 'Export Text' checkbox.
 +
<br/>
 +
[[File:CreateDialogTemplate2.png]]

Revision as of 14:34, 22 October 2017

Contents

Introduction

The Dialogue Designer is a visual tool for creating dialogues in our Divinity games. The tool is easy to use for writers and scripters alike and it is independent of the game we're working on.

Creating Dialogues

The Dialogue Designer can be found in the toolbar of our game editor. Look for the speech bubble.

Click that icon to open an instance of the Dialogue Designer. Every time you click on that icon, you will open a new dialogue editor instance. You will be presented with an empty dialogue when the editor starts:
Dialog Empty.png

New Dialogues

From the File menu you can create a new empty dialogue (replaces the currently open dialogue, if any, with an empty one) or a dialogue from a template. For more about Templates see #Templates.

Copying Dialogues

If you want to create a new dialogue based on an existing dialogue, don't just copy the files! This will cause problems with voice recording. If you want to copy an existing dialogue you can either:

  1. Open up the existing dialogue and use the "save as" function in the File menu to save a new dialogue with the name of your choice. You will then be working in the copied version of the dialogue.
    OR
  2. Open up two instances of the Dialogue Editor. Open your source dialogue in the first instance and Copy the nodes. Then go to the second Dialogue Editor Instance and paste the nodes. For more about copying nodes see #Copying_Nodes.

Dialog Categories

Different kinds of dialogs serve different purposes. You can select the dialog category using the pop-up menu on the top-right of the dialog window.

Generic NPC Dialog

This is an interactive dialog with player interaction. It can contain any kind of dialog node. Generally it should include at least one player, as NPCs by themselves cannot progress through such a dialog (unless the dialog only contains Greeting and Answer nodes, and all node transitions are timed; even then all you will see is a text balloon over the speakers' heads and the only way players can know what they are saying is by clicking on them while they are in the conversation — this could still result in fun "listen in" gameplay mechanics though!).

Starting such a dialog shows the dialog interface for all involved players (if any), which they can use to click through the dialog and select their reactions where allowed. Players cannot exit an interactive dialog, except through Leave nodes.

Automated NPC Dialog

This is a non-interactive/automated dialog. An automated dialog can only include Greeting and Answer nodes. The default node transition mode will show each node a certain amount of time based on its length. An automated dialog can have any combination/absence of NPCs and players.

Starting such a dialog shows the text of the dialog above the speakers' heads. Nobody is pulled into a modal interface like with the Generic NPC Dialog.

You must also check the Automated checkbox in this case.

Repeated Automated NPC Dialog

This is exactly the same as an Automated NPC Dialog, except that it gives a hint to the sound subsystem that this AD is repeated from time to time. It is used for ADs by sellers on market squares and the likes. The effect is that the voice recordings are played at a lower volume, and only a maximum number of times per minute.

If your dialog is not recorded, it will behave the same as a regular Automated NPC Dialog.

You must also check the Automated checkbox in this case.

PVP Dialog

Reflection Dialog

Voice bark

Ghost Dialog

This is the same as Generic NPC Dialog, except that the main NPC speaker is a ghost. This was added in order to give a hint to the sound subsystem that it should apply a "ghostly ambience" filter to ghost text. However, since dialogs can include both ghosts and non-ghosts, you need to process this per speaker rather than per dialog and hence this setting has no effect.

Ghost Automated Dialog

The same as a regular Automated NPC Dialog, with the same remarks as for ghost dialogs.

You must also check the Automated checkbox in this case.

Repeated Ghost Automated Dialog

The same as a regular Repeated Automated NPC Dialog, with the same remarks as for ghost dialogs.

You must also check the Automated checkbox in this case.

Gameplay Automated Dialog

You must also check the Automated checkbox in this case.

Companion Dialog

This is the same as a Generic NPC Dialog, but it treats tag checks for the origin companions (IFAN, BEAST, ...) the same as their shapeshifted versions (SHAPESHIFT_IFAN, SHAPESHIFT_BEAST, ...).

Automated

This checkbox must be checked for all automated dialogs. It is what actually determines whether a dialog is started in interactive or non-interactive mode. The difference between the automated and non-automated categories above are used by different systems (mainly sound).

Nodes

The Dialogue Designer represents the logical structure of a dialogue with a node tree. A node is a logical block of text said by an actor in the dialogue. Everything an NPC or a player can say (or ask), is represented by such a node. Nodes form a tree by connecting to other nodes. These connections denote the flow of the dialogue. For example, if you want an NPC A to say something and another NPC B to reply to that, you have to make a node for NPC A and connect another node for NPC B to that. Nodes can be connected to multiple other nodes, but more about that later.

Adding Nodes

In your dialogue window, right click the grey area to get the node popup menu:
Dialog Nodemenu.png

From this menu you can select which type of node you want to add to your dialogue. You'll notice that some of them are greyed out in this pictures. That's because not all node types can be added independently. Some node types require a parent node, before they can be added.

Connecting Nodes

In the previous section we saw that some nodes need a parent node before they can be added to your dialogue. That's the case for most node types found in a dialogue. The Greeting node is an example of a node that doesn't need a parent, since it's the node where the dialogue will start execution. They form the roots of the dialogue tree and the rest of the dialogue flows from them.

Let's create a greeting node, by selecting “Greeting” from the node popup menu:
Dialog Greeting.png

You'll see a green box appear in the main panel of your dialogue designer. Every node is represented as a little box like that, each with a unique colour, Notice the little circle at the top right of the greeting node? That's a connector. This is where other nodes will connect to this greeting node. The greeting node only has a single connector (to the right), because it does not accept parent nodes. You can only attach nodes to it, you can't attach a greeting node to another node since it has no connector on the left.

Now lets add an Answer node to this greeting node. Answer nodes are plain text nodes, usually put in dialogues as answers to questions made by a player (hence the name). You can't have an answer without a preceding question or another text node of some kind, That just wouldn't make sense. That's why Answers require a parent node and that explains why they were greyed out when we first opened up the node popup menu.

To add an answer node, we first select the greeting node, by left clicking on it. You'll notice the colour will change to a lighter shade of green. Now you right click to open the node popup menu:
Dialog Connect.png

You'll notice the previously greyed out options are now available to click. All those greyed out node types require a parent node before they can be used in a dialogue. Now select “Answer” from the menu. You'll see an Answer node appear next to your Greeting node:
Dialog Connected.png

Notice the line between the two nodes. That's a node connection. It extends from one node connector to another node connector. The Answer node has a node connector on its right side, That means you can attach other nodes to it. It also has a node connector on the left, which means it accepts incoming connections from other nodes.

There is no limit on the number of node connections you can have. A single Greeting node can have multiple nodes attached to it. Just as a single Answer node can have multiple nodes as parents.

Inserting Nodes

Some times you want to add a node in between a parent and its children. Instead of adding a new node to the parent and then manually connecting (and disconnecting) the parent's child nodes, you can use the node popup menu's “Insert Node” function.

To insert a node, select the parent node and right click it. Then from the node popup menu open the “Insert Node” sub menu and select your desired node type from the list. This list only contains nodes that can be inserted in between 2 nodes. That is, it only contains nodes that accept parents and children. Selecting Nodes

If you want to move a node, remove it or change its properties you have to first select it. You can select more than one node, though you can't change node properties if you have more than 1 node selected. The dialogue editor offers several ways to select nodes:

  1. Select a single node by left-clicking it with the mouse.
  2. Add or remove from your node selection by holding the CTRL key and left-clicking another node. If the new node was not selected it gets added to the current node selection. If the new node was already selected it will be removed from the current selection.
  3. You can marquee select a (group of) nodes by left-clicking in empty space and dragging over the node(s) you want to select. You'll see a rectangular region extend from where you clicked and following the mouse cursor. When you let go of the left mouse button, any nodes contained in the selection rectangle will be selected.
  4. Select a node and all of its children by holding the ALT key and left-clicking a node.

Copying Nodes

You can copy and paste nodes into your dialogues.

To copy dialog nodes, select the nodes you want to copy and press the CTRL + C key combination on your keyboard. The dialog nodes are now put on the clipboard and can be pasted in either the current dialogue or another instance of the dialogue editor.

To paste your copied dialog nodes, simply go to the destination dialogue editor window and press the CTRL + V key combination on your keyboard. If the pasted nodes had parent and/or child nodes and those nodes are present in the destination dialogue editor, the newly pasted nodes will be connected to those too.

Removing Nodes

Remove nodes from the dialogue by selecting them and pressing the DELETE key.

Moving Nodes

To move nodes to a new location in the dialogue tree, select them first. Then left click and drag one of the selected nodes. The group of selected nodes will now follow the mouse cursor as you drag it around. Let go of the left mouse button to place the nodes on the new location. When you drop the nodes, they will snap to a location. You can show the grid by checking the 'Show grid' option in the 'View' menu.

Collapsing Nodes

You can collapse dialog Nodes in the editor by double-clicking their title bar. That is the top part of a Node where the Logical Name is shown:
Dialog TitleBar.png

A collapsed Node only displays the Logical Name and not its contents:
Dialog Collapsed.png

Changing Node Properties

Every node type has a number of properties that can be changed from the node properties side bar:
Dialog NodeProperties.png

You can only edit the properties of one node at a time. So if you have multiple nodes selected you can not change their properties. Not every node type offers the same node properties. A more in-depth discussion is provided in #Node Properties and Node Types.

To copy and paste properties from one node to another, you can right click the property and choose for 'Copy'. If you want a textual representation of a property (eg. for documentation), you can choose 'Copy display string to clipboard'.

You can drag the Node Properties window to dock it somewhere else or move it to a second screen for easier editing.

Navigating the Dialogue Tree

As your dialogue grows not all nodes will fit on the screen anymore. When your view doesn't contain all the nodes in the dialogue tree anymore, the dialogue editor will show scrollbars to indicate where there's more nodes outside of the current view. Drag the scrollbars to pan the view. You can also right-click or middle-click the mouse and drag to move the dialogue view in a desired direction.

If you want an overview of the dialogue tree, you can zoom the dialogue view by scrolling the mouse-wheel.

If you want to center the view on a node, select the node and hit the HOME key on your keyboard.

Speakers

Every dialogue is written for a certain set of characters. These characters are the actors of the dialogue. Every dialogue keeps these actors in a list, called the Speakers. They indicate who says what in the dialogue. This Speaker list has a certain order. For example, say we have a dialogue between Bill and Ted. Bill would be speaker 1 (and be in the first slot) and Ted would be speaker 2 (and be in the second slot). Nodes refers to these slot to see who's saying the text contained in.

In our dialogues players will always be the last Speakers in the list. That's because we can have dialogues where depending on the situation more than 1 player can be active in a dialogue. Since we don't want to disrupt the order of the other Speakers, we add players in the back.\

For Question nodes, the Speaker of the node also determines who has to select the question.

Editing Speakers

At the top right of the Dialogue Designer window you can find the Speaker Editor:
Dialog Speakers.png

Click the Edit button to open up the Speaker Editor. The Speaker Editor will open and show the current Speakers assigned to the slots (if any):
Dialog SpeakerEditor.png

Click the Add button to add a Speaker Slot to the current dialogue:
Dialog SpeakerAdd.png

The slot with the grey background is the currently selected item. This is important if you want to change the order of the slots with the Move Up and Move Down buttons.

To select a Speaker Slot, just click it with the left mouse button.

The Delete button removes the currently selected slot from the list. When the removed slot is still used in the dialog, a messagebox will pop up asking you if you want to replace the speaker by another speaker. All occurrences of the removed speaker (in flags, speaker, animations...) will then be replaced by the selected speaker.

Click the Edit button next to a slot to start assigning Speakers to that slot:
Dialog AssignSpeaker.png

You'll see 2 lists. All the available Speakers in the game and the active Speakers in the selected slot. A slot can have more than 1 speaker assigned to it. This is because some dialogues can be said by several NPCs (think flavour automated dialogues).

To assign a Speaker to the current slot you have to move Speakers from the Available list to the Active List. You can do this in two ways:

  • Double-click a Speaker from the Available Speakers list
  • Select one or more Speakers from the Available Speakers list and click the > button. Use the CTRL key on your keyboard to add or remove Speakers to your selection.

To remove Speakers from the current slot, you have to move them from the Active list to the Available Speakers list. You can do this in two ways:

  • Double-click a Speaker from the Active Speakers list
  • Select one or more Speakers from the Active Speakers list and hit the < button. Use the CTRL key on your keyboard to add or remove Speakers to your selection.

You can use the Filter textbox to search for speakers in the list of Available Speakers.

Once you're done, click the OK button and you'll see your Speakers show up in your selected slot.
Dialog SpeakersAssigned.png

Click the OK button in the Speaker Editor to close it and keep your changes. The Cancel button will close the Speaker Editor without saving your changes.

Once you're done assigning Speakers to your slots, they'll show up in the drop down list in the upper right:
Dialog Speakerdrop.png

The Narrator Speaker

Sometimes you want a node to be spoken by a narrator instead of any of the Speakers inside the dialogue. To handle that case there's a special Narrator Speaker provided. This Speaker can not be found in the Speaker List of the Dialogue and needs to be assigned manually to the Nodes you want to be said by the Narrator:
Narrator.png

For more info on Assigning Speakers see #Assigning Speakers to Nodes.

NOTE: this Speaker is not available for every node type. This is because it simply doesn't make sense for all nodes to have support for this. At the moment only Greeting and Answer nodes support the Narrator Speaker.

The Narrator Speaker is there for voice recording reasons and as such can not be used to set or check Flags and/or Tags on!

Assigning Speakers to Nodes

Not all nodes have a Speaker, only nodes that have text inside of them need one. In our case these are the Greeting, Answer and Question nodes. To assign a Speaker to them, select the node and in the properties panel look for the Speaker property:
Speakers.png

Selecting the Speaker property in the grid will show a button that opens up a dropdown list with the current Speakers. Select the speaker from the dropdown list to assign it to that Node.
Dialog SpeakerNodeDropdown.png

By default, Answer and Greeting nodes will select the first Speaker slot as their Speaker. Questions default to the last Speaker Slot. This is in keeping with the fact that players will be added to the back of the Speaker list.

Addressed To Property

This property indicates who the Speaker of the node is talking to. This is an optional property. If nothing is filled in, the game will select a default value. At the moment this property is only used for localization purposes.

Speaker Groups

We've already mentioned that a Speaker Slot can contain more than 1 speaker. This is to support generic dialogues that can be said by more than 1 character. For example a generic "Hello" dialogue that's assigned to several citizens in a town. You would then have to assign every citizen as a Speaker in that "Hello" dialogue. Some times you don't know beforehand who's going to be able to say something or the list of speakers is just too long to manually assign them all. That's why the dialogue editor also supports Speaker Groups. Speaker Groups simply group a number of Speakers together so that you can assigned the group to a Speaker Slot instead of each speaker individually.

Creating Speaker Groups

Creation and editing of Speaker Groups is done through the Speaker group Editor. This is a tool that's found in the Tools menu of the dialogue editor:
Dialog ToolsSpeakerGroups.png

Click it and the Speaker Group Editor will open.
SpeakerGroupEditorEmpty.png

The Speaker Group Editor will scan the game for all characters and items to see in which groups they are. That way you can see exactly which characters are in which groups or in no groups at all. While it's looking through the characters, you'll see the icon animate in the top right:
Dialog SpeakerRefreshing.png

While it's refreshing the Speaker list you are free to edit Speaker Groups.

  • To add a Speaker Group click the Add button. This will create a new Group with a default name. You can change the name in the Speaker Group properties.
  • To remove a Speaker Group, select a Group from the list and click the Remove button.
  • Filtering is possible for a part of the name or the full uuid.

Speaker Group Properties

When you select a Speaker Group from the list the right part of the editor will display an overview of that Speaker Group:
SpeakerGroupEditor.png

This overview shows which Speakers are assigned to the Group, along with a number of properties of the group.

UUID 
Each Speaker Group has a unique identifier. This is used by the game so you don't have to update the Speaker Groups for your characters or items if you decide to rename a group. This is automatically generated for oyu and can not be modified.
Name 
This is a logical name for your Speaker Group. This is the name that will be shown in the Speaker list in the dialogue editor. As a convention we start Speaker Groups with the "GROUP_" prefix.
Description 
This is a text field that contains a description for this Speaker Group. Can be useful for voice recording purposes.
Mod 
This property shows in which game module this Group was defined. Groups that are unique to a certain game should be created in that game's module. Groups that are shared between games should be created in the Shared module.
Overwrite speaker 
If an override speaker is defined for a group, the speaker of that character will be used for the voice data. The uuid of the character should be filled in here. An override speaker is a speaker that will be used to voice all characters in this group when this group is assigned as speaker in a dialogue node (e.g. the God King voices most voidwoken in the main campaign).

Looking for a specific Speaker

The Speaker Group Editor also provides you with an option to look for a certain Speaker. You can do this by pressing the CTRL-F key combination on your keyboard or by selecting the find option from the Edit menu:
Dialog SpeakerFind.png The Find Speaker window will pop up:
Dialog SpeakerSearch.png Enter text to search for in the Search For text box. The checkboxes in Search Locations determines where the editor will look for the text:

Name 
The editor looks in the name of the Speaker for a match
UUID 
The editor looks in the unique identifier of the Speaker for a match

You can select both locations to search in both the UUID and the Name of Speakers. If you tick the Match Case check box, only Speakers are returned if they contain the text with a matching case.

The results are displayed at the bottom of the screen. It contains 3 columns:

Name 
Name of the Speaker
UUID 
Unique identifier of the Speaker
Groups 
All the Speaker Groups this Speaker is assigned to
Warningred.png
The editor only looks through the Speakers it has found so far. This means that he might not return all Speakers if the Refreshing icon is still animating!

Assigning Speakers to Speaker Groups

Speaker Groups are assigned on the individual characters and items themselves. They can belong to more than 1 Speaker Group. To assign a Speaker Group to a character or item, select it in the editor and open up the proeprties panel (CTRL-B by default).

Look for the Speaker Group property in the properties pane of the object:
Dialog CharacterProperties.png

Select the property and click the button to open up the Speaker Group Assignment Editor:
Dialog SpeakerGroupAssign.png

The available Speaker Groups are in the Available groups list. The currently assigned Speaker Groups are in the Assigned Speaker Groups list.

The Speaker Group Assignment Editor also lists the Speaker Groups that were set on the Root Template for this object.

To assign this object to certain Speaker Groups, you have to select groups and put them in the 'Assigned Speaker Groups list. There are two ways to do this:

  • Double-click a Group from the Available groups list
  • Select a Group from the Available groups list and click the Assign button.

To remove this Object from a certain Speaker Group, you have to remove the Group from the Assigned Speaker Groups list. There's 2 ways to do this:

  • Double-click a Group in the Assigned Speaker Groups list
  • Select a Group in the Assigned Speaker Groups list and click the Remove button.

Click the OK button to apply your changes and close the Speaker Group Assignment Editor. Click the Cancel button to close the Speaker Group Assignment Editor without applying your changes.

Adding Text to Nodes

To add text to a node or edit the existing text, double click on the node. This will open the 'Edit Tagged Texts' window.
EditText.png

To add a tagged text, click the add button. This will add a new Tagged text form. The text for the node can be entered in the textbox.
EditText2.PNG

A tagged text can have multiple text blocks. To add a new text block, click the Add button. This will add an extra textbox. To remove one, click the X button. One of the text blocks will be randomly chosen when the dialog plays.
EditText3.PNG To personalize the text, you can add multiple Tagged Text forms and define rules on which one to choose while playing the dialog. This way, you can show a different text depending on whether the players are dwarves or elves.
Edit Text4.png

The tagged texts are checked in the given order (see numbers on top, left to right, top to bottom). The first one that meets the conditions, is chosen. The first text block will be shown in the dialog node in the editor.

Defining Rules

A rule will check if all/any/none... members of the speakergroup or a single speaker have/has the given tag(s). To add a rule, click the + button, to remove one, click the - button.

Show this when All/Any of the following rules are valid

When choosing All, all of the conditions needs to be met before that tagged text is chosen. When choosing Any, only one condition needs to be met. It doesn't matter which one.

Conditions

There are 5 options:

Has all 
will check if all members of the specified group have the given tag.
Has any 
will check if there is at least one member in the group who has the given tag.
Has none 
will check if there are no members in the group with the given tag.
And all 
will make a subgroup of rules. All rules in the subgroup should be met.
And any 
will make a subgroup of rules. Only one of the rules in the subgroup has to be met.

Speaker

Choose a speaker or speaker group on which the rule should be checked.

Tags

By clicking on the '...' button, the Add Tags window can be opened in which you can choose multiple tags.
AddTags.png

On the Available Tags tab, you can see all the possible tags that can be chosen. The Current Tags tab shows all the tags that are used in the current node's tagged text block checks. The filter can be used to search for specific tags.

Example

RulesComplicated.png

In the above example, we have two subgroups: 2 and 2c. 2c is a subgroup in subgroup 2.

The tagged text for this set of rules will be selected when:

  • 1 and 2 are met (because of Show this when ALL of the following rules are valid.
  • 2 is met when any rule in 2 is met (because of the And Any of the following rules). So when 2a, 2b OR 2c is met.
  • 2c is met when all of the rules in 2c are met (because of the And All of the following rules). So when 2c' AND 2c'' are met.

Node Properties and Node Types

In this section we'll cover the Node properties in detail. Not all Node Types will have the same properties, but all Text Nodes (nodes that display text in the dialogue) shared a set of common properties. We'll look at those first.

Base Text Node Properties

Greeting, Answer and Question nodes are all Text Nodes. As such they all share a number of properties:
NodeProperties2.png

Addressed To

In some languages, a sentence being said to a man is different than the same sentence being said to a woman.

English: You are beautiful

French: Tu es beau (to a man) vs Tu es belle (to a woman)

To be able to choose the right version, we need to know to whom the sentence is addressed. This information is stored in the Addressed To property.

If no Addressed To speaker is specified, it will be addressed to the first speaker (that is not the Speaker of the node). If a Look At value is set for this node, the speaker of that property is taken.

EndNode

Checking this checkbox (and thus setting it to True), means that the dialogue will stop executing after this node has been shown. You'll see that the Node turns red to indicate it is an End Node now. You also can't connect nodes to an End Node.
Dialog EndNode.png

Exclusive

Normally a dialog selects a node to display out of the list of valid nodes at the point of execution. Out of all those valid nodes it selects a random node. When the dialog encounters one or more valid Exclusive nodes in that list, it stops considering all non-exclusive nodes. This means that the dialog will select a random node from the group of valid Exclusive nodes. This can be used to alter the flow of a dialog in case a certain condition is set and the dialog shouldn't take the normal path. For more info check [[#Controlling Dialogue Flow|]].

Logical Name

This is a human-readable name that's useful to provide context for a dialog node. Can be useful for making the use of a node clear and for voice recordings. The logical name is displayed at the top of a node in the dialog overview.

Optional

Optional nodes function as normal nodes unless the dialog doesn't encounter any valid nodes when looking for a node to show. If the dialog doesn't encounter any valid nodes, but it has a list of optional nodes, it'll select a random node out of the optional nodes and skip it. The selected optional Node will not be shown then, but the dialog will progress as if that Node was shown. Note that the nodes are skipped, that means none of the actions of the nodes are performed (so no flags are set). For more info see #Controlling Dialogue Flow.

Shown Once

When Shown Once is checked the node will only be shown once during a dialog instance. The node will be shown again when the dialog starts again.

Speaker

Who says the text in this Node? For Question Nodes this also decides who has to click the question. Clicking this property allows you to chose a value from a dropdown list containing all the Speaker Slots defined in this dialogue.

Stub

Indicates that this node is a work in progress (not used in practice).

Tags

The tags property can be used to assign multiple tags to a dialog node. The SFX_ONLY tag can be used on dialog nodes that don't need to be voiced.

Texts in this Node

List of all the texts contained in this node. More about the texts and how to create them in #Adding Text to Nodes.

UUID

Unique identifier of this node. This is generated for you and can't be changed.

Transition Mode

Indicates how the dialog progresses when it encounters this Node. It has 2 possible settings.

Wait for input

This is the default setting. The dialog will display the node and then wait for a user to click continue (or end in the case of an End Node)

Wait X seconds

The dialog will show the node and then wait X seconds before it shows the next node in the dialogue tree. X is a number that you can fill in when you select this transition mode:
Dialog TransitionMode.png

Flags to Check

Which flags is this Node checking? More about flags in #Controlling Dialogue Flow.

Flags to Set

Which flags is this Node setting? More about Flags in #Controlling Dialogue Flow and #Flags to Set property.

Node Context

What's the context for this Node? Use this to clarify a Node or for voice recording purposes, or as comments for yourself or others about this node (never shown to players).

Text Nodes

Greeting

Dialog Greeting.png

These nodes indicate where a dialogue starts executing. They form the roots of the dialogue tree.

Question

Question.png

These Nodes are used to ask questions to other Speakers in the dialogue. When a dialogue encounters these nodes it'll present a list with all valid Question nodes to the Speaker that owns the Nodes.

Warningred.png
You cannot have a mix of valid Answer Nodes and Question Nodes as children of a single Node. When that happens the game will warn you and ignore the Answer Nodes.

Answer

Dialog Answer.png

These nodes are simple text entries. Most commonly used as replies to player Questions.

Logic Nodes

The Nodes in this section do not contain any text themselves and only exist to change the flow or to simplify the structure of a dialogue. As a result these Nodes do not have the base Text Node properties, but have their own (small) set of properties.

Jump Nodes

Jump Nodes are Nodes that reference other Nodes. They are a way to re-use nodes or as a means to keep dialogue structure cleaner by cutting down on the number of child connections needed. A Jump Node is constructed by pointing it to another node in the dialogue.

Properties
Jump To 
This indicates which Node(s) a Jump node references. This Property can have 2 values:
Start of Node 
This Jump node references the pointed to Node. This is as if the pointed to Node and its children are inserted at the point of the Jump Node.
Warningred.png
The pointed-to Node still needs to be valid before it can be shown (flag checks need to pass).
End of Node 
This Jump Node references the children of the pointed-to Node. This is as if the parent Node of this Jump Node has all children of the pointed-to Node connected to it.
Warningred.png
The pointed-to Node does not need to be valid. The children of the pointed-to Node are still validated though.
Target Node UUID 
The UUID of the Node this Jump Node is pointing to. You can not change this. To see which Node this is, double click the Jump Node and the editor will center the view and select the pointed-to Node.
UUID
The unique identifier of this Node. You can not change this.
Creating Jump Nodes
  1. Select a Node that accepts children and select Jump Node from the Node Context menu.
    Dialog JumpNode.png
  2. Your cursor will now change into a targetting cross.
  3. Select a node in the dialog to create a reference to that Node.
    Dialog JumpCreated.png

If you want to cancel the creation of a Jump Node, you can press the ESCAPE key.

Once your Node has been created you can set the Jump To-property to change which node(s) it references.

DOS specific Nodes

The Nodes in this section are not part of the Dialogue framework. they are Nodes that were created specifically for Divinity: Original Sin. These may or may not be available in other games.

Pop Nodes

Dialog Pop.png

Pop Nodes are Nodes that were introduced to support the old Keyword dialogues. They function much like a Jump Node that always points to the End of a Node.

Properties

Exclusive 
Functions the same as the Exclusive property of Text Nodes. See #Exclusive Property.
Pop Count 
How many levels the Node should go back. This a number that starts from 0. See #Pop Levels for more information.
UUID 
The unique identifier of this Node.

Pop Levels

Every time a list of Quesiton Nodes is presented, a pop level is created. This is a point in the dialogue that Pop Nodes can refer to, to present a list of Questions to the player.

The Pop Node then functions as a Jump Node that jumps back to the end of the Parent Node of the specified level of Question Nodes. To see how many levels to jump back to, you have to go back X+1 Question Nodes in the dialogue tree, starting from the Pop Node. X is the value you filled in for the Pop Count property. You can see which node a Pop Node it's targetting by double clicking the Pop Node. If the Pop Node can't Jump back to the specified pop level you'll get an error message in the editor when double clicking the Pop Node.

Dual Dialog Node

Dialog DualDialog.png

Dual Dialog Nodes are Nodes that pause the current dialogue and ask the Game Scripting to start a certain sub-dialog. These sub-dialogs are typically decission dialogues between 1 or more players. When the sub dialogue ends, the current dialogue resumes again.

Properties

Dual Dialog Name 
This is the name (without file extension) of the sub dialog to start. Double clicking the Dual Dialog content, tries to open or switch to a dialog editor for the pointed-to sub dialog.
Exclusive 
Functions the same as the Exclusive property of Text Nodes. See #Exclusive Property.
Logical Name 
Functions the same as the Logical Name property of Text Nodes. See #Logical Name Property.
Optional 
Functions the same as the Optional property of Text Nodes. See #Optional Property.
Shown Once 
Functions the same as the Shown Once property of Text Nodes. See #Shown Once Property.
UUID 
The unique identifier of this Node.

Persuasion Nodes

Game specific Node Properties

In addition to the built-in Node Properties, a game can also add custom properties to Nodes. These Properties are on the Advanced tab of the properties sidebar:
Dialog GameProperties.png

DOS Node Properties

Divinity Original Sin has a couple of Node options that are unique to this game. These are all applied to the Text Nodes (Greeting, Question, Answer).
GameNodeProperties.PNG

Sound

Sound Event 
This is the id of an additional sound that is started when the node is started (eg. evil music when an evil answer is chosen).
Instruments 
This is the id of a sound for a specific instrument. Depending on the instrument the player choose, the sound for the given instrument will be played. If there is a sound event set, the instrument sound will not be played.

Animation

Emotional Expression 
This determines which animation the Speaker of this Node will play. Can also be used as a hint to the voice actors. If an animation for the Speaker of this Node is set as well, the emotional expression will not be played.
Look At 
You can define per dialog Node what Speaker a certain Speaker needs to face when the Node starts. This is done by defining Look-At entries. You can add an entry by clicking the Add button. This will add an empty Look-At entry:
GameNodePropertiesAddLookat.png
Pressing the Add button again will add more empty Look-At entries to this node.
The two dropdown boxes control which Speaker looks at which Speaker. The first one is the NPC that's going to face a certain Speaker. The second one is the target Speaker. You can only select Speakers that :were assigned to this dialog!
You can delete a Look-At entry again by clicking the Delete button:
GameNodePropertiesDeleteLookat.png
To copy paste the look at property to another node in the dialog, click the 'Copy' button, select another node and click the 'Paste' buttons.
Animations 
For each speaker, an animation can be set that will be performed during that dialognode. To add an animation, click the add button.
GameNodePropertiesAddAnimation.png
Choose one of the speakers and fill in the name of an animation.
Copy-pasting and deleting an animation can be done the same way as for 'Look at'.
If an animation for the speaker of the selected node AND an 'Emotional expression' (which is also for the speaker of the selected node) is set, only the animation will be played.

Game

Camera Target 
The camera is, by default, following the speaker in a dialog. Choose another speaker from the list to target the camera on another player during the dialog node.
Extra node time 
If a node needs to be shown longer than normal, that extra time can be set in the Extra node time property. This time will be added to the default node time (based on the amount of words), the length of the voice data or the Wait time set for nodes with the Wait for x seconds node transition mode.

Controlling Dialogue Flow

All the Nodes in a dialogue form a tree by connecting with their parents and children. The game then walks through the dialogue tree to figure out which Nodes to show to players and when. It does this by starting at the roots of the tree, selecting a root to show and from that root working itself through the branches towards the leaves that are connected to it. The #Greeting Nodes form the roots of the tree, so this is where all dialogues will start. The leaves are the End Nodes in a dialogue, and this is where execution of a dialogue stops.

Node validation

When a dialogue starts, the game looks through all of the roots of that dialogue and validates them. Validating a node means checking all the conditions that are put on the Node. Only Nodes that pass this test are considered for display. The game performs a similar test for the non-root Nodes that are connected to a root: only the valid nodes are considered for display.

Validating a Node is a process that results in a boolean value. You can think of a boolean value as a truth value, something that is either true or false. So validating a node results in 2 possible truths: the node is either valid (true) or invalid (false).

Node Conditions

While a game can have custom validation requirements on a Node, most of the conditions are put on Nodes through the #Flags to check property of Nodes. A Flag is also a boolean value. It can either be set (true) or not set (false). By default, Flags start out as being not set and are thus considered to be false.

The Flags to Check property is a list of flags that need to have a certain value (set or not set) if a Node is to be considered valid. Each entry of this list compares the boolean value of the specified Flag with a desired boolean value. If the boolean value of the Flag matches the desired boolean value, the games considers that entry to be true. If the two boolean values don't match it considers that entry to be false. The games calculates if a Node is valid or not, by combining all of the boolean values of the entries of that list. We'll see how we can combine boolean values in the next section.

Boolean Logic

Boolean Logic describes how we can combine two boolean values to come up with a new boolean value that's the combination of the two input values. We call the way we combine the 2 input values an operator. It's something that operates on 2 input values to produce a new output value. There's several operators you can use to combine boolean values, but we'll stick to the ones used by the dialogue system in this section.

The AND operator

The AND operator is used to enforce that the two input values passed to it are true. If and only if the two input values are true will the AND-operator return true as well. As soon as one (or both) of the inputs are false it will return false as well.

To summarize:

  • true AND true gives us true
  • false AND true gives us false
  • true AND false gives us false
  • false AND false gives us false
The OR operator

The OR-operator is more lenient than the AND operator. It returns true as soon as any of the two input values is true. That means it will only return false if both input values are false too.

To summarize:

  • true OR true gives us true
  • false OR true gives us true
  • true OR false gives us true
  • false OR false gives us false
The NOT operator

The NOT operator simply returns the inverse of whatever you put into it. That means that NOT true will result in false. Similarly NOT false will result in true.

To summarize:

  • NOT true gives us false
  • NOT false gives us true

Validating a Node

Now that we know how to combine boolean values, we can look at how the game checks the #Flags to Check property of Node. Like we already mentioned, this property is a list of Flags that need to be set (true) or not set (false) before this Node is considered valid (and thus, considered for display). It compares the boolean values of the flags with the desired boolean value and considers an entry true if they match. If they don't match it considers the entry false. The game then combines all of these boolean values using the AND operator. This means that a Node is only valid if that list only contains true values. As soon as that list of entries contains a false, the node is considered invalid.

Adding Flag Checks

To add a Flag check to a Node, select the Flags to Check property of the Node in the properties sidebar and click the edit button:
Dialog AddNodeCheck.png

You'll get the Flag Editor screen:
Dialog FlagCategories.png

Select the Flag Category you want to add a Flag to from the Flag Categories list. You will then be presented with an overview of this Flag Category:
Dialog AddingFlags.png

The top list box shows all available Flags of the selected type. This is a list of all the Flags used in the whole dialogue or a list of all defined Tags (see #Tag Editor to define Tags) in the case of the Tags Flag type.

The bottom list box, the Active flags list box, shows the Flags that are active on the currently selected Node.

Type the name of the Flag you want to add in the Custom flag text field and click the Add button to add a new Flag. The new Flag will be automatically added to the Active flags list.

To remove a Flag from the currently selected Node, move the Flag from the Active flags list to the top list box. You can do this by double clicking the Flag in the Active flags list box or by selecting it in the Active flags list and clicking the up arrow button.

To add an already defined Flag to the currently selected Node move it from the top list box to the Active flags list. You can do this by double clicking the Flag in the top list or by selecting it in the top list and clicking the down arrow button.

Hit the OK button when you're done adding flags and apply your changes. Or hit the Cancel button to discard your changes and close the Flag Editor.

Practical Examples

Let's say we have a node that we want to show if a certain local flag (called localFlag) hasn't been set and if a certain global flag (called globalFlag) is set. More concrete this means that this node is valid if:

  • localFlag's value has to be false.
    AND
  • globalFlag's value has to be true.

This translates into the following Flags to Check property:
File:File:Dialog NodeChecks.png As you can see, a checked checkbox indicates that we want a desired value of true. An unchecked checkbox indicates that we want a desired value of false.

When validating this Node the game performs these steps:

  1. build a list of all Flag checks: we have 2. Checking if localFlag is not set and checking if globalFlag has been set.
  2. Compares the value of localFlag with the desired value of false and puts the result in a list.
  3. Compares the value of globalFlag with the desired value of true and puts the result in a list.
  4. Goes over the list created in step 2 and 3 and combines the boolean values with the AND operator

Let's see how this work with the concrete case where localFlag is not set and globalFlag is set:

  1. build a list of all Flag checks: we have 2. Checking if localFlag is not set and checking if globalFlag has been set.
  2. localFlag is not set, so has a value of false. This equals our desired value of false. So we put true in the list
  3. globalFlag is set, so has a value of true. This equals our desired value of true. So we put true in the list
  4. We go over the result list and combine our results with the AND operator:
  5. true AND true gives us true

We ended up with a result of true, so this Node is considered valid.

Let's change our Flags to Check property to the following:
Dialog NodeChecks2.png

And let's again use the case where localFlag is not set and globalFlag is set:

  1. build a list of all Flag checks: we have 2. Checking if localFlag is set and checking if globalFlag has not been set.
  2. localFlag is not set, so has a value of false. This does not equal our desired value of true. So we put false in the list
  3. globalFlag is set, so has a value of true. This does not equal our desired value of false. So we put false in the list
  4. We go over the result list and combine our results with the AND operator:
  5. false AND false gives us false

This means our Node is invalid.

Now let's look at an example with more than 2 entries in our check list:
Dialog NodeChecks3.png

Let's assume that localFlag is set, otherLocalFlag is set and globalFlag is not set:

  1. build a list of all Flag checks: we have 3. Checking if localFlag is set, checking of otherLocalFlag has not been set and checking if globalFlag has not been set.
  2. localFlag is set, so has a value of 'true'. This equals our desired value of 'true'. So we put 'true' in the list
  3. otherLocalFlag is set, so has a value of 'true'. This does not equals our desired value of 'false'. So we put 'false' in the list.
  4. globalFlag is not set, so has a value of 'false'. This equals our desired value of 'false'. So we put 'true' in the list
  5. We go over the result list and combine our results with the AND operator:
  6. 'true' AND 'false' AND 'true'
  7. We combine from left to right:
  8. ('true' AND 'false') AND 'true'
  9. which turns into:
  10. 'false' AND 'true'
  11. which gives us: 'false'

This Node is considered invalid for the flag values given in the example.

Visual Cue

When a Text Node is checking Flags a little square is shown on the left of the Node. Hovering over this squares shows which Flags are being checked by that Node:
Dialog FlagsToCheckHover.png

The pop-up shows the type of the Flag that's being set and what value it's being set to in brackets. A value of True means we're checking if the flag is set. A value of False means we're checking if the flag is not set.

Node Selection

So the dialogue now has a list of Nodes that can be potentially shown (either the roots of the dialogue or the branches and leaves flowing from those roots). It will then select a Node from this list to determine the next Node to show to players. It does this using the following process:

  1. Collect all nodes that should be considered for display. This is all Root Nodes when the dialogue starts or all children of the previously shown Node
  2. Validate all Nodes in this list:
    1. If an Optional Node and the Node is not valid: Keep in a list of Optional Nodes.
    2. If an Optional Node and the Node is valid: Keep in a list of Valid Nodes.
    3. if an Exclusive Node and the Node is valid: add to a list of Exclusive Nodes
    4. if a normal (not exclusive and not optional) Node and the Node is Valid: add to a list of Valid Nodes
  3. Now select a Node to show from our lists:
    1. if we have Nodes in our Exclusive Nodes list: select a random Node from this list.
    2. ELSE
    3. if we have Nodes in our Valid Nodes list: select a random Node from this list
    4. ELSE
    5. if we have Nodes in our Optional Nodes list: select a random Node from this list

After a Node has been selected for display, the game will execute the Actions attached to that Node.

Warningred.png
For Greeting' Nodes, the size of the Exclusive Nodes list is limited to 1. This effectively means that the game will pick the first valid Exclusive Greeting Node to use as a starting point of the dialog. This can be used to simplify starting conditions of your dialogs by separating specific flows using Exclusive Greeting Nodes place at the top of your dialog.

Node Actions

Some Nodes can have actions assigned to them that execute when the Node is selected for display. A game could add game specific actions to a Node, but the base Text Nodes (Greeting, Question, Answer) already come with a built-in action to set or un-set Flags.

Flags to Set property

Flags to Set is a property that indicates which flags to set or un-set when this Node is selected as the next Node in a dialogue.

Adding and Removing Flags to Set

It's very similar in function to the Flags To Check property:
Dialog FlagsToSet.png

Clicking the edit button when the property is selected will open up the same Flag Editor as seen in Adding Flag Checks.

Setting a Flag is done by checking the checkbox in front of the Flag's name.

Un-setting a Flag is done by unchecking the checkbox in front of the Flag's name.

Visual Cueu

When a Text Node is setting Flags a little square is shown on the right of the Node. Hovering over this squares shows which Flags are being set by that Node:
Dialog FlagsToSetHover.png

The pop-up shows the type of the Flag that's being set and what value it's being set to in brackets. A value of True means the flag is being set. A value of False means the flag is being un-set.

Types of Flags

There are several types of Flags available in the dialogue editor. Each type of Flag is handled differently, so it's important to know when to use a certain type of flag.

Local Flags

Local Flags are the simplest type of Flag and is the only built-in Flag type in the dialogue system. Local Flags are flags that can be set or unset and that are local to the context of the dialogue they're used in. That means that other dialogues or game scripts can not reference these Flags. The state of Local Flags is saved and is not reset between instances of dialogues. this means: if a dialogue sets a local flag, the next time you start the dialogue again the flag will still be set.

Important: Since those flags are local to a Dialogue, this means that if you assign a dialogue to multiple characters they all refer to the same Local Flags! If talking to one character sets a Local Flag, it will be set when talking to another character with the same dialogue!

Tag Flags

Tag flags check/set tags on speakers. Tags can also be checked/set from script, and can be statically assigned to characters and items using the sidebar.

Script Flags

Script flags can only be checked. There is a script coupled to each Script flag. The script itself can be found under Tools > Edit script flags. See the Script Flag Editor for more details.

Global Flags

Global Flags are simple Flags that can be accessed by scripts or other dialogues. They are not tied to any item, character or dialog.

Character Flags (DOS specific)

A Character Flag is a Flag that's tied to a specific character (or item). They are often used to indicate that a certain character knows or did something. They can be used in scripts and other dialogues.

Character Flags can be set and unset but they always take a Speaker as a parameter. The Flags will then be set and unset for the character that's currently in the specified Speaker Slot.

User Flags (DOS specific)

A User in DOS is a (human) player in the game. Every User controls a number of characters in the game. Similarly every playable character is assigned to a specific User. The User Flag is a shortcut for (un)setting a Character Flag on every character that's currently controlled by a specific User.

User Flags, like Character Flags, take a Speaker as a parameter. The User Flag will then take the User that controls the character in the specified Speaker Slot and set a Character Flag for every character currently controlled by that Speaker. Checking if a certain User Flag is set, means going over the User's characters and checking if any of them have the Character Flag set. To clarify: as soon as a single character has the Character Flag set, the User Flag will be considered set.

Party Flags (DOS specific)

A party in DOS consists out of several characters. Those characters can be assigned to different Users. A Party Flag is a shortcut for (un)setting a Character Flag on all characters in a certain party.

Party Flags also take a Speaker as parameter. The Party Flag will then take the party of the character in that Speaker Slot and (un)set the Character Flag on all characters currently belonging to that party. Checking if a Party Flag is set, means going over the party's characters and checking if any of them have the Character Flag set. To Clarify: as soon as a single character in the party has the Character Flag set the Party Flag will be considered set.

Script Flag Editor

Adding, changing or removing a script flag can be done in the 'Edit script flags' window (Tools > Edit script flags).
EditScriptFlags.png

A script flag has a uuid, a (unique) name, a description, the mod in which the script flag is defined and the filepath and the script itself. Script flags are saved in the dialogs folder under 'ScriptFlags'.

The script itself consists of different conditions and a check at the end to define which combination of conditions should be true. Only the conditions mentioned below are supported at this time.

Syntax

Script flags have the following syntax: 

CONDITION x
[
CONDITION y
CONDITION z
]
CHECK "<check string>"

Where the CONDITIONs between square brackets are a list of CONDITIONS. You can have as many conditions as you want, but you need at least 1. Each CONDITION will be a script call that takes a number of parameters and produces a value that's either true or false. The "check string" that is used in the CHECK statement then defines a way to combine all of these returned values and produce a single true or false value. This value will be the value of the Script Flag. So if your CHECK string produces a false the Script Flag will be considered not set. Any Dialog Node that then checks for this flag to be true will be considered not valid.

Let's look at the "check string" in a bit more detail. Every CONDITION you list in the Script section of a Script Flag gets a number. These numbers start from 1. So the first CONDITION will get 1, the second one gets 2 and so on. The "check string" refers to return values of CONDITIONs by using these numbers. The first CONDITION's return value, for example, is referred to as c1. The second CONDITION's return value is c2 and so on. All these return values are then combined following the Boolean Logic we outlined before. The Boolean operators supported by the Script Flags are:

  • | = OR
  • & = AND
  •  ! = NOT

So for example:

CHECK "c1&c2" Combine the return values of the first 2 CONDITIONs and combine them with the AND operator
CHECK "!c1&c2" Use the NOT operator on the result of the first CONDITION and combine it with the result of the second CONDITION using the AND operator
c2" Combine the return values of the first 2 CONDITIONS and combine them with the OR operator

The second example uses the NOT operator only on the first CONDITION's result. What if we wanted to apply the NOT operator on the result of combining the return values of the first 2 CONDITIONs? We can use parentheses to group certain CONDITIONs and apply operators to that whole group:

CHECK "c1&!(c2&c3)"

This "check string" will combine the result of the first CONDITION with the inverse of the combination of the second and third CONDITION (combined using the AND operator here). Using parentheses combined with the boolean operators available gives you a lot of flexibility in creating complex conditions for Dialog Nodes.

Available Conditions

IsGlobalFlag

CONDITION IsGlobalFlag(FlagName, Bool)

Check if global flag has certain value

IsLocalFlag

CONDITION IsLocalFlag(FlagName, Bool)

Check if local flag has certain value

IsSpeakerFlag

CONDITION IsSpeakerFlag(SpeakerIndex, FlagName, Bool)

Check if speaker's character flag has certain value. If that speaker is not present, the result will always be false.

IsUserFlag

CONDITION IsPartyFlag(SpeakerIndex, FlagName, Bool)

Check if speaker's user flag has certain value. If that speaker is not present, the result will always be false.

IsSpeakerPresent

CONDITION IsSpeakerPresent(SpeakerIndex, Bool)

Check if a character at that speaker index is present in the dialog. E.g., you can have a dialog with 3 speakers, but pass NULL as the third speaker when starting it. In this case, this test will return false for the third speaker.

IsMagicPocketsGold

CONDITION IsMagicPocketsGold(SpeakerIndex, CompareOp, CompareValue)

Check amount of gold in magic pockets (= per-user) for condition. CompareOp is one of <, >, <=, >=, ==. Can also be used on NPCs.

Warningred.png
CompareValue MUST be DialogVariable (starts with %).

HasItemTemplate

CONDITION HasItemTemplate(SpeakerIndex, Template, CompareOp, CompareValue)

Check amount items with specified root template in speaker's inventory for condition. CompareOp is one of <, >, <=, >=, ==. Can also be used on NPCs.

Warningred.png
CompareValue MUST be DialogVariable (starts with %).

HasItemTemplateInMagicPockets

CONDITION HasItemTemplateInMagicPockets(SpeakerIndex, Template, CompareOp, CompareValue, MoveAndReport)

Check amount of items with specified root template in magic pockets (= per-user) for condition. CompareOp is one of <, >, <=, >=, ==. If MoveAndReport is true, template items are moved from other characters to this speaker's inventory.

Warningred.png
CompareValue MUST be DialogVariable (starts with %).

HasTalent

CONDITION HasTalent(SpeakerIndex, TalentID)

Check speaker has talent. TalentID is string.

PartyMemberWithTalentInRange

CONDITION PartyMemberWithTalentInRange(SpeakerIndex, TalentID, Range)

Check speaker's party members in a range to have talent. TalentID is string.

HasAbility

CONDITION HasAbility(SpeakerIndex, AbilityID, Level)

Check speaker has ability no lower then of certain level. AbilityID is string.

IsTagged

CONDITION IsTagged(SpeakerIndex, Tag)

Check whether speaker has the specified tag.

Dialog Variable Editor

Overview

Each parameter of a Script Flag condition (FlagName, GroupName...) can be a Dialog Variable. A Dialog Variable starts with a % sign. While checking the flag, the variable is replaced by a default value or by a value set through script. All dialog variables are saved in the dialog folder under 'DialogVariables'.

Variables have to be defined through the 'Dialog variables' (Tools > Edit dialog variables) window.
EditDialogVariables.png 

A variable has a uuid, a (unique) name, a description, a type, a default value, the mod in which the variable is declared and the filepath. The different types are
  • Int
  • Float
  • String
  • FixedString

When you are writing a script and you use dialog variables that are not yet created, you will get a warning while saving. You can create the variable afterwards, but it is best to open the script and save it again afterwards. If the name of the variable is changed afterwards, the name in the script will be changed as well.

An overview of all the dialog variables in the current dialog (the dialog variables used in the scripts of the scriptflags set in the current dialog) can be found under Tools > Current dialog nodes.

Using Dialog Variables from Script

Dialog Variables can be set through Osiris script. To be able to do this there's a call supplied for every data type: 

call DialogSetVariableString((STRING)_Dialog, (STRING)_Variable, (STRING)_Value) 
call DialogSetVariableInt((STRING)_Dialog, (STRING)_Variable, (INTEGER)_Value)
call DialogSetVariableFloat((STRING)_Dialog, (STRING)_Variable, (REAL)_Value) 
call DialogSetVariableFixedString((STRING)_Dialog, (STRING)_Variable, (STRING)_Value)
call DialogSetVariableTranslatedString((STRING)_Dialog, (STRING)_Variable, (STRING)_StringHandleValue, (STRING)_ReferenceStringValue)

Where:

  • _Dialog is the name of the dialog (without extension)
  • _Variable is of the form <variable name>_<uuid>
  • _Value is the actual value of this parameter for the dialog _Dialog.
  • _StringHandleValue and _ReferenceStringValue can be obtained via the CharacterGetDisplayName and OtemTemplateGetDisplayString Osiris APIs

If the data type of the _Value that you're passing doesn't match the data type of the variable you will get an assert and no value will be stored.


Searching Through Dialogues

Searching in an individual Dialogue

The Dialogue Editor comes with a powerful Find tool that you can use to find back several pieces of information. You can access it from the Edit menu in the editor or by pressing the ctrl-f key combination.
DialogFindMenu.png

When you open the Find window, you'll get an interface similar to the Speaker Find option:
DialogSearch.png

Type what you're looking for into the Search for textbox. Clicking the Find button to start looking through the current Dialogue. The Dialogue Editor will then look for the text in the locations you specified in Search Locations using the options you specified in Search Options. The results and the number of results will be displayed at the bottom of the Find window. Double clicking a result line will select and center the Dialoge Editor on the Dialog Node where the result was found.

Search Locations

The Search Locations determine where the Dialogue Editor will look for your search string. You can specify multiple locations at the same time.

Logical Name

Look in the Logical Name property of the Dialogue Nodes.

UUID

The UUID is the unique identifier of a Dialogue Node. Every Node comes with one and no two nodes will share the same UUID. The game will report any potential errors in Dialogue structure using this UUID.

Text

Look in the text assigned to nodes

Flags

Look in the Flags that are being Set and Checked on the Dialogue Nodes.

Tags

Look at the Tags being checked and set on Dialogue Nodes as well as the Tags being checked in the Text Blocks of Dialogue Nodes.

Search Options

These can be used to refine your search results.

Match Case

Only returns results that have the same case as the search string.

Searching through files

To search in files, you can open the 'Find in files' window through the edit menu (Edit > Find in files) or by pressing the ctrl-shift-f key combination. All search locations and options available in the 'Find Dialog Nodes' are available in the 'Find in Files' form as well.
FindInFiles.png

Before you start searching, define the folder in which you want to search. If you want to search in subfolders of that folder as well, check the 'Search in subfolders'.

Testing Dialogues

To test a dialogue, open the dialogue in the dialogue editor and click the 'Play' button. This will open the 'Play window'. This will simulate the dialogue in game. It is possible to open the player without loading a level, however, dialogplayers, voices... can be more specific when a level is loaded.
PlayWindow.png

To start, click the 'Play' button. The start node is chosen and the possible options are shown in the 'dialogue' tab. To review the history of the dialogue, click the 'History' tab.

Advanced play

You can start playing your dialogs in the editor with certain dialog flags already set. This could be helpful to check what dialogs look like after completing a quest for an NPC, for a specific player eg.

In this window you can select a set of dialog flags and tags to set on the speakers.

To do so, open the 'Advanced play' (File > Play advanced). This option is not available when the dialog player is playing.
AdvancedPlay.png

On the left, you can see a list of available sets. The flags and tags set in the selected set are visible at the right. To create a new set, click the Create button. This will open the 'Create Flag set' window.
CreateFlagSetWindow.png

Flags can be assigned to the left by double clicking on the flag or using the up and down arrows to move a flag from 'Available flags' to 'Assigned flags'. This way, you can make a node valid when playing the dialog in the dialog player.

The following node for example checks if the speaker 'Magister' doesn't have the Character flag 'TUT_ShakeCamera' and has the Character flag 'TUT_CollaringPriest_Kill'. By setting those flags in the 'Create Flag set' window, that node becomes a valid node.
FlagsToCheck.png

You can do the same for tags. Following text is only chosen when speaker 2 has the tag 'RED PRINCE'. By assigning the tag 'RED PRINCE' in the 'Create flag set' window, this text will be valid when playing the dialog in the dialogplayer.
TaggedText.png

Templates

Using a template

If a certain combination of nodes is used multiple times, you can convert it to a template. A new dialog can be created from a template (File > New > From Template), but you can add a template to an existing dialog as well (right-click in the grey area > Insert Template...).
InsertTemplate.png

A template can have different parameters. Before inserting the template, you need to fill in a value for each parameter. Those parameters can be custom flags (see Adding Flag checks) or tags.

Creating a template

To create a template, create a dialog as described previously. Save it as a template (File > Save > Save as template). Select all flags and tags that you want to turn into parameters and give those a proper name.
CreateDialogTemplate.png

Provide a template name and path. If you don't want the text of the nodes to be exported as well, uncheck the 'Export Text' checkbox.
CreateDialogTemplate2.png

Retrieved from "https://docs.larian.game/index.php?title=Dialog_editor&oldid=4047"