ChatMapper for game developers
This manual is for developers and narrative designers who need branching conversation data — something your engine loads, your writers can edit without you, and your build pipeline can consume.
ChatMapper Cloud is a collaborative web editor over a mature, well-documented dialogue format. It is a companion to your engine, not a replacement for it: Unity and Unreal own simulation and rendering; this owns the authoring, the validation and the exports.
It has two sections. Read the one that describes you.
1. Start here — new to ChatMapper
Section titled “1. Start here — new to ChatMapper”Start here — new to ChatMapper
Read this if you have never used ChatMapper. It covers the data model, the traversal semantics you must implement (or that your runtime already implements), the Lua host API, the editor workflow, and every export route into an engine.
2. Migrating from ChatMapper Desktop
Section titled “2. Migrating from ChatMapper Desktop”Migrating from ChatMapper Desktop
Read this if your team already has .cmp / .cmpkg / XML projects from the
Windows Desktop app and a pipeline built around them. It covers getting those
projects in, what is bit-identical, what changed, and how to keep your existing
Unity or custom importer working unchanged.
The short pitch, in pipeline terms
Section titled “The short pitch, in pipeline terms”| You want | Route |
|---|---|
| Unity, with Pixel Crushers Dialogue System | Export ChatMapper XML — Dialogue System imports it natively. A Unity export preset adds preflight lints. |
| Yarn Spinner | Export .yarn — nodes, options, and the translatable subset of the Lua. |
| Your own runtime | Read the canonical JSON. Stable, documented, and shipped with a dependency-free reference parser. |
| Unreal / Godot / anything else | Same JSON. The format is engine-neutral; the traversal rules are specified. |
| A playable build with no engine at all | Export a single self-contained HTML file, or a SCORM 1.2 / xAPI package. |
| To get out of articy:draft, Arcweave or Twine | Import them, with a report of everything that did not map cleanly. |
Ground rules worth knowing up front
Section titled “Ground rules worth knowing up front”- The format is never forked. Extensions are additive: custom fields that
older tools ignore, and an
_editorobject that is stripped from every export. Anything you write into aFieldsobject survives a round trip. - Values in
Fieldsare always strings —"True","30","[]"— whatever the field’s declared type. This trips up every first-time consumer. - Variables are keyed by name, not ID. XML has no variable ID at all.