Unity — Dialogue System

Pixel Crushers’ Dialogue System for Unity imports ChatMapper XML natively. ChatMapper Cloud’s Unity export is that XML plus a preflight for the things that import cleanly and then misbehave at runtime — which is where integration time actually goes.

The pipeline

In ChatMapper, apply the built-in Unity — Dialogue System custom field template (Details → Custom field templates). It adds Sequence and Response Menu Sequence to every dialogue node and Is Item to every item, so writers fill them in as they go.
Export → Unity — Dialogue System XML. Read the preflight report; fix errors, weigh warnings.
In Unity: Tools → Pixel Crushers → Dialogue System → Import → Chat Mapper, point it at the XML, and import into a Dialogue Database.
Wire the database into a Dialogue Manager and trigger conversations by title as usual.

There is no separate file format: the Unity export emits exactly the same bytes as Export → ChatMapper XML. Using the preset just adds the report.

What maps to what

ChatMapper	Dialogue System
Actor	Actor (`IsPlayer` → Is Player)
Item	Item, or Quest — decided by the `Is Item` field
Location	Location
UserVariable (`Initial Value`)	Variable
Conversation	Conversation; `Actor` / `Conversant` become its default participants
DialogEntry (node)	Dialogue Entry; `Dialogue Text` and `Menu Text` map by name
`ConditionsString`	Conditions (Lua)
`UserScript`	Script (Lua)
`IsGroup`	Group entry
`FalseConditionAction` Passthrough	Passthrough
`ConditionPriority`	Priority
Link	Link; cross-conversation links supported
`Sequence`, `Response Menu Sequence`	The cutscene sequence for the line / for the response menu
Custom fields	Fields on the entry, with their `Type`

The preflight

Level	Finding	Why it matters
Error	Two assets whose names clean to the same Lua key (two actors called `Guard`; `Guard-1` and `Guard 1`)	Dialogue System keys its Lua tables by cleaned name. The second silently overwrites the first.
Warning	An asset with no `Name`	It will have no Lua key at all.
Warning	An item with no `Is Item` field	ChatMapper keeps items and quests in one collection; `Is Item` is how Dialogue System tells them apart. `True` = item, `False` = quest.
Warning	A `\|` inside a bracketed tag	Dialogue System splits lines on `\|` before parsing tags and tears the tag in half.
Warning	A link with a `Filename` (cross-project link)	Unsupported; Dialogue System loads one database.
Warning	A condition that does not parse as the supported Lua subset	It may well be fine — Dialogue System runs real Lua — but verify it in Unity.
Summary	How many dialogue nodes have no `Sequence`	Not wrong, just a reminder.

Sequences

Sequence is Dialogue System’s own mini-language for what happens when a line plays — AudioWait(entrytag); AnimatorPlay(Talk) — and it is your field, not ChatMapper’s. Writers author it in the Inspector under Advanced once the template is applied; the simulator ignores it; the export carries it. Keep engine calls here rather than in UserScript, so the project still simulates in the editor and exports to other targets.

Lua

Dialogue System runs the same Lua environment: Variable["…"], Actor["…"], Item["…"], Location["…"], Conversation[id].Dialog[id] with SimStatus, and the name-cleaning rule (Menu Text → Menu_Text). Scripts written and tested in the ChatMapper simulator run unchanged. The relationship helpers (IncRelationship and friends) exist on both sides.

Media

Dialogue System reads Audio Files, Pictures etc. as fields but plays media through Sequences. The common pattern is an entrytag-based sequence (AudioWait(entrytag)) with audio clips named by conversation and entry ID. Ask the studio for files named <conversation>_<node>_<segment> (the ChatMapper Desktop Audio File Placer convention, e.g. 003_002_001.wav); the Voiceover Script CSV gives them the sheet with those numbers on every row. Ship the files with the Unity project, or unpack a CMPKG.

Localisation

Per-locale fields (de-DE, Menu Text de-DE) export as fields with type Localization; Dialogue System’s localisation support picks them up by that naming convention.

Round-tripping

Dialogue System’s exporter writes ChatMapper XML too, so a database edited in Unity can come back into ChatMapper Cloud (Import, drop the XML). Editor-only data — canvas positions, reviewer notes — does not survive the Unity leg; everything in the model does.

Troubleshooting

Symptom	Look at
A character’s lines appear under the wrong name	Lua key collision (the preflight error) or `Actor` unset on the node
A quest imported as an item, or vice versa	`Is Item`
A choice that ChatMapper shows plays automatically in Unity	The node has no `Menu Text`, or it is the only option and lacks `[f]` — both engines agree on this rule; check the runtime semantics
A line shows `[em1]` literally	Emphasis tags are plain text to Dialogue System; strip them in a custom UI, or avoid them in Unity projects
A condition never passes	Test it in the ChatMapper simulator’s Lua console first; if it passes there, the difference is in the Unity Lua environment (an undefined function)