Developer documentation

This section is for the person who wires ChatMapper output into an engine, or who hands the editor to a writing team and consumes what comes out. It assumes no ChatMapper knowledge and no particular engine.

If you are a writer, the getting started manual is the one you want; come back here for the export formats.

Pick your route

You are building	Start with
A Unity game with Pixel Crushers Dialogue System	Unity integration
Anything using Yarn Spinner (Unity, Godot, Unreal, web)	Yarn Spinner
Your own runtime — Godot, Unreal, a web game, a chatbot, a proprietary engine	Building a custom runtime on top of the JSON format
A web playtest build, a review link, a QA harness	Standalone HTML player and its JavaScript API
Training content for an LMS	SCORM 1.2 and xAPI
A migration from Twine, Arcweave or articy:draft	Importers
A pipeline that reads or writes ChatMapper files itself	Data model, JSON format, XML, CMPKG

The three things to know

1. A project is one JSON document. Five asset collections (actors, items, locations, variables, conversations); each conversation is a graph of dialogue nodes joined by links. Every field value is a string. That is the whole data model, and it is the same model the Windows Desktop app has always used, so the ecosystem around it — Unity importers, the XML serialisation, the .cmp files — is stable.

2. The runtime contract is small and exact. From a node: collect the link targets, drop the ones whose Lua condition is false (unless they passthrough), keep only the best priority, expand group nodes, and then play, present a menu, or end. The runtime semantics page is normative; the ChatMapper simulator, the HTML player and the reference parser all implement it and are tested against each other.

3. The format is extended, never forked. Add custom fields; put editor-only metadata in _editor; degrade gracefully. Your engine’s fields (Sequence, cutscene_id, vo_take) ride along in every export without a schema change — see Extending the format.

Reference

• Data model — the shapes, in prose.
• JSON format — the normative interchange specification, with a complete fictional example.
• Runtime semantics — traversal, menus, status tracking.
• Lua scripting — the host API, name cleaning, the supported subset.
• Inline markup — |, [f], [var=…] and friends.
• Extending the format — custom fields, _editor, ai_* fields, field templates.
• ChatMapper XML — the Desktop serialisation and where it differs from JSON.
• Validation rules — what a conforming document must satisfy.
• Export catalogue — every format, its file, its group, its warnings.
• Importers — the mapping from each source tool.

Downloads

File	What
example-scenario.json	A complete, minimal, entirely fictional project. It is covered by a test in the ChatMapper repository that asserts it validates with zero errors.
reference-parser.ts	A single dependency-free TypeScript file that parses and walks the format. MIT licensed. Compiles standalone under tsc --strict.
example-scenario.xml	The same project as ChatMapper XML — what the Desktop app and Unity read.
example-scenario.yarn	The same project through the Yarn Spinner exporter.
example-scenario-player.html	The same project as a standalone HTML player. Open it in a browser.

Is there an API?

Not a public one yet. ChatMapper Cloud’s integration surface today is files: the exports the editor produces and the imports it accepts. Every export is deterministic from the saved project, so a pipeline can be built on “export, commit, build” without surprises. If your team needs a scripted route into or out of the editor, tell us what it should look like.

Compatibility promise

• Canonical keys never change meaning. New capabilities are additive.
• A document produced by any ChatMapper version opens in any later one.
• Custom fields a consumer does not recognise are preserved, not dropped.
• _editor may always be ignored.
• The XML attribute misspelling FalseCondtionAction is part of the format and will not be “fixed”.