Extending the format

The ChatMapper format is extended additively and never forked. Three rules are load-bearing for the whole ecosystem; everything on this page follows from them.

1. Custom fields. Add whatever you need to any Fields object. A consumer that does not know a field must preserve it, not drop it.
2. _editor. One top-level object for editor-only metadata. It is stripped from interchange exports and any consumer may ignore it. Nothing the project’s meaning depends on goes there.
3. Graceful degradation. A consumer that does not understand an extension must still produce a working project without it.

What this rules out: renaming canonical keys, changing a field value’s type away from string, or adding a top-level sibling to Assets that carries meaning.

Custom fields

Every asset, conversation and node has a Fields map. Add keys:

{
  "ID": 7,
  "Fields": {
    "Title": "Ferryman refuses",
    "Actor": "2",
    "Dialogue Text": "No token, no crossing.",
    "Sequence": "AnimatorPlay(Shrug); Delay(1.5)",
    "vo_take": "ferry_07_b",
    "cutscene_id": ""
  }
}

Values are strings. Booleans are "True" / "False"; lists of files use the [a;b] bracket form (see the data model).

This is exactly how the existing ecosystem works: Dialogue System’s Sequence, Response Menu Sequence and Is Item; the *_raw provenance fields every importer writes; the ai_* fields below. No schema change, no version bump, and the project still opens in every other ChatMapper tool.

Field templates — so writers fill them in

A custom field the writer has to remember to add is a field that is usually missing. Register it as a custom field template instead: Details → Custom field templates in the editor, per kind (dialogue nodes, actors, items, places, variables, conversations). Every new object of that kind then carries the field with its default value, and the Inspector shows it under Advanced. Each definition has:

Property	Meaning
Title	The field key.
Default value	Written into new objects.
Type	Text, Multiline, Number, Boolean, Files, Actor, Item, Location, Localization. Controls the editor widget and the Type attribute in XML.
Hint	Tooltip for writers. Becomes the XML Hint attribute.
Include in XML export	Off to keep an editor-only field out of the XML (Desktop’s DoExport).
voice (Files fields on nodes only)	Marks the field as an alternate voice rendition of Audio Files.
options (Text fields only)	A comma-separated list of allowed values. The Inspector shows a dropdown; the stored value is still a plain string. Editor-only: it has no XML counterpart.

Templates and their metadata live in _editor.templates and _editor.fieldMeta; the values they produce live in Fields and export everywhere.

Add performance fields in the same panel registers Expression, Expression_intensity, Gesture, Mood and Pose on nodes, and Mood, Pose and Expression_palette on actors. They are ordinary string fields. Their dropdowns are filled from the performance vocabulary for the project’s enabled targets, with no option list of their own. A consumer that does not perform them ignores them; see performance cues for the inline form and the rules.

The editor ships a built-in Unity — Dialogue System template that adds Sequence and Response Menu Sequence to nodes and Is Item to items.

Reading custom fields in your importer

Treat Fields as an open map. Read the keys you know; carry the rest through unchanged if you ever write the project back. Coerce at the boundary ("True" → true, "3" → 3) and never write non-string values.

_editor

Everything that only the editor needs. Present in the stored project and in ChatMapper JSON as saved by the editor, but stripped from every interchange export (the JSON export, XML, Yarn, the players). Keys you may meet:

Key	Holds
positions	Canvas coordinates per conversation per node.
layoutDir, autoLayout, collapsed, edgeFlow, nodeColors, showNodeIds	Canvas display state.
templates, fieldMeta	Custom field templates and per-field type / hint / export / rendition flags / option lists.
languages	Additional localisation locales.
emphasis	The four [emN] style slots.
notes, reviewStatus	Reviewer notes and review status per node, keyed convId:nodeId.
styleGuide, media	Art and audio direction for generated media.

A consumer may ignore all of it. A producer that generates ChatMapper JSON should omit it entirely and let the editor lay the graph out.

In XML, some of this has a native home: reviewer notes and status are inline on each <DialogEntry>, and field Type / Hint are attributes on each <Field> — see ChatMapper XML.

The ai_* fields

The editor’s AI features store their authoring data as ordinary custom fields, so they travel with the project and degrade to nothing in a runtime that does not use them:

Field	On	Meaning
ai_gate	node	"True" marks an AI conversation gate.
ai_gate_prompt	node	The character’s persona and situation for the gate.
ai_gate_guardrails	node	Hard rules for the character.
ai_gate_max_turns	node	Turns before the fallback menu is offered (default "8").
ai_outcome	node (child of a gate)	The rubric an evaluator scores the transcript against.
ai_voice_id	actor	Provider voice ID used for generated audio.
ai_video_avatar_id, ai_video_voice_id	actor	Provider IDs for generated avatar video.

A runtime that wants to drive gates itself has everything it needs: the gate node’s children are the exits, each with a rubric and a Menu Text fallback; the editor’s own implementation uses two model calls per turn (actor in persona, evaluator against the rubrics) and fires an outcome at ≥ 0.7 confidence. A runtime that does not is expected to present the children as an ordinary menu — which is why authors are told to keep the Menu Text on outcome nodes.

Provenance fields from importers

Every importer preserves what it could not translate:

Field	Written by
twine_markup_raw	Twine — macros and markup stripped from a passage
arcweave_script_raw, arcweave_components, arcweave_attr_<name>	Arcweave — untranslated arcscript, attached components, attributes
articy_script_raw, articy_id	articy:draft — untranslated scripts, the source object ID

They are ordinary custom fields, so your pipeline can read them, and a writer can search for _raw to finish the translation by hand.

Versioning

Version at the top of the document records the schema version of the tool that wrote it ("1.5.1.0" is current). It is informational. A consumer should accept any value and rely on the additive rules above rather than on the number.