Table of contents
1. Downloading and importing the file
To start using ChatMapper, the Scenario Template can be downloaded. It is recommended to use this file to start a new project, especially in the case of ChatMapper beginners, as it comes with Actors, custom fields, and conversations already set up.
After clicking on the link, a “Download” window will appear – click Save.
Note that ChatMapper is a Windows-only tool – if you are using macOS or a Linux distribution, you will need to run it in a Windows VM (such as Parallels on macOS, or Wine on Linux). This guide assumes you are using Windows.
There are two types of files commonly encountered when working with ChatMapper.
CMP files do not bundle external assets, and are suggested for most projects (most assets, such as 3D models, can be imported directly into the LearnBrite platform).
It is however possible to export a bundled version of the CMP which will include the assets imported into the ChatMapper project as well – there are “CMPKG” (ChatMapper Package) files, like the Scenario Template.
Open the file after downloading – ChatMapper will import it, and will ask to open the project. Click Yes.
If you have already imported the project in the past, ChatMapper will ask to overwrite the existing import first. In that case, click Yes, and then open the project when asked.
By default, the project will be saved in the following folder:
C:/Users/USERNAME/Documents/Chat Mapper/Imported Packages
2. Using ChatMapper
A detailed guide on ChatMapper can be found at the LearnBrite Academy website.
The Template has been set up with Actors and Conversations.
The project includes four Actors: Player, Narrator, Jane, and Michael.
Tok see the details of each actor and modify them, click on their name on the left pane, and their details will be displayed on the Properties pane (on the right by default).
Both Player and Narrator are special actors.
- Player, as the character of the user, must have isPlayer checked and isNPC unchecked. In the screenshots some additional details are defined, such as the player’s Voice (UK English Male).
- Narrator is also a special actor, representing the “camera” in the experience. To work as such, it must have no avatar_externalId, and both isPlayer and isNPC must be unchecked. Whenever a dialogue node has the Conversant set to Narrator, the avatar who is speaking will look directly at the camera (it will otherwise look at the Conversant’s avatar). If Narrator is set as the Actor of a node, the camera will not move from its previous position.
Jane and Michael are normal actors. Taking Jane as an example, here are all her properties and what they do:
- Name: the actor’s name, also used within Scenario (it is displayed above a character’s head).
- Pictures: this is an image used purely for decorative purposes within ChatMapper, to show an actor’s image in a conversation.
Any image can be used, though it should be placed within the same folder as the .cmp file (in the case of the template project, “C:/Users/USERNAME/Documents/Chat Mapper/Imported Packages/Scenario Template”).
If placed outside of that folder, it will not be included correctly in any .cmpkg (ChatMapper Package) exported.
- Description: used only in ChatMapper – will fill the tooltip that shows when hovering over a character, useful to show some additional information about the actor that is not critical.
- IsPlayer: this should be unchecked for every Actor that is not the user’s.
- onclick: the action to trigger when clicking on the avatar within the 3D environment. Please refer to the Scenario Actions guide for more details.
Jane and Michael’s onclick do something straightforward: Jane’s launches the conversation called “Conversation with Jane”, and clicking on Michael starts “Conversation with Michael”.
- avatar_externalId: this is an ID that can be obtained from https://app.learnbrite.com/bots , where you can create your own bots.
- avatar_spotTag: name of the hotspot where the actor should be placed within the 3D environment.
- isNPC: is checked (as it should for every character that is not the user’s).
- isPIP: sets the actor to appear as a picture-in-picture avatar. When the actor is speaking, they will appear in the bottom-right corner (as opposed to the camera moving and focusing on them), and disappear when the first node with a different actor is played.
- Voice: the actor’s voice, from ResponsiveVoice’s catalog.
- Voice_parameters: additional parameters for the actor's Voice (pitch, rate of speech, volume). See Speech, SFX, Ambient > How to Make Actors using the Same Voice Sound Different
- avatar_height: the height of the camera when the actor is speaking. When left empty, the camera will adjust its height automatically.
Conversations are closed by default when a CMPKG file is imported.
To open one, double-click on it.
In the project are two conversations, “Conversation with Jane” and “Conversation with Michael”. You can open each by going to the “Conversations” tab in the left pane and double-clicking on any of the two.
If at any point you either double or single-click on the conversation, its properties will appear in the right pane, in the same way Actor properties do. A couple of different fields are available for conversations out of the box:
- Title: the conversation’s title. If multiple conversations are present (such as with the template) but either all or none are set to Autoplay, a list of conversation titles will appear for the user to choose which they want to start.
- Pictures: this is an image used purely for decorative purposes within ChatMapper, to show an image on the side of a conversation’s title in the “Conversations” pane. See the note on where to place the images in the same field within the “Actors” section.
- Description: a description of the conversation. Purely for descriptive purposes, it does not appear anywhere within a space.
- Actor: the main Actor of the conversation. It does not impact a scenario (any number of Actors can participate in a conversation), but can be useful to set for descriptive purposes.
- Conversant: the counterpart to the main Actor of the conversation. It does not impact a scenario (any number of Actors can participate in a conversation), but can be useful to set for descriptive purposes.
- Autoplay: if one (and only one) conversation has this checked, it will start automatically when the scenario is loaded.
- location: set to the only location available. Should generally be left unchanged.
- conversation_onend: sets the behaviour of the scenario when a conversation ends. Can be one of “stay” (which leaves the space in exploration mode, where one can move and look around freely), or “return” which shows a list of possible conversations to select.
- camera_animationTime: the amount of time (in seconds) used by the camera to move between one camera angle and the next (see “avatar_shot” in the Dialogue Nodes section). It’s set to 0 in the template, equivalent to a jump cut in movies.
- delay_enter and delay_exit: the amount of time (in seconds) to delay the start or the end of multiple nodes spoken by the same Actor. Best left to 0.
- choice_position: where to position choices. They will be in the center of the screen if this is left empty or an invalid value is used. Other possible values are “top” and “bottom”.
The conversation with Jane includes some helpful tips on using ChatMapper, as well as one of the most important interactive elements in dialogue: a choice (highlighted in ChatMapper using red, white and green nodes). All of this can and should be modified as needed.
When opening a conversation, a tree structure is shown, also known as the dialogue tree. Each of these dialogue nodes, when clicked on, also has its own properties.
If the same property is set for both a conversation and a dialogue node (for instance delay_exit), the value in the dialogue node takes precedence and will be used.
- Title: the node’s title, appears in the dark gray bar at the top of a node within the dialogue tree.
- Pictures: images used purely for decorative purposes within ChatMapper, to show an image within the dialogue node instead of the Actor’s (if set – if neither this nor the Actor’s image is set, a default icon will take their place). See the note on where to place the images within the “Actors” section.
- Description: a description of the dialogue node. Purely for descriptive purposes.
- Actor: who will speak the node. Other actors close enough will look at him or her while they are speaking.
- Conversant: the counterpart to the main Actor of the node, does not usually have an effect. If set to the Narrator if the speaking avatar should look directly at the user (see “Narrator” in the “Actors” section). It should be set to the avatar whose shoulder the camera rests on for OSL and OSR avatar_shot nodes (more on this below).
- Menu Text: if set, it will display a button. Multiple dialogue nodes at the same level, i.e. children of the same parent node, will create a group of choices (see relevant section in the ChatMapper Cookbook)
- Dialogue Text: the text that will be spoken by the Actor of the node. Can be separated by pipes | to split audio and closed captions in multiple “pieces”.
- Parenthetical: doesn’t appear within the spoken dialogue, but will appear before the Dialogue Text in Screenplay exports. It usually contains stage directions, or describes emotions (such as “nervously” or “with a broad smile”).
- Audio files: by default, LearnBrite uses text-to-speech, but audio files can be used as well. Audio files included within this field will be played instead of TTS. To synchronize them with captions, be sure to include a pipe (“|”) where each file stops. For example, if one audio file contains the text “Hello” and the second “how are you?”, to sync audio and captions the Dialogue Text should be “Hello|how are you?”
- Video files: unused, should be left untouched.
- choiceCaption: when set, a small header will appear above a choice list containing this text, very useful to create recaps of what was just said, or to repeat a question for a multiple-choice answer. This should be set in a child node (i.e. when a node has multiple children, to make it show it should be set within the children, not the parent). If multiple children have different choiceCaptions, the first will be used.
- avatar_shot: which camera shot to use for this dialogue node. Note that in 1st person and VR modes, camera control is left completely to the user, and logically this field will not appear to have an effect even if it is set. Can be one of:
- MS (the default)
- OSL (in this case and for OSR, Conversant cannot be the Narrator actor)
XLS (Extra Long Shot)
LS (Long Shot)
MLS (Medium Long Shot)
MS (Medium Shot)
MCU (Medium Close Up)
CU (Close Up)
BCU (Big Close Up)
XCU (Extra Close Up)
OSL (Over the Shoulder, Left) (2.9+)
OSR (Over the Shoulder, Right) (2.9+)
- camera_animationTime: see the same section within the “Conversation” part of this document.
- delay_enter and delay_exit: see the same section within the “Conversation” part of this document.
- choice_style: if left empty or set to “vertical”, choices will be grouped vertically. If set to “horizontal”, choices will be grouped horizontally. As with choiceCaption, this should be set for children, not parent node of a choice.
3. Uploading to Dashboard
3.1 Export the CMPKG
When the project is ready to be tested, go to File > Export > ChatMapper Package (CMPKG). This will create a package like the original Scenario Template one.
3.2 Create the scenario
The package can be uploaded directly on the LearnBrite Dashboard > Scenarios page.
On that page, click on Create a new Scenario, and fill in the form with a name for your scenario (it will not be visible to users, so it can be named as you prefer) and choosing the recently-exported CMPKG file. Click Create to upload the package file and create the scenario.
3.3 Create the space
On the Dashboard page, click on Create a new Space. In the next page you can choose one of the many environments included in the platform, as well as a name for the space (which is visible to users) and whether the space is a Virtual Meeting Room (i.e. if users are in a multi-user session, or in a single-user one). Create the space by clicking on Create Space at the bottom.
3.4 Assign the scenario to the space
In the list of spaces on the Dashboard homepage, click on the three vertical dots on the new space, and select Edit Space
At the bottom of this new page, click on Show advanced settings, and expand the section called Scenario. Then select the scenario you just created from the dropdown, and click Save at the bottom. You’re done!
You can now access your space by clicking on it on the Dashboard homepage. Enjoy!
We are sorry that this article was not useful for you!
Let us improve this article!
Tell us how we can improve this article?