How to Create a Dialogue Database

You can create a dialogue database from scratch and edit it inside Unity, or you can use one of the Dialogue Database Converters.

To create a dialogue database from scratch:

Select Asset > Create > Dialogue System > Dialogue Database, or
In the Project view, right-click and select Create > Dialogue System > Dialogue Database

Once you've created a dialogue database, read about How to Edit Dialogue Databases.

What's in a Dialogue Database?

A dialogue database contains these sections:

Section	Description
Database Properties	General settings such as the description, author and version
Actors	Conversation participants (PCs, NPC, interactive objects)
Items/Quests	Information about items and quests
Locations	Information about locations
Variables	Lua user variables
Conversations	Conversations between actors

The dialogue database format is based on the data model used by Urban Brain Studios' Chat Mapper, a authoring tool used widely in the industry. If you've used Chat Mapper, the terms below will already be familiar.

Database Properties

The Database Properties section contains this information:

Field	Description
Author	The author of this database
Version	The version of this database, so you can keep track of revisions
Description	A description of what this database contains, its purpose, etc.
Global User Script	An optional Lua script to run when using this database
Emphasis Settings	Special text formatting values that you can use in your dialogue entries

The Author, Version, and Description fields are typically only used internally by the game developer.

Actors

The Actors section contains a list actors. Each actor contains this information:

Field	Description
ID	An ID number used internally by the Dialogue System to reference the actor
Name	The name of the actor
Display Name	(Optional) The name to show in the dialogue UI's portrait name field, and which is set in Variable["Actor"] or Variable["Conversant"]
Description	The description of the actor
Portraits	Optional portrait images or spritesheets that can be displayed during conversations
Fields	A customizable list of data fields. See Fields

Every dialogue database starts with an actor named Player that represents the PC.

You can add more actors and set the IsPlayer field True (player character) or False (non-player character). Actor names must be unique.

The Display Name can contain [var=varName] and [lua(code)] Dialogue Markup Tags. For example, you can use the TextInput() sequencer command to input the player's name and store it in a variable, and then use the [var=varName] tag in the player actor's Display Name to show the value of the variable for the player's name.

In the Lua environment, actors are stored in the Actor[] table.

Items/Quests

The Items/Quests section contains a list of items and/or quests. Items and quests are stored in the same section to make it easier to convert Chat Mapper projects into dialogue databases. Chat Mapper doesn't have a quest system, but Chat Mapper users can repurpose the Item table to hold quest information.

The Dialogue System uses quests in the Quest System, but it doesn't use items for anything in particular. You can use their data however you want as appropriate for your project.

Each item contains this information:

Field	Description
ID	An ID number used internally by the Dialogue System to reference the item
Name	The name of the item
Description	The description of the item
Fields	A customizable list of data fields. See Fields

Item names must be unique.

In the Lua environment, items are stored in the Item[] table.

Each quest contains this information:

Field	Description
ID	An ID number used internally by the Dialogue System to reference the quest
Name	The name of the quest
Display Name	(Optional) The name to show in the quest log window and quest tracker HUD. If not defined, the Name field is used
Group	The optional group that the quest belongs to
Description	The description of the quest, usually containing completion requirements
Success Description	The optional description of the quest once successfully completed
Failure Description	The optional description of the quest if completed in failure
State	The starting state of the quest (e.g., unassigned, active, etc.)
Trackable	(Optional) Specifies whether the player can track the quest in a heads-up display (HUD)
Track	(Optional) If Trackable is true, specifies whether to currently track the quest in a HUD
Abandonable	(Optional) Specifies whether the player can abandon the quest in the quest log window
Abandon Sequence	(Optional) Sequence to play if the quest is abandoned; if needed, you must add this field manually
Entries	(Optional) Quest entries (subtasks), each with its own description and state
Fields	A customizable list of data fields. See Fields

Note that the Quest System uses a field named State, not the Chat Mapper GetStatus()/SetStatus() functions.

At runtime, the quest system may create or set a Boolean field named Track. This specifies whether the quest is currently being tracked (versus Trackable, which specifies whether the player is allowed to enable or disable tracking). The Quest Tracker HUD checks Track to determine which quests to show. If you want tracking to be active as soon as the quest becomes active, create this field manually and set it true.

Quest descriptions may contain formatted text (e.g., tags such as [lua(code)]), although response menu-related tags are discarded, and emphasis tags are ignored in order to give the display a consistent look in the Unity Quest Log Window. You're free to observe these tags, of course, in your own quest window implementation if you choose to write one instead of using any of the built-in quest log window systems.

Quest names must be unique.

Quest groups are optional. If you want to organize your quests into groups, you must manually add a Group field to the quest or add it to the quest template on the Templates tab.

In the Lua environment, quests are stored in the Item[] table, but you can use the alias Quest[] to refer to the same table.

Fields are localizable by adding a custom field with " <em>langugage</em>" at the end of the name, such as "Description ru" for the quest description in Russian. See Localization for more info.

For more on quests and items, see More on Quests and Items.

Locations

The Locations section contains a list of locations. The Dialogue System doesn't use locations for anything in particular. You can use their data however you want as appropriate for your project.

Each location contains this information:

Field	Description
ID	An ID number used internally by the Dialogue System to reference the location
Name	The name of the location
Description	The description of the location
Fields	A customizable list of data fields. See Fields

Location names must be unique.

In the Lua environment, locations are stored in the Location[] table.

Variables

The Variables section contains a list of user-defined Lua variables. You can check and set the values of these variables in your dialogue entries to control the flow of conversations and record information about choices that the player has made.

Each variable contains this information:

Field	Description
Name	The name of the variable
Initial Value	The initial value of the variable
Description	The description of the variable (e.g., its purpose)
Fields	A customizable list of data fields. See Fields

Every dialogue database starts with a text variable named Alert that you can set to display a gameplay alert.

Variable names must be unique.

In the Lua environment, variables are stored in the Variable[] table.

Conversations

The Conversations section contains conversations. A conversation is a collection of linked dialogue entries. The conversation contains information, and each dialogue entry also contains information.

The conversation information is:

Field	Description
ID	An ID number used internally by the Dialogue System to reference the conversation
Title	The title of the conversation. When triggering a conversation, you will usually reference it by title
Actor	The primary participant. In a PC-NPC conversation, this is the PC
Conversant	The other participant. In a PC-NPC conversation, this is the NPC
Fields	A customizable list of data fields. See Fields

Conversation titles must be unique. If you want to organize your conversations in groups, you can use forward slashes in titles, such as "Level 1/Commander", "Level 1/Radio Barks", and "Companions/Romantic/Nadia/In Barracks". The slashes will act as submenus in the dialogue editor and conversation trigger pop-up menus.

Although conversations define an Actor and Conversant for convenience, you can involve any number of actors in a conversation.

The information for each dialogue entry is:

Field	Description
ID	An ID number used internally by the Dialogue System to reference the dialogue entry
Title	The optional title of the dialogue entry, useful to record reminders about its purpose
Actor	The actor that speaks this entry
Conversant	The actor that listens to this entry
Group	A flag that marks this entry as a special stub entry used to group together several child entries
Dialogue Text	The text spoken by the actor. If blank, the Menu Text is spoken
Menu Text	The text shown in the player response menu, usually a shorter version of the Dialogue Text. If blank, the Dialogue Text is used
Sequence	The cutscene sequence to play while the actor speaks this entry, for example to play lipsync animation
Conditions	The conditions that must be true to use this entry. Conditions may check quest states, variables, etc. (Note that Conditions are not checked on the START node.)
Script	The Lua script to run when this entry is spoken. It may set quest states, variables, etc.
Links	A list of links to other entries
Fields	A customizable list of data fields. See Fields

There may also be language-localized versions of Dialogue Text, Menu Text, and Sequence. There may also be an optional Response Menu Sequence that is played after the dialogue entry, when the player response menu is shown.

For more information about Conditions, see More on Conditions.

Bark Conversations

Interactive conversations usually have a back-and-forth flow, where the actor says a line, then the conversant says a line, and so on.

Barks, on the other hand, are one-off lines of dialogue that don't involve a player response menu. They're typically spoken by an NPC for atmosphere (e.g., "Nice weather today"). Barks can also give the player an idea of an NPC's internal state (e.g., "I'm reloading. Cover me!").

To create a bark conversation, add all bark entries as children of the START node. In other words, the conversation tree will only be one level deep. When an actor barks, the Dialogue System will evaluate all children of the START node to generate a list of currently-valid entries. It will then choose an entry from this list and bark it. Barks can play in sequential order or random order. You'll be able to specify this when you configure your Bark Trigger.

You can set conditions on entries to ensure that they'll only be barked when appropriate. By setting conditions, barks can be aware of the current game state. For example, Sergeant Graves in the Feature Demo only communicates through barks. He barks different lines depending on the current state of the "Assassinate the Emperor" quest. You could also define variables that record whether each dialogue entry has already been barked: In the entry's Script field, set the variable true. In the Conditions field, make sure the variable hasn't already been set true.

Remember that you can also specify a cutscene sequence in each dialogue entry. For example, the sequence could play a hand wave animation with a "Hello" bark. If the dialogue entry's sequence is blank, no sequence will be played; it will not play the Dialogue Manager's Default Sequence.

Bark Priority Values

You can specify priority levels on your bark entries to prevent lower-priority entries from interrupting higher ones.

To do this, add a custom Number field named "Priority" to your dialogue entry. Higher values have higher priority. If you don't want to have to add this custom field on each entry, you can add it to the template on the Dialogue Editor Templates Tab. If the dialogue entry doesn't have a custom field named "Priority", it uses a default of 0.

When the Dialogue System considers playing a bark (for example, through the Bark On Idle component), it checks the bark entry's Priority. If the NPC is already barking, the Dialogue System will only interrupt it to play the new bark if the new bark's Priority is greater than or equal to the current bark's Priority.

ID Numbers

Every element in the dialogue database has an ID number. Within a section (such as the Actors section), each element must have a unique ID. The Dialogue System automatically handles IDs to keep them unique, but it's possible to manually change IDs and create conflicts. The Unique ID Tool can fix conflicts for you.

Fields

Every element in the dialogue database has a customizable list of data fields. In fact, many pieces of information listed above, such as Name, Title, and Description, are actually fields. You can define fields as necessary to store additional information about each element. For example, in a combat-based game you might want to define a field named HP in each actor to keep track of the actor's hit points.

The Dialogue System offers many field types, such as Text, Number, and Boolean, as well as references to Actors, Locations, Items, etc. In addition, you can define your own custom field types (see Custom Field Types).

If you define a field Notes, it will appear below Conditions and Scripts (as well as the All Fields section). You can use this field to record notes about the dialogue entry. The Dialogue System doesn't do anything special with this field.

Table of Contents