 |
|
The Dialogue System stores its content in dialogue databases.
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:
Once you've created a dialogue database, read about How to Edit Dialogue Databases.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Other topics: