Chat Mapper Project Details

Your Chat Mapper Project should contain these settings:

Custom Asset Fields - Items

Title	Type	Description
Is Item	Boolean	Specifies whether the item is an item or a quest

If you're using the Quest System, also add the quest fields listed in the Items/Quests section. If you plan to use quest entries (subtasks), you can read more about how to add fields for them in the Quests Entries in Chat Mapper section.

Custom Asset Fields - Dialogue Nodes

Title	Type	Description
Sequence	Text	Cutscene sequence to run during the node
Response Menu Sequence	Text	(Optional) Cutscene sequence to run during the response menu that follows the node

To set up Localization, also add localized fields as described in the Conversations section. The Chat Mapper simulator will only recognize localization of the Dialogue Text field, but any other localized fields, such as Menu Text, will be handled properly in the Dialogue System.

Global Lua Script

If you're using the Quest System, add this to the Global Lua Script:

Quest = Item;

This Lua statement makes Quest[] an alias for the Item[] table. In your Conditions and Script fields, you can refer to Quest["questName"] instead of Item["questName"].

Chat Mapper Project Template

The Dialogue System provides a blank template Prefabs/Chat Mapper Template/Template.cmp that already contains these settings. You can make a copy of this template and use it as your project file, or copy it to your [Documents]/Chat Mapper/Templates folder to make it available as a template choice in Chat Mapper.

The template is based on the Chat Mapper "Games" template. Several fields from the Chat Mapper "Games" template are still present but excluded from export to reduce the size of your asset files. You can review these fields and change which ones are exported by selecting Project > Project Settings in Chat Mapper.

Notes about Content

Review these helpful tips before editing your Chat Mapper Project:

Asset names (actors, items, locations, variables) and conversation titles must be unique. If you define two actors with the same name, only one will be loaded at runtime. If a conversation references the other (not-loaded) actor with the same name, the results may be unpredictable.
The Dialogue System will try to match the characters' GameObject names with their actor names. It's simplest to keep these the same. If not, you can use an Override Actor Name component in Unity.
If you use actor pictures, store them in your Assets folder hierarchy so Unity will be able to access them.
If you're using the Quest System, define your quests as items as described above. You're otherwise free to store whatever information you want in items.
In Chat Mapper and the Dialogue System, space characters and hyphens get replaced with underscores in Lua table indices. This is described in more detail in the section Important Note About Table Indices. For example, My Quest becomes My_Quest when referencing the Item[] table. For example:
- Item["My_Quest"].State = "active"
The Dialogue System doesn't use locations for anything specific. You can store whatever information you want in them.
The Dialogue System will create the following user 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)

The first dialogue node of every conversation should be START. This is the default.
Define cutscene sequences in a custom Dialogue Entry field named Sequence in this form:
- Action(parameters)[@seconds] If you leave a Sequence field 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 START node's Sequence to:
```
LookAt()
```
The Dialogue System supports all of Chat Mapper's standard conventions and features, with a few differences, as documented in Dialogue Markup Tags.
If you need to do more dialogue entry validation outside of Lua (e.g., checking GameObjects in Unity), you can use an IsDialogueEntryValid Delegate.
The Dialogue System supports Chat Mapper's localization functionality. To set up localization, see Localization.
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.

Limitations and Warnings

If you create multiple Chat Mapper Projects, it's possible that their internal assets (actors, items, etc.) will have IDs that overlap across projects. To resolve this in the Dialogue System, use the Unique ID Tool.
The Chat Mapper Converter will split Dialogue Text with pipes (|) into separate dialogue entries.
- The Audio Files, Menu Text, Sequence fields, as well as their localized counterparts, are also split.
- All other fields will be assigned to all of the split entries.
- If the Chat Mapper dialogue entry is set to Passthrough, the Dialogue System will apply the Condition to all of the split entries. Otherwise (if it's Block) it will only be applied to the first entry.
- The Script will only be applied to the first entry.
- There is a known issue when Dialogue Text or Menu Text contains pipes inside other tags such as the [lua()] tag. For example, this Dialogue Text will not be split properly:
```
Hello, [lua(RandomElement("friend|buddy"))]. | How are you?
```

However, if you use a variable, it will be split properly. For example, set a variable FriendSynonyms to friend|buddy. Then use this Dialogue Text:

Hello, [lua(RandomElement(Variable["FriendSynonyms"]))]. | How are you?

The Dialogue System supports all Chat Mapper features except:
- Cross-project links (This is on the feature roadmap.)

Quests Entries in Chat Mapper

Chat Mapper doesn't actually have a concept of quests. You have to do a little setup in your Chat Mapper project first by adding some custom item fields. Select Project > Project Settings > Custom Asset Fields > Items. Add these fields:

Field Name	Type	Default Value
Is Item	Boolean	False
Entry Count	Number	0

Add as many entries as you need for your biggest quest. You can always add more later if you need them. If you're localizing to multiple languages, you can add fields for them, too, such as Entry 1 ru for the Russian version of the text for Entry 1.

These fields are not in the provided template because many developers do not use quest entries.

When you define a quest, set Entry Count. Even though every item record will have the full set of Entry 1 ... Entry n, the Dialogue System will only use the entries up to Entry Count.

Then set Entry 1 to the entry text and Entry 1 State to the quest state (e.g., "unassigned" or "active"). Repeat for all the entries up to Entry Count.

Chat Mapper Converter

To convert a Chat Mapper Project into a dialogue database, use the Chat Mapper Converter. If you use Chat Mapper Commercial, you can convert CMP files directly. If you use Chat Mapper Indie, you must export your project to an XML file first.

How to Export Chat Mapper XML

To export to XML from Chat Mapper, select File > Export > Project as XML.

How to Use the Chat Mapper Converter

The Chat Mapper Converter creates a dialogue database out of a Chat Mapper CMP or XML file.

If you're using Chat Mapper Indie, export the project to an XML file somewhere in your Assets folder hierachy. If you're using Chat Mapper Commercial, the Chat Mapper Converter can process the CMP file directly, so you don't need to export it to XML.
Select Window > Dialogue System > Converters > Chat Mapper Converter.
Set Project Format to XML or CMP. You can only use CMP with Chat Mapper Commercial.
If you're using Chat Mapper Commercial, set Path to ChatMapper.exe to the location where you installed ChatMapper.exe. You only need to specify the path to ChatMapper.exe if you have a Commercial License and want to convert directly from the Chat Mapper project file (CMP) instead of manually exporting to XML.
In the Chat Mapper Projects section, press '+' to add slots for Chat Mapper files. Then click the '...' button next to each slot to add a Chat Mapper file. You can untick the checkbox next to each slot if you don't want to convert that file.
(Optional) For Portrait Folder, specify the folder containing the actor portrait images defined in your Chat Mapper project. 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.
(Optional) If your Sequence fields contains pipes ('|' characters) and the sequencer commands use the '{{end}}' keyword, tick Smart Split. When the converter splits a dialogue entry at the pipe character, it will put all '{{end}}' sequencer commands on the last split. All other sequencer commands will be on the first split, and the middle splits will be Delay({{end}}).
For Save To, select the folder inside the Assets hierarchy where you want the dialogue database to be created.
Tick Use Project Name to use the Project Name defined in the Chat Mapper Project as the name of the dialogue database. If you untick this, you can specify a different dialogue database name.
Tick Overwrite if you want to overwrite an existing dialogue database (if one exists).
Click Convert. This will create a dialogue database. If Overwrite is unticked and you need to reconvert, you may want to delete the old asset first. Otherwise the new database will be created with a slightly different name, usually by appending a number to the end.

The image below shows settings for converting an XML-exported Chat Mapper project:

Note: You can also convert Chat Mapper XML to a dialogue database asset at runtime using PixelCrushers.DialogueSystem.ChatMapper.ChatMapperProject.ToDialogueDatabase().

Exporting XML To Chat Mapper

The Dialogue Editor can export dialogue databases to Chat Mapper XML format. This is useful for creating a text-format backup copy of your database.

Using Chat Mapper 1.7+, you can also import this back into Chat Mapper.

Chat Mapper's XML importer is very particular. After importing the XML, you must import a Chat Mapper template that defines every field in your dialogue database, in the exact order of your database.

For example, if you've defined a quest that has an Abandonable field, your Chat Mapper template must define an Abandonable field. Similarly, if you use quest entries, you must define Entry Count as well as Entry # and Entry # State fields for as many entries as you have defined in your longest quest.

Follow these instructions to export a dialogue database and then import it into Chat Mapper:

Make sure there are no links back to the START node in any conversations. Chat Mapper doesn't allow links back to the START node. If you have any conversations where nodes link back to START, correct them before exporting to Chat Mapper XML. You can add a child node of START and link back to that.
Open your dialogue database in the Dialogue Editor.
Optional: On the Template tab, select Reset from the menu. This will reset the Dialogue Editor's template.
- Do this step if you've added fields to the template that you have not used in any assets. This will prevent those fields from being added to all assets.
- Do this step if you've added fields in different orders in different assets. By resetting the template, you will allow it to apply a consistent order across all assets.
On the Database tab, export Chat Mapper XML.
- A window will pop up to ask if you want to update the template to match the contents of the database. If you click OK, it will update the template, and then apply the template consistently to all assets in your database.
- The export process will create a file in the same directory as filename.xml, named filename_Template.txt. This text file will list all fields that must be in your template. You can use the Chat Mapper project in Prefabs/Chat Mapper Template as a base for your template. Place a copy in your [Documents]/Chat Mapper/Templates/ folder and adjust it so it contains exactly the fields listed in the text file, in the exact order.
Import the XML into Chat Mapper.
After importing the XML file into Chat Mapper, select Project > Apply Template to Project... and specify the template.

If the import fails:

Verify that all fields are defined in your template exactly as listed in the text file.
Review the Chat Mapper log located in [Documents]/Chat Mapper/log.txt.
If you get stuck, contact Pixel Crushers at suppo.nosp@m.rt@p.nosp@m.ixelc.nosp@m.rush.nosp@m.ers.c.nosp@m.om for assistance.

How to Import Chat Mapper at Runtime

It's possible to import Chat Mapper XML at runtime, too. See the code example below:

using PixelCrushers.DialogueSystem;
using PixelCrushers.DialogueSystem.ChatMapper;
...
var chatMapperProject = ChatMapperTools.Load(xmlFile);
var db = ChatMapperToDialogueDatabase.ConvertToDialogueDatabase(chatMapperProject);
DialogueManager.AddDatabase(db);
DialogueManager.SendUpdateTracker();

The code above creates a ChatMapperProject object from an XML file. The xmlFile parameter can be a filename or a TextAsset.

It then converts the ChatMapperProject to a DialogueDatabase and adds it to the Dialogue Manager.

Finally, it updates the quest tracker HUD in case the Chat Mapper project contains active, trackable quests.

<< Dialogue Database Converters | articy:draft >>

Table of Contents