Skip to content
ChatMapper Docs

Migrating from ChatMapper Desktop

This section is for authors who already build scenarios in the Windows ChatMapper Desktop app and are moving that work to ChatMapper Cloud, with LearnBrite as the destination.

Short version: the data model is identical, the editing model is the same tree you know, and the differences are mostly things the web adds — autosave, revision history, real-time collaboration, continuous validation and a publish path straight into a space.

Your projects come with you

Section titled “Your projects come with you”

Use Import in the toolbar. All of these are read directly:

FileNotes
.cmpDecrypted server-side. No Desktop install needed.
.cmpkgThe zipped variant.
.xmlDesktop’s XML save/export.
.jsonCanonical ChatMapper JSON.

Everything survives: conversations, nodes, links, actors, items, locations, variables, custom fields, conditions, user scripts, node colours, localisation, reviewer notes and emphasis settings.

Going the other way, Export ▾ gives you ChatMapper XML (opens in the Desktop app) and CMPKG + media — the project XML and JSON plus every attached media file, zipped as a .cmpkg you can hand to a Desktop user. There is one genuine gap: the web app does not write the encrypted .cmp format, so the Desktop-native round trip is XML-based rather than .cmp-based.

What is the same

Section titled “What is the same”

You will recognise all of this immediately:

  • Conversations, dialogue nodes, links, group nodes, root/START.
  • Actors, Items, Locations, User Variables — including their custom fields, with per-field types (Text, Number, Boolean, Multiline …) and the export this field flag.
  • Conditions and User Scripts in Lua, with the same Variable["name"] access.
  • Inline markup: | sentence splits, [em1]…[/em1] emphasis (the four project emphasis colours/styles/labels come across), [var=Name], [pic=N] / [pica=N] / [picc=N], [f] and [a] on Menu Text, and the runtime input prompt — Desktop’s [input=?Name] form and the bare [?Name] form are both accepted.
  • Keyboard tree building: Tab for a child, Enter for a sibling, Home for the root, arrows to move, Ctrl+↑/↓ to reorder siblings.
  • Node fields you rely on, including Delay SimStatus, False Condition Action and Condition Priority.
  • Reviewer notes and reviewer status, per node.

What is different

Section titled “What is different”

Files and saving

Section titled “Files and saving”

There is no Open/Save. A project lives in a workspace and autosaves. Every save writes a revision, so History replaces “save a copy before I break something”: browse revisions, diff them, restore one. If two people edit at once, a conflict banner offers Discard mine & reload or Overwrite with mine.

Save As is now clone the project from the project list.

Where things moved

Section titled “Where things moved”
DesktopChatMapper Cloud
File → Export XML / CMPKGExport ▾ (plus JSON, LearnBrite JSON, Unity preset, Yarn, HTML player, SCORM/xAPI, CSVs, RTF screenplay, SVG)
Tools → Simulate (F5)▶ Simulate in the toolbar
Tools → Check ErrorsValidate — and it also runs continuously
Find / ReplaceCtrl+F / Ctrl+H, project-wide
Overview windowAlways-on minimap
Collapse / Expand AllLayout ▾ → Collapse all subtrees / Expand all
MindFusion tree layoutLayout ▾ → direction, auto-arrange, structured layout lock
Project preferences → custom asset fieldsSidebar → field templates and per-field metadata
Emphasis tag setupSidebar → Dialogue emphasis

Layout behaviour

Section titled “Layout behaviour”

By default each conversation uses structured layout: nodes are placed in story columns and rows automatically and you cannot drag them around. Turn it off per conversation in Layout ▾ if you prefer Desktop-style freeform placement, then use Auto-arrange when the graph gets messy.

Things the web does better

Section titled “Things the web does better”
  • Validation is deeper. Duplicate IDs, unreachable nodes, orphan and broken links, undefined variables, cross-conversation link integrity, spoken lines with no Actor — plus platform-specific readiness profiles.
  • The simulator has step history and a Lua console. Walk back and forward through a run, branch differently from any step, and evaluate or assign variables live against the running state.
  • Collaboration is real. Live presence, roles (Owner / Admin / Editor / Viewer), and a genuinely read-only mode for reviewers.
  • Inline canvas editing. Double-click a node’s dialogue or menu text and type; Enter commits, Esc cancels.
  • Insert-between. Select a link, then insert a node into the middle of it.
  • Media has real storage. Attachments are uploaded and content-addressed rather than referencing paths on your PC — which is what makes a .cmpkg export portable.

Still Desktop-only

Section titled “Still Desktop-only”

Be aware of these before you retire your Desktop install:

  • Encrypted .cmp export (import works; export is XML/CMPKG).
  • Conversation LockedMode — not modelled; exported XML always says Unlocked.
  • File links from a node to an external .cmp.
  • Promote to primary link — the web has no primary/secondary link concept.
  • Reparent by dragging a node onto a new parent — delete and recreate the link instead.
  • Audio File Placer (bulk-assign audio files to nodes).
  • Excel import/export of per-asset worksheets — use the CSV exports, which open in Excel.
  • Sort assets by field, Cut, Select All, and the Conditions/Scripts snippet menus.
  • Word count report and Yack .dls/.dla export.

Now do the LearnBrite part

Section titled “Now do the LearnBrite part”

Everything above is format and editing. The reason to move to the web is the publish path, and it has no Desktop equivalent.

1. Sign in through LearnBrite

Section titled “1. Sign in through LearnBrite”

Use Continue with LearnBrite on the sign-in page. This is what enables the LearnBrite features; a plain email account can still author and export a conversation.json by hand, but you lose the live pickers and one-click publish.

2. Turn on LearnBrite mode

Section titled “2. Turn on LearnBrite mode”

The LearnBrite mode checkbox in the toolbar reveals the space-specific surface: bot fields on actors, the actions list on nodes, LearnBrite readiness checks in the validator, and Publish to LearnBrite. It is a per-project switch and it does not change your file format.

3. Give each actor a bot

Section titled “3. Give each actor a bot”

Each speaking actor needs:

  • Bot ID (avatar_externalId) — from your LearnBrite avatar library at bots.learnbrite.com. ChatMapper cannot generate these.
  • Starting hotspot (avatar_spotTag) — hotspot1–hotspot5; hotspot0 is conventionally the learner.

Once ChatMapper has your live account context these become pickers rather than free-text fields.

4. Understand the three runtime conventions

Section titled “4. Understand the three runtime conventions”

These are applied for you on export, but they explain what you will see:

  • The autostart conversation is marked Autoplay: True; the others False. Other conversations start when the learner clicks the bot, wired via an onclick of playConversationId.
  • The START node carries a voice-sync script so the character’s TTS voice matches the learner’s chosen gender.
  • The autostart conversation gets an extra first node — a [f]Start button between START and the first spoken line. Browsers will not play audio until the user has clicked something, and that button is the click. Conversations triggered by clicking a bot already have their gesture and get no gate.

Desktop’s Primary Location is not what the runtime reads: LearnBrite uses the conversation’s location field. Imported projects are handled, but if you hand- edited Primary Location in Desktop, check it after import.

5. Add LearnBrite actions where you need them

Section titled “5. Add LearnBrite actions where you need them”

Any node can carry an ordered list of runtime actions — notifications, hotspot enable/disable, task status, give item, set a runtime variable, bot emoji, show/hide a bot or 3D object, object transitions and field changes, play audio, camera in/out, volume, custom JavaScript, or a raw runtime action name for anything newer than the built-in catalogue. Required parameters are validated. Unknown actions and extra parameters are preserved on round trip.

This is the layer that has no Desktop analogue, and it is usually why a Desktop-authored scenario needs a pass after import.

6. Publish

Section titled “6. Publish”

Open Publish to LearnBrite, set the Space code and Scenario code, then:

  1. Check deployed JSON — read what is live now (read-only).
  2. Import into editor — only if the deployed version is newer than yours.
  3. Publish ChatMapper version — pushes your saved project; the Dashboard backs up the previous JSON and bumps the revision.
  4. Reload space — and test.

A revision conflict means someone published after your check; re-check and publish again. Nothing is overwritten silently.

The manual route still works: Export ▾ → LearnBrite JSON gives you a conversation.json for the Dashboard’s normal upload control.

From the other direction, Dashboard scenarios carry an Edit in ChatMapper link that opens the project with the scenario and space already linked.

A sensible first migration

Section titled “A sensible first migration”
  1. Import one small, finished Desktop project.
  2. Validate. Fix errors; read the warnings.
  3. Simulate it end to end and compare against what Desktop did.
  4. Turn on LearnBrite mode, assign bot IDs and hotspots.
  5. Validate again — now you also get the readiness checks.
  6. Publish to a test scenario code, reload the space, click through it.
  7. Only then migrate the rest.

Where to next

Section titled “Where to next”