articy:draft

(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.


articy:draft Projects

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:

General Data Notes

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.

articy:draft Variables

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:

  • articy:
    • Variable set: GameState
    • Variable: therapist_down
  • Dialogue System: 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)

articy:draft Entities

In the Dialogue System, articy:draft entities can be any of the following:

  • Players
  • NPCs
  • Items
  • Quests

You can distinguish between Players, NPCs, Items, and Quests by adding any of these Boolean properties to the entity's feature template:

  • IsPlayer
  • IsNPC
  • IsItem
  • IsQuest

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

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:

  • Trackable: If true, the player is allowed to toggle quest tracking for this quest.
  • Track: If true, show the quest in the quest tracker HUD. (Trackable must also be true.)
  • Abandonable: If true, the player can abandon the quest using the quest log window.

You can also add these optional properties to quests:

  • Success_Description: Shown when the quest is in the success state.
  • Failure_Description: Shown when the quest is in the failure state.
  • State: The starting state of the quest. This can be set two ways:
    1. A string set to "unassigned", "active", "success", "failure", or "abandoned", or
    2. A dropdown using the values in the table below.
  • Entry_Count
  • Entry_#: The text for a quest entry (starting from Entry_1, ...)
  • Entry_#_State: The starting state for a quest entry (starting from Entry_1_State). Uses the value types as the quest's main State property.

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+.

Actor Entities

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).

articy:draft Locations

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.

articy:draft Flow Fragments

Flow fragments can be handled three different ways. You can specify which way with a popup menu:

  • Conversation Groups: Flow fragments are prepended to conversation titles. This allows you to use flow fragments to organize conversations in groups.
  • Quests: Flow fragments are treated as quests. They're imported as elements in the Dialogue System's Item[] table as quests.
  • Ignore: Flow fragments are ignored.

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.

articy:draft Dialogues

Dialogues are imported as defined in articy:draft, into the Dialogue System's Conversation[] table, with the following notes:

  • Dialogue Fragments, Hubs, Jumps, and Connections within the Dialogue are imported normally.
  • Jumps that go outside the Dialogue are imported in Dialogue System 1.5.8+. In earlier versions of the Dialogue System, these jumps are not imported.
  • Dialogue Fragments that are only connected from Jumps or other links originating outside the dialogue will be imported, but they will show up as "Orphaned". You can link them manually after import if desired.
  • Condition nodes will be converted into two dialogue entries in the Dialogue System's dialogue database: one for the true state, one for the false state.
  • Instructions will be converted into a group dialogue entry that acts as a passthrough to run the instruction node's expression.
  • In articy:draft 2.4+, the Dialogue System will import the correct order of response nodes as indicated by the vertical position of the nodes on articy's canvas. Earlier versions of articy:draft (pre-2.4) do not export this information, so it's not possible to import it into the Dialogue System; instead, nodes will generally be ordered in the order they were created in articy.
  • All localization will be imported. (If you're using articy:draft's Unity exporter to export an Excel spreadsheet for localization, please read Localization Plugin)
  • In your dialogue text, you can use several Dialogue Markup Tags.
  • If you're using Unity UI, you can use bold, italic, and color rich text codes, as well as some special timing codes described in the Typewriter Effect section.
  • Assign the main actor and conversant to the Dialogue. You don't have to include all of the actors if your dialogue has more than two actors; you only need to specify the main actor and conversant. For example, the Feature Demo's "Private Hart" Dialogue has the actors "Player" and "Private Hart":

ConversantEntity Property

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.

Sequence Property

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 Expressions

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)

Link Priorities

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

articy:draft Templates, Features, and Properties

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:

  • Booleans, numbers, strings, and localizable text are converted.
  • For localizable text properties, all localized strings are converted.
  • Enums can be converted to their string values or index numbers, where 0 is the first enum value, 1 is the second enum value, etc.
  • Slots are converted to strings containing the DisplayName of the referenced object. (Note: Prior to 1.6.1, slots were converted to the IdRef.)
  • Strips are converted as special text fields that can expand into Lua subtables at runtime.
  • Since articy:draft Technical Names can't have spaces, use underscores instead where needed, for example if you're defining quest properties like Success_Description, Entry_Count, etc.
  • Make sure you've ticked "Include in XML Export" when defining your property.

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 Lua Subtables

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:

var ensnareSpellEffects = DialogueLua.GetItemField("Ensnare", "Effects").AsTable;

articy:draft Documents

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.

Emphasis Settings

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.

Voice-Over Plugin

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.

Localization Plugin

articy:draft 3 has a localization plugin. For instructions on using this plugin with the Dialogue System, see articy:draft Localization Plugin Instructions.


articy:draft Converter

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.

  1. In articy:draft, export the project to an XML file somewhere in your Assets folder hierachy. When exporting XML in articy:draft, uncheck Export Text Markup.
  2. Select Window > Dialogue System > Converters > articy:draft Converter:
  3. articy:draft Project: Select your XML file.
  4. Encoding: (Optional) Specify the XML file's character encoding type. If importing special characters (such as umlaut), change Encoding to UTF8.
  5. Stage Directions are: (Optional) If you used the Stage Directions field for sequencer commands, select Sequences. If you created a new template field named "Sequence", select Not Sequences.
  6. Dropdowns as: (Optional) Specify how to you want to import dropdowns (enums) – as their display names or their index values. (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+.) You can also specify types for individual dropdowns in the Dropdown foldout further down the window.
  7. Slots as: (Optional) Specify how to you want to import slots – as their display names or their articy internal IDs.
  8. FlowFragments are: (Optional) Specify how you want to handle flow fragments.
    • Nested Conversation Groups: Prepend flow fragment's name to titles of subconversations, and create links into subconversations.
    • Conversation Groups: Prepend flow fragment's name to titles of subconversations.
    • Quests: Create quests out of flow fragments.
    • Ignore: Ignore flow fragments.
  9. FlowFragment Script: (Optional) Enter the name of a Lua function to run it when a flow fragment occurs inside a dialogue.
  10. VoiceOverFile Property: (Optional) If you use the Voice-Over Plugin, specify the name of your voice-over file property. Don't enter the entire path including the feature name; only enter the property name.
  11. Portrait Folder: (Optional) Specify the folder containing the the actor portrait images defined in articy:draft. If you didn't specify actor portrait images, or if you don't want to display character portraits beside subtitles, you can leave this blank.
  12. Save To: Select the folder where you want the dialogue database to be created.
  13. Overwrite: Tick if you want to overwrite an existing dialogue database (if one exists).
  14. Click Review. This will load the articy:draft XML data for you to review. Open each foldout as shown in the screenshot below.
  15. Tick the items you want to import, and untick the items you want to skip. In Entities, change the player's pop-up from "NPC" to "Player" so the converter knows which entity to treat as the player. If you've defined an "IsPlayer" template property for characters, the template property value will override this pop-up. articy:draft 1.x doesn't provide a good way to automatically distinguish actors from items, so you'll also have to select the appropriate categories using the pop-ups.
  16. The converter will remember your settings the next time you open the window. In the future, you can skip the Review button unless you want to change your settings or reload changes from the XML file. (To clear the settings and start over, click the Clear button.)
  17. Click Convert to create the dialogue database. After converting, if you change your articy:draft project and re-export it, click Review before Convert to refresh the version of the XML file that's cached in the converter's memory.

Runtime Conversion

You can also convert articy:draft XML files into dialogue databases at runtime. To do this, call this static function:

ArticyConverter.ConvertXMLToDatabase(string xmlFilename, ConverterPrefs prefs = null, Template template = null)

For example, to convert D:/Data/MyArticy.xml:

var database = ArticyConverter.ConvertXMLToDatabase("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.

Full Code Example

The code below contains a complete example of importing an articy:draft XML at runtime:

...
var database = ArticyConverter.ConvertXMLToDatabase("D:\Data\MyArticy.xml");
DialogueManager.AddDatabase(db);
DialogueManager.SendUpdateTracker();

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.

Converting Expressions

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.

var luaCode = ArticyConverter.ConvertExpression(expressoCode)

<< Chat Mapper | Aurora Toolset >>

PixelCrushers.DialogueSystem.Articy.ArticyTools.InitializeLuaSubtables
static void InitializeLuaSubtables()
Articy strips are saved in a string field.
Definition: ArticyTools.cs:108
PixelCrushers.DialogueSystem.Articy
Definition: ArticyConverterWindow.cs:8
PixelCrushers.DialogueSystem
Definition: ArticyConverterWindow.cs:8
PixelCrushers
Definition: ArticyConverterWindow.cs:8
PixelCrushers.DialogueSystem.Articy.ArticyTools
This static utility class contains tools for working with Articy data.
Definition: ArticyTools.cs:11