Start here — new to ChatMapper

This section assumes you have never used ChatMapper before. By the end you will have edited a working scenario, added your own branch, played it in the browser, wired it to bots in a LearnBrite space, and published it.

Nothing here requires the Windows Desktop app. If you do already use Desktop ChatMapper, read Migrating from ChatMapper Desktop instead — it covers the same ground faster and tells you what changed.

1. The five words you need

ChatMapper models a conversation as a graph, not a script. Five terms carry almost everything:

Term	What it is
Project	One scenario file. Everything below lives inside it.
Conversation	One branching tree — typically “the talk with the receptionist”. A project holds many.
Node	One beat: a line someone says, or a choice the player picks. Nodes are the boxes on the canvas.
Link	An arrow from one node to the next. A node with several outgoing links is a branch.
Actor	A character. In LearnBrite an actor is usually a bot standing in the space.

Two more you will meet soon: variables (remembered facts, like trust or hasBadge) and conditions (a line only plays when a variable says so).

Every conversation starts at a root node called START. START is structural — it holds no dialogue, it just points at the first real line.

How a node becomes a line or a choice

A node has two text fields that matter most:

Dialogue Text — what the character says out loud.
Menu Text — what the player sees on a button.

The runtime decides between them by counting children. If a node has one child, that child plays automatically. If it has two or more, the player is shown a menu built from each child’s Menu Text. That is the whole branching mechanic: add a second child and you have created a choice.

Go to app.chatmapper.com/login. You can sign in with

email and password,
an emailed sign-in code, or
Continue with LearnBrite, if your organisation has LearnBrite single sign-on enabled.

If you are not already signed in to LearnBrite, you do not need to go through the LearnBrite Dashboard first. Go straight to app.chatmapper.com/login and choose Continue with LearnBrite — you will be sent to LearnBrite to sign in, then returned to ChatMapper with your LearnBrite account connected.

The first time you sign in, ChatMapper creates a workspace for you automatically and offers three ways to start:

The working example (recommended) — a small complete scenario, ready to edit.
A blank project.
Import an existing file — a .cmp, .cmpkg, .xml or .json from Desktop ChatMapper, or a spreadsheet, Twine, Arcweave or articy:draft export. For spreadsheet formatting, see Import a conversation from CSV or Excel.

Take the working example. Editing something that already runs is much faster than staring at an empty canvas.

A workspace holds projects, and can hold teams. Members have one of four roles — Owner, Admin, Editor, Viewer — where Viewers get a read-only editor (you will see a view only badge in the toolbar). Renaming your workspace and inviting people can wait; it is all under Workspace settings.

3. Your first ten minutes

A guide strip appears across the top of the editor with three steps. Do them in order — it is the shortest path to understanding the tool.

Change a line

Double-click a node’s dialogue text directly on the canvas and type. Enter commits, Esc cancels. Alternatively, select the node and edit Dialogue Text in the Inspector on the right, where you also get the Actor, the Menu Text and everything else.

There is no Save button to hunt for: the project autosaves a couple of seconds after you stop typing. The toolbar button on the right shows Saved / Save / Saving… so you always know where you stand.

Add a second path

Select a node and press Tab to add a child, or drag from the node’s handle onto empty canvas. Now do it again on the same parent so it has two children. Give each child a Menu Text — “Ask for their badge” / “Wave them through” — and you have built a branch.

Useful while building:

Key	Action
`Tab`	New child of the selected node
`Enter`	New sibling
`Home`	Jump to the conversation root
Arrow keys	Move between nodes
`Ctrl`+`↑` / `↓`	Reorder a node among its siblings (this is menu order)
`Ctrl`+`Z` / `Ctrl`+`Y`	Undo / redo
`Ctrl`+`F` / `Ctrl`+`H`	Find / find and replace across the project
Double-click canvas	New node

Preview it

Press ▶ Simulate. The simulator plays your conversation the way a learner will see it: lines appear, choices become buttons, variables update. You can step Back and Forward through the run, restart, and try the other branch without touching the canvas.

That loop — edit → branch → simulate — is the job. Everything else in this manual is refinement.

4. The editor, one panel at a time

Toolbar (top). Add Node / Add Group, undo/redo, the Layout ▾ menu, Validate, ▶ Simulate, History, Notes, the ✦ AI panel (if enabled), search, Import, Export ▾, and Save. When you are signed in through LearnBrite you also get the LearnBrite mode checkbox and the Publish to LearnBrite button.

Sidebar (left). Project settings (title, author, description, language, a project-level Lua script), your Conversations list, and the asset lists: Actors, Items, Locations, Variables. This is where you create characters and the variables your conditions test.

Canvas (middle). The graph. Drag nodes, drag from a node handle to another node to link them, right-click for context menus, and use the minimap to get around. Click a link and you can insert a node into the middle of it.

Inspector (right). Everything about the selected node: Title, Actor, Conversant, Menu Text, Dialogue Text, Parenthetical, media slots, node colour, whether it is a group node, its Conditions and User Script (Lua), custom fields, reviewer notes, and — in LearnBrite mode — its LearnBrite actions.

Layout ▾ is worth a look early. It flips the graph between left-to-right and top-to-bottom, toggles flow animation and per-node colours, collapses or expands subtrees, and switches Structured layout on or off. Structured layout keeps nodes in tidy story columns automatically; turn it off when you want to place nodes by hand.

5. Making the story actually branch

Choices

As above: two or more children with Menu Text. Order them with Ctrl+↑/↓.

Group nodes

A group node presents its children as the choice set. Use it when you want a labelled decision point in the graph rather than choices hanging directly off a line of dialogue. Groups count as branching for validation purposes.

Loops, merges and jumps

Nothing says a link has to go to a new node. Link back to an earlier node to loop (a hub you return to after each question), or link several nodes into one to merge paths back together. You can also link into a different conversation — useful for “and now go talk to the manager”.

Variables and conditions

Create a variable in the sidebar (Variables), then:

Set it in a node’s User Script:

Variable["trust"] = Variable["trust"] + 1
Variable["hasBadge"] = true

Test it in a node’s Conditions:
```
Variable["trust"] >= 2
```
A node whose condition is false is skipped. That is how you make later dialogue react to earlier choices.

The scripting language is Lua, and the simulator runs real Lua — so if it behaves in the simulator, it behaves at runtime. You do not need to learn much Lua: assignment, comparison, and / or / not covers the great majority of training scenarios.

Inline markup in dialogue

These tags live inside the text itself and are understood across the toolchain:

Markup	Meaning
`\|`	Sentence split — one node, two successive lines.
`[em1]…[/em1]` … `[em4]`	Emphasis spans; colour, style and label are set per project in the sidebar. There are buttons for these on the text fields.
`[var=Name]`	Replaced by the variable’s current value when displayed.
`[?Name]` / `[x=?Name]`	Ask the player to type something and store it in `Name`. The simulator pauses and shows an input box.
`[f]`	On Menu Text: force a menu even when this is the only option.
`[a]`	On Menu Text: marks an action line rather than a spoken one.
`[pic=N]`, `[pica=N]`, `[picc=N]`	Swap the displayed image mid-line.

6. Check your work: validation

Press Validate at any time. The validator is advisory and continuous, and it catches the things that silently break a scenario later:

duplicate IDs and broken or orphaned links,
nodes that can never be reached,
conditions referencing variables that do not exist,
links pointing at a conversation that was deleted,
a spoken line with no Actor assigned.

Errors block; warnings are advice. Fix errors before you publish.

7. Actors and bots

An Actor is a character in the story. In a LearnBrite space each speaking actor is a bot standing on a hotspot, and needs two extra values (they appear on the actor in the sidebar once LearnBrite mode is on):

Field	What to put in it
Bot ID (`avatar_externalId`)	The bot’s ID from your LearnBrite avatar library at bots.learnbrite.com. ChatMapper cannot invent these — pick from your account, or paste the ID.
Starting hotspot (`avatar_spotTag`)	Where the bot stands: `hotspot1` … `hotspot5`. By convention `hotspot0` is the learner, so give bots 1 and up.

When ChatMapper has your live LearnBrite context (see below), both fields become pickers listing the bots and hotspots that actually exist in the space, instead of free text you have to get right by hand.

8. LearnBrite mode

Tick LearnBrite mode in the toolbar. This is a per-project switch that turns on everything space-specific:

the LearnBrite fields on actors,
the LearnBrite actions list in the node inspector,
LearnBrite readiness checks in the validator,
the Publish to LearnBrite button.

It changes what the editor offers you; it does not fork your project. A project with LearnBrite mode on is still ordinary ChatMapper JSON.

What LearnBrite mode adds when you export

On export, the LearnBrite profile wires up the runtime plumbing for you:

each conversation’s bot gets an onclick of playConversationId so clicking the avatar in the space starts that conversation;
the conversation you nominate as the autostart gets Autoplay: True, the rest get False;
the START node gets the voice-sync boilerplate that matches the learner’s chosen TTS voice;
the autostart conversation gets a first [f]Start click gate.

That last one deserves an explanation, because it looks strange on the canvas. Browsers refuse to play audio or speech until the user has clicked something. The autostart conversation therefore needs one button between START and the first spoken line — that click is the permission. Conversations you trigger by clicking a bot already have their gesture (the click on the bot), so they get no gate. If the validator warns that your autostart conversation has no [f]Start gate, this is what it means.

LearnBrite actions on a node

With LearnBrite mode on, any node can carry an ordered list of actions that fire when the node plays. Add them in the Inspector; each action names its parameters and the required ones are checked by the validator. The catalogue covers things like:

show a notification (success / reward / warning / error / info),
enable or disable a hotspot,
set a task’s status, give an item or change its status,
set a runtime variable, optionally propagated to other participants,
make a bot show an emoji, or show/hide a bot,
show, hide, transition or set a field on a named 3D object,
play a sound or background audio, set volume,
move the camera in or out,
run custom JavaScript, or call a runtime action by name for anything newer than this catalogue.

Unknown action names and extra parameters are preserved rather than discarded, so a project authored against a newer runtime survives a round trip through ChatMapper.

9. Publishing into a space

Click Publish to LearnBrite. The panel asks for two codes:

the Space code — which space this scenario runs in,
the Scenario code — which Dashboard scenario this project deploys to.

You can also record hotspot names, task shortcodes and object names here to feed the pickers in the editor. If you signed in through LearnBrite, refresh context pulls those lists live from your account instead: the bots, hotspot spotTags, decorated 3D objects and gamification tasks that really exist.

The safe publishing loop is:

Check deployed JSON — reads what is currently live on the Dashboard, read-only, and shows a summary plus whether it matches your local version.
Optionally Import into editor — pulls the deployed version into ChatMapper (as an unsaved change, covered by normal history), when someone changed it outside ChatMapper.
Publish ChatMapper version — sends your saved project to the Dashboard. The Dashboard verifies you own the scenario, backs up the previous JSON, bumps the revision and clears its caches.
Reload space — opens or refreshes the space tab so you can test it.

If someone else published between your check and your publish, you get a revision conflict rather than a silent overwrite: check again, look at what changed, then publish.

Your media travels with the publish

Audio, images and video attached to nodes and actors are uploaded to the space automatically as part of publishing — you do not copy files anywhere by hand. It is efficient about it: only files the space does not already hold are transferred, so republishing after a text edit uploads nothing, and re-recording one line uploads one file.

The panel tells you what will happen before you commit: how many files, their total size, and — before the upload starts, not after it fails — anything that cannot be delivered:

a file larger than LearnBrite accepts (25 MB per file),
a file in a format LearnBrite will not serve (stick to normal audio, image and video formats — .mp3, .wav, .png, .jpg, .mp4 and friends),
a reference to a file this project no longer has.

If your Dashboard does not support media delivery yet, the panel says so plainly: publishing then sends the script only, and audio will not play in the space until either the Dashboard is updated or you deliver media the manual way (a CMPKG upload).

The manual fallback

You never have to use the bridge. Export ▾ → LearnBrite JSON (or the panel’s download button) gives you a conversation.json that you upload with the Dashboard’s normal scenario upload control. Same result, more clicks.

Launching from the Dashboard

Dashboard scenarios have an Edit in ChatMapper link. It opens ChatMapper with the scenario — and the space, if one is selected — already linked, so you skip the code entry entirely.

10. Testing

Test in this order; each step is cheaper than the next.

Simulator — logic, branching, variables, conditions, wording. Use the step history to walk paths, and the Lua console to poke at variables mid-run.
Validate — structure plus the LearnBrite readiness checks (bots without IDs, no autostart conversation, a missing click gate, action parameters).
The space itself — publish, reload, and click through it. This is the only place that proves voices, bot placement, tasks and 3D objects.

11. Working with other people

Presence — you can see who else has the project open, live in the toolbar.
Autosave and conflicts — if the project changed underneath you, a banner offers Discard mine & reload or Overwrite with mine. Nothing is lost silently.
History — every save snapshots a revision. Browse them, diff them, restore one.
Reviewer notes — leave a note on any node, mark it resolved, and set a review status. Nodes with notes get a badge on the canvas. The Notes panel lists them all, and you can export them as CSV for a review meeting.
Roles — Viewers get a read-only editor, which is exactly what you want for subject-matter experts who should comment but not edit.

12. Localisation

Add languages under project settings and each translatable field gains a per-language version. The language dropdown in the toolbar switches what the canvas, inspector and simulator display, so you can proofread a translation in place.

13. Alternate voices (renditions)

This is the short version — the voice renditions guide walks through it with more care.

One spoken line can have more than one recording — a second voice for the same words. LearnBrite’s classic use is a male and a female voice track, but the mechanism is neutral: a calmer read, a different casting, whatever your scenario needs. The learner’s runtime picks which one plays; your script stays identical.

Setting it up is three steps:

Register the field. In the sidebar under Custom field templates → Dialog nodes, add a field called Voice 2 (any name works), set its type to Files, and tick voice. That checkbox is the registration — ChatMapper never guesses that a field holds alternate audio from its name.
Attach the takes. On each node, the Media tab now shows a Voice 2 slot next to Audio files. Attach one file per sentence, in the same order as the primary audio — first alternate pairs with first primary, and so on. Use the same file format as the primary (an .mp3 primary needs an .mp3 alternate).
Publish. ChatMapper arranges the files the way the LearnBrite runtime expects — the primary and its alternate share a filename, in different folders — and uploads both.

Two rules keep this stress-free:

A missing alternate never blocks publishing. If Voice 2 covers only some lines, the space simply plays the primary voice for the rest. The panel tells you exactly which lines fall back, at check time and again after publishing — it is allowed, but never silent.
A broken pairing is skipped, not published. A .wav alternate against an .mp3 primary, or an alternate with no primary to pair with, is reported and left out rather than deployed broken.

Which voice actually plays is chosen per actor: once a rendition is registered, each non-player actor gains a Spoken voice selector in the Actors panel — pick the rendition (or Primary voice) and ChatMapper wires the runtime field for you. A space script can also switch it at runtime, which is how the classic learner-profile setups work. If an actor points at a voice folder this project does not publish, the publish check says so.

Hearing it in the space

Nothing but the space itself proves audio, so after setting a rendition up, run this loop once. It takes about five minutes.

Attach and check. Give at least one node a primary recording and a Voice 2 alternate. Open Publish to LearnBrite and click Check latest — the media summary should count both files, and the warnings should be quiet (or say exactly which lines will fall back).
Hear the primary. Leave every actor’s Spoken voice on Primary voice. Publish, Reload space, click through to your line — remember the space plays nothing until the first click. You should hear the primary take.
Hear the alternate. In Assets → Actors, switch the speaking actor’s Spoken voice to Voice 2. Publish again (the audio is already uploaded, so this sends only the script) and reload the space. The same line should now play the alternate take.
Hear the fallback. If some lines have no alternate, play one of those too: it should fall back to the primary voice, exactly as the publish warnings listed.

If step 3 plays the primary anyway, check the actor’s Spoken voice survived the publish (re-check shows the deployed version) and see the troubleshooting table below. If it plays nothing, the alternate file did not reach the space — the publish result names anything that was skipped.

For localised audio, repeat step 2–3 with the space switched to that language: the audio_speech_es recording should play, and with a Voice 2 es attached and the actor on Voice 2, its alternate should.

Localised audio composes with renditions: audio_speech_es on a node carries the Spanish recording for learners in Spanish, and a rendition field named with the same locale suffix — Voice 2 es — carries the Spanish alternate takes. Register both as Files fields (the locale lane needs no voice tick; the alternate does) and the same Spoken voice choice then works across languages.

14. Optional extras (Labs)

Some capabilities ship behind per-workspace Labs flags, toggled in workspace settings. Ask your workspace admin if you do not see them:

Media attachments — upload or link audio, video and images on nodes and actors, with preview and playback; the simulator plays them in order.
AI copilot — a chat panel that drafts and restructures scenarios. It never edits directly: it proposes changes as approval cards, and applying them snapshots a revision first and lands as a single undo step.
Generative media — generate a node’s audio from its dialogue text, or an actor portrait, using your own provider keys.
AI conversation gates — a node where the learner free-chats with the character; child nodes are the possible outcomes, judged against rubrics you write. Menu Text on those children stays as the non-AI fallback, so the scenario still works everywhere.
Voice conversations — talk to the copilot instead of typing.

15. When something is wrong

Symptom	Likely cause
Nothing is spoken when the space loads	The autostart conversation has no `[f]Start` gate. Browsers block audio until a click.
Clicking a bot does nothing	That actor has no Bot ID, or its conversation is not wired to it. Validate in LearnBrite mode.
The bot is in the wrong place, or two bots overlap	Duplicate or missing `avatar_spotTag`. Remember `hotspot0` is the learner.
A branch never appears	Its condition is false, or the parent has only one child so no menu is built. Step through the simulator and check the variables.
The space still shows the old script	You reloaded without publishing, or the publish hit a revision conflict.
Publish says the revision changed	Someone published after your check. Re-check, review, publish again.
Audio plays in ChatMapper but not in the space	Your Dashboard may not support media delivery yet — the publish panel says so when checking. Otherwise re-publish: media uploads before the script, so a completed publish always has its files.
The alternate voice never plays	The actor’s `audio_speech_urlPrefix` is unset or does not match the rendition folder (e.g. `voice-2/`), or those lines fell back — the publish result lists every line missing an alternate.
A choice with one option plays straight through	Expected. Prefix its Menu Text with `[f]` to force the menu.

Migrating from ChatMapper Desktop — if you inherit Desktop projects from colleagues.
Game developers manual — if the same scenarios also need to reach an engine.