 |
|
(Click Here for Video Tutorial)
The Dialogue System can convert Nevigo's articy:draft 1, 2, & 3 into a Dialogue Database at design time in the Unity editor and at runtime.
The Dialogue System's converter does not use articy:draft 3's Unity exporter. You do not need to import articy's special unitypackage plugin for its Unity exporter. We may introduce support for articy's Unity exporter in the future, but for now it's not necessary.
The Dialogue System includes a starter project in Prefabs/Articy/articy_template.zip. It's built in articy:draft 2.4 for compatibility with 2.4 and 3.x users. This project is configured with all of the custom fields described below.
The Dialogue System's articy:draft Converter imports data from XML exports. It imports the following data:
Each imported element will have a field named Articy Id containing the articy:draft Id (e.g., 0x01000001000011FB) and a field named Technical Name containing the technical name (e.g., "Loc_Corridor").
The Name field will contain the element's default Display Name.
All imported elements will also be given all the fields defined in the dialogue database template, which you can edit using the Dialogue Editor Templates Tab before importing the articy:draft project. If you define new fields in articy draft, replace blank spaces in their technical names with underscores (e.g., "Alternate_Name").
Your player entity should have a Boolean property named IsPlayer set to True.
Variable sets and variables are imported as elements in the Dialogue System's Variable[] Lua table, where the name of the variable is VariableSet.VariableName. For example:
Variable["GameState.therapist_down"]The Dialogue System will create the following Lua variables if they don't exist:
| Variable | Type | Description |
|---|---|---|
| Alert | Text | You can assign text to this variable. At the end of the conversation, the dialogue UI will display that text. You can use this to give the player information. For example, to let the player know that they just acquired a new quest, add a Script such as Variable["Alert"] = "New Quest: Kill 5 Rats" |
| Actor | Text | The name of the current actor. In the Dialogue System, you can configure a conversation to trigger for any character, not just the character defined in your Chat Mapper project. You can read the value of Variable["Actor"] to get the name of the current actor. This is useful for general-purpose, shared conversations such as shopkeepers |
| Conversant | Text | Similarly, this is the name of the current conversant (see Actor above) |
In the Dialogue System, articy:draft entities can be any of the following:
You can distinguish between Players, NPCs, Items, and Quests by adding any of these Boolean properties to the entity's feature template:
The property's Technical Name must use the exact capitalization as above with no space characters. If any of these properties exists, they will override the pop-up menu setting in the articy:draft Converter.
Note: Your player entity should have a Boolean property named IsPlayer set to True. The IsPlayer property distinguishes to the Dialogue System which dialogue fragments are shown as subtitles and which ones are shown in player response menus (IsPlayer fragments).
Item and Quest entities are imported as elements in the Dialogue System's Item[] table. This table is also used for quests, and in Lua has an alias as Quest[]. In your Lua code, you can use Item[] or Quest[] interchangeably.
If you want to use the Dialogue System's Quest Tracker HUD, add these Boolean properties:
You can also add these optional properties to quests:
Quest State Dropdown Values
| Value | State |
|---|---|
| 1 | unassigned |
| 2 | active |
| 3 | success |
| 4 | failure |
| 5 | abandoned |
The dropdown values must be exactly the numbers shown above (1, 2, 3, etc.).
NOTE: A bug in articy:draft 2.4.3 - 2.4.5 causes dropdown values to be offset by one. To resolve this, upgrade to 2.4.6+.
Player and NPC Actor entities are imported as elements in the Dialogue System's Actor[] table. Portrait images (if specified) will be imported from the location specified in the articy:draft project, as long as that location is inside the Unity project's Assets folder. If not, you can manually assign them after import.
The Dialogue System will try to match the characters' GameObject names with their entity Display Names in articy:draft. It's simplest to keep these the same.
At a minimum, you should define at least two Actors (usually the Player and an NPC).
Locations are imported as elements in the Dialogue System's Location[] table. The Dialogue System doesn't use locations for anything specific. You can store whatever information you want in them.
Flow fragments can be handled three different ways. You can specify which way with a popup menu:
Item[] table as quests.Flow fragments inside conversations will be converted as pass-through dialogue entries. However, in the converter you can also choose to have them invoke a Lua function. The dialogue entry will pass the name of the flow fragment to the Lua function. You can register a custom Lua function and use this feature to invoke your own C# code when the conversation passes through a flow fragment.
Dialogues are imported as defined in articy:draft, into the Dialogue System's Conversation[] table, with the following notes:
In a Dialogue Fragment, the entity spoken to is called the conversant. Normally the conversant is the non-speaking actor (for this fragment) among the two actors assigned to the Dialogue. However, if you want to assign a different actor as the conversant, add a custom slot property named "ConversantEntity" to your dialogue fragment template. The Technical Name must be "ConversantEntity" with exact capitalization and no blank spaces. For the property's "Allowed object types", tick only "Entities". Make sure to tick "Add to XML-export".
If you're using Dialogue System 1.7.3 or earlier, you must set the "Convert Slots As" dropdown to "ID" in the articy Converter window.
Define cutscene sequences in the Stage Directions field, in this form:
Action(parameters)[@seconds]
If you leave it blank, the Dialogue System will use the default sequence defined in the Dialogue Manager's display settings. Frequently, you will want to make the conversants face each other at the beginning of a conversation. To do this, set the dialogue fragment's Stage Directions to:
LookAt()If you want to use the Stage Directions field for something else, add a custom text property named "Sequence" to your dialogue fragment template. The Technical Name must be "Sequence". Put your Dialogue System sequencer commands in this field, and untick "StageDirs are Sequences" in the converter (see below). Make sure to tick "Add to XML-export".
More information: Sequences
articy:draft 1 input and output pins will be imported as-is, assumed to be written in Lua.
articy:draft 2 input and output pins that contain articy:expresso code will be imported, and the Dialogue System will attempt to translate the expressions to Lua. If the expressions already appear to be written in Lua, they'll be imported as-is.
To use getObj(), getProp(), setProp(), and speaker as detailed in https://www.nevigo.com/articy-importer/unity/html/howto_script.htm, add an Articy Lua Functions component to your Dialogue Manager. (Component > Dialogue System > Third Party > articy:draft > Articy Lua Functions)
In the Dialogue System, links (articy:draft connections) have priority values. The default priority value is Normal.
When the Dialogue System evaluates a level of the conversation tree, it first considers all dialogue entries at the highest priority level. If there are any dialogue entries with true conditions at this level, it stops evaluating, and it only uses those dialogue entries. If no dialogue entries are true at the highest priority level, it considers the next priority level, and so on. This allows authors to write a line that always takes precedence over lower-priority lines as long as its condition is true.
To specify priority levels in articy:draft, the Dialogue System uses colors. To set a priority level in articy:draft, select a connection and then change the color to one of the colors on the bottom row of the color picker, starting from the second button on the left. Any color other than the ones below is treated as Normal priority.
| Color | Priority Level |
|---|---|
| #FF0000 | High |
| #FFC000 | Above Normal |
| (any other) | Normal |
| #FFFF00 | Below Normal |
| #92D050 | Low |
In articy:draft 2, you can define templates to apply to elements such as Entities and Dialogues. These templates can contain properties and features (groups of properties). All features and properties are converted to dialogue database fields, with these notes:
As mentioned in the articy:draft Entities section above, if you add an "IsPlayer" Boolean property to actor entities. Set it to true for player characters, false for NPCs.
Strips are converted as text fields with the text "SUBTABLE__" added to the front of the field title. The content of the text field is a semicolon-separate list of Articy Ids, such as:
0x0100000000000260;0x0100000000000264;0x0100000000000B6D
At runtime, you can convert all such fields into Lua subtables by calling the method below. The subtable field's title will not have the "SUBTABLE__" prefix.
To get the values of the subtable, which will in turn be elements in the Actor[] or Item[] table, use DialogueLua.GetActorField or DialogueLua.GetItemField:
The Dialogue System supports dialogues inside documents. Dialogue fragments must be located inside dialogues. The converter will ignore loose dialogue fragments that are in documents but not in dialogues within those documents.
The Dialogue System supports four Emphasis ([em#]) Dialogue Markup Tags. You can define variables in your articy project to specify the values of the emphasis tags. For each emphasis tag, you can define four variables for color (a string using #rrggbbaa format), bold, italic, and underline (Booleans).
You can then specify these variables in the articy:draft Converter window's Review > Emphasis Settings section.
articy:draft 3 has a voice-over plugin. For instructions on using this plugin with the Dialogue System, see articy:draft Voice-Over Plugin Instructions.
articy:draft 3 has a localization plugin. For instructions on using this plugin with the Dialogue System, see articy:draft Localization Plugin Instructions.
To bring your articy:draft project into Unity, use the articy:draft Converter. This creates a dialogue database asset out of an articy:draft XML file.
You can also convert articy:draft XML files into dialogue databases at runtime. To do this, call this static function:
For example, to convert D:/Data/MyArticy.xml:
The prefs and template parameters are optional.
The prefs object lets you specify which articy:draft content to convert and how to convert it. Since the runtime project doesn't have access to the Unity editor environment, it won't use any prefs you've already set in the articy:draft Converter window. If you omit prefs, all supported content will be converted.
The template specifies the templates for the various types of assets in the dialogue database. Since the runtime project doesn't have access to the Unity editor environment, it won't use the template you've set in the Dialogue Editor. If you omit template, it will use a default template.
If portrait images are associated with actors in the XML file, the converter will search all Resources folders and loaded asset bundles.
If conversion fails, the method will return null instead of a dialogue database object.
The code below contains a complete example of importing an articy:draft XML at runtime:
The code above creates a DialogueDatabase from an articy:draft file, adds it to the Dialogue Manager, and updates the quest tracker HUD in case the articy:draft file contains active, trackable quests.
The converter converts pins from articy expresso to Lua. If you want to convert additional fields, call ArticyConverter.ConvertExpression. You must have previously converted an articy XML file. The converter will cache the variable names from the XML file conversion to use when converting other expresso code.
<< Chat Mapper | Aurora Toolset >>