Scenario Actions

The detailed guide on actions available within the platform. Actions described here apply to Scenario version 2.5 or above. If the action is only available from a certain version onwards, it will be indicated beside its name.

Triggering Actions from ChatMapper Dialogue

Triggering Actions from ChatMapper Scripts

Triggering Actions from Scenario onclick

Multiple actions within a single onclick

Delaying Actions

delayMs

delay

Conditional Actions

Properties

nid/nodeid

cnvid (conversation ID)

actorId

Modes

Conversation mode

Exploration mode

API

Common parameters

playNode

playConversationId

teleportActorToSpotTag

teleportPlayerToSpotTag

setSpotTagActive

setUserVariable

getUserVariable 2.15+

displayNotification

launchYammerFeed

callFunction

displayIframe

displayForm

exitConversation

openURLInNewWindow

playGesture

setAvatarLookTarget

fadeScene

forceCameraShot

playCustomNode  2.7+

lookAt 2.7+

setObjectVisible 2.7+

fadeObject 2.7+

navigateTo 2.8+

startTask 2.8+

completeTask 2.8+

getTaskStatus 2.8+

updateTask 2.8+

collectItem 2.8+

dropItem 2.8+

checkIfCollected 2.8+

getItemStatus 2.8+

setItemStatus 2.8+

playExplojis 2.8+

setAvatarMood 2.8+

setVideoboardControls 2.8+

playSFX 2.9+

playAmbient 2.9+

stopAmbient 2.9+

setObjectField 2.9+

displayImage 2.9+

setVolume 2.10+

changeMediaboardImage 2.11+

displayVideo 2.11+

setStatusMeterVisible 2.12+

setStatusMeterValue 2.12+

setAvatarOutfit 2.11+

playStatusMeterExploji 2.12+

getStatusMeterValue 2.12+

pauseConversation 2.12+

resumeConversation 2.12+

repeatAction 2.12+

stopRepeatingAction 2.12+

UI.openLocations 2.12+

UI.openAchievements 2.12+

UI.openShare 2.12+

UI.openParticipants 2.12+

UI.openSettings 2.12+

UI.openProfile 2.12+

UI.openContacts 2.12+

UI.openSideMenu 2.12+

UI.openAdditionalMenu 2.12+

UI.openAvatarCreator 2.12+

doNothing 2.13+

displayPoll 2.14+

displayPollResults 2.14+

UI.openQnA 2.14+

UI.displayDialInDetails 2.14+

sendUserToSpace 2.14+

startTimer 2.15+

pauseTimer 2.15+

resetTimer 2.15+

requestInput 2.15+

dropConferenceCall 2.15+

zoomInObject 2.15+

zoomOutObject 2.15+

avatarWalkTo 2.15+

displayMediaboard 2.16+

UI.setRaiseHand 2.16+

rollDice 2.16+

setSlideshowIndex 2.16+

Triggering Actions from ChatMapper Dialogue

Actions can be triggered directly from dialogue. The recommended convention is the following:

[action:"actionName", param1:"value", param2:"value"]

Scenario will also accept using spaces instead of commas, or equal signs instead of colons.

[action:"actionName"  param1:"value"  param2:"value"]
[action=
"actionName", param1="value", param2="value"]

Values should always be inside quotes, especially if they have spaces or special characters.

Triggering Actions from ChatMapper Scripts

These can be added into the Script Editor and Conditions panels in ChatMapper. They can also be used anywhere javascript calls can be used.

Note that all actions trigger at the same time if they are in the same script, not one after the other. In the example above fadeScene and the teleportActorToSpotTag all happen at the same time.

Triggering Actions from Scenario onclick

It is possible to add actions to the "onclick" property of an asset (where that is a mediaboard, a bot, an item, etc.). The field is accessible within the Editable Items List, or directly by editing an item by clicking on the cog icon while in Edit mode. If the onclick field is present, an action can be added (don’t forget to hit "Save" after!).

This has a special format called JSON, in which everything is wrapped in quotation marks, and "internal" quotation marks must be substituted with \"

{"action":"teleportActorToSpotTag", "actorId":"1", "spotTag":"hotspot2"}

Multiple actions within a single onclick

It is possible to trigger multiple actions on a single onclick. Note that all actions trigger at the same time, not one after the other.

The syntax is simple, it requires including all actions within square brackets, and separating each with a comma.

[ {action1}, {action2}, {action3} ]

In the following example,

  • Actor 1 is teleported to hotspot2, AND
  • A popup is displayed with title "Popup Title", the message "Hello world!" and an OK button

[ {"action":"teleportActorToSpotTag","actorId":"1","spotTag":"hotspot2"}, {"action":"displayNotification","message":"Hello!"} ]

Delaying Actions

You may want an action to happen a little after the node has started. You can achieve this with the delay attribute.

Example: play the yes gesture on the current actor after 2 seconds (2000 milliseconds)

There are two parameters available for specifying a delay:

  1. delayMs – takes a value in milliseconds, eg. 2000 milliseconds is 2 seconds
  2. delay – takes a value in seconds, eg. 2 seconds

delayMs

Dialogue

[action:"playGesture", name:"yes", delayMs:2000]

onclick

{"action":"playGesture", "name":"yes", "delayMs":"2000"}

Script

LB.Actions.playGesture({name:"yes", delayMs:2000});

Syntax

Dialogue

[action:"actionName", param1:"value", param2:"value", delayMs:"milliseconds"]

onclick

{"action":"actionName", "param1":"value", "param2":"value", "delayMs":"milliseconds"}

Script

LB.Actions.actionName({param1:"value", param2:"value", delayMs:"milliseconds"});


delay

Dialogue

[action:"playGesture", name:"yes", delay:2]

onclick

{"action":"playGesture", "name":"yes", "delay":"2"}

Script

LB.Actions.playGesture({name:"yes", delay:2});

Syntax

Dialogue

[action:"actionName", param1:"value", param2:"value", delay:"seconds"]

onclick

{"action":"actionName", "param1":"value", "param2":"value", "delay":"seconds"}

Script

LB.Actions.actionName({param1:"value", param2:"value", delay:"seconds"});

Conditional Actions

An action that only runs if an item was collected

{"action":"displayNotification", "message":"The door is now open", "condition":"item.goldenkey.collected"}

Properties

nid/nodeid

Node ID is shown in the top left in the dialogue tree in ChatMapper

cnvid (conversation ID)

Conversation ID (cnvid) is shown in the left of the Conversations list in ChatMapper

actorId

ActorID is generally the order in which an avatar appears in the list, starting from one.  

However:

Actors in ChatMapper store their ID at time of creation, so if at some point there were 5 actors and the fourth was deleted, actor #5 would still have ID=5.

The ID for bots is their bot ID, e.g. "bot2i39pthzmhp8fidw03232hat". This can be seen in the Bots app

Modes

There are two modes in Scenario they are explained here

Conversation mode

This mode is when you are actively in a scenario conversation (typically built in ChatMapper).
When in conversation mode a toolbar with conversation controls is shown at the bottom of the screen, by default it includes the controls to rewind, pause, fast forward, toggle captions and mute audio.

By default the camera in non-immersive devices will be locked on the conversation and any camera angles defined.

In immersive devices such as VR and AR the player can look around freely and the controls will follow as a heads up display (HUD) at the bottom of their view.

It is also possible to force the freedom of looking around while a conversation is playing in non-immersive devices. Simply add an extra parameter getIntoCMMode to the action and set it to false.

{"action":"playConversationId", "cnvid":6764, "getIntoCMMode":false}

Exploration mode

Where the participant is free to look and move around the environment

API

Common parameters

propagate

(bool, optional, default false) The action will be propagated to all users in the space so it will run for every user

propagationAllowedRoles

(string or array, optional, default empty) Restrict the propagation capabilities for these roles. Leaving this parameter empty will allow anybody to propagate the action

onExecuted 2.15+

(function, optional) This callback will be called when the action has been executed locally

onRemotelyExecuted 2.15+

(function, optional) This callback will be called when the action has been executed in other users’ devices.

Argument: externalId

delay

takes a value in seconds, eg. 2 seconds

delayMs

takes a value in milliseconds, eg. 2000 milliseconds is 2 seconds

condition

(string, optional) Gamification condition to be checked before running the action

playNode

The playNode() action plays a node of the conversation.

Dialogue Example

[action:"playNode", nodeid:"5", getIntoCMMode:true]

onclick Example

{"action":"playNode", "nodeid":"5", "getIntoCMMode":true}

Script Example

LB.Actions.playNode({nodeid:"5", getIntoCMMode:true});

Parameters

nodeid

(required) ChatMapper dialogue node number in the current conversation

getIntoCMMode

(optional) true to change game status to Conversation Mode (with prev/next/pause buttons and no navigation), false to remain in the current interaction mode (default)

Return value

null

playConversationId

The playConversationId() action plays a conversation optionally jumping to a specific node with control over the user interface mode of conversation or interactive.

Example: play ChatMapper conversation 5 and remain in interactive interface mode

Dialogue

[action:"playConversationId", cnvid:"5"]

onclick

{"action":"playConversationId", "cnvid":"5"}

Script

LB.Actions.playConversationId({cnvid:"5"});

Example: play ChatMapper conversation 5 from node 3 and use conversation interface

Dialogue

[action:"playConversationId", cnvid:"5", nid:"3", getIntoCMMode:true]

onclick

{"action":"playConversationId", "cnvid":"5", "nid":"3", "getIntoCMMode":true}

Script

LB.Actions.playConversationId({cnvid:"5", nid:"3", getIntoCMMode:true});

Parameters

cnvid

(required) ChatMapper conversation number to play

nid

(optional) ChatMapper dialogue node number in the current conversation

getIntoCMMode

(optional) true to change game status to Conversation Mode (with prev/next/pause buttons and no navigation), false to remain in the current interaction mode (default)

Return value

null

teleportActorToSpotTag

The teleportActorToSpotTag() teleports an actor to a hotspot with the matching spotTag name.

Each hotspot has a spotTag field, here you can enter any text name to identify the hotspot.

Note: a hotspot can only accept one character occupying it at one time. If you try to teleport an actor or player to the spot when it is occupied no action will be taken.

However, more than one hotspot can be given an identical spotTag name and the platform will randomly teleport to an unoccupied hotspot with the matching spotTag name.

Example: move actor 1 to hotspot2

Dialogue

[action:"teleportActorToSpotTag", actorId:"1", spotTag:"hotspot2"]

onclick

{"action":"teleportActorToSpotTag", "actorId":"1", "spotTag":"hotspot2"}

Script

LB.Actions.teleportActorToSpotTag({actorId:1, spotTag:"hotspot2"});

Parameters

actorId

(required) ChatMapper actor ID

spotTag

(required) hotspot tag defined in the template’s 3d scene

See VR Scenario – Bot Authoring section titled Actor Hotspots Assignments in Templates to see images of spot identifiers in the scenario templates. For example the office template hotspots are identified as follows:

office_hostpots.jpg

Return value

null

teleportPlayerToSpotTag

The teleportPlayerToSpotTag() teleports the player to a hotspot.

Each hotspot has a spotTag field, here you can enter any text name to identify the hotspot.

Note: a hotspot can only accept one character occupying it at one time. If you try to teleport an actor or player to the spot when it is occupied no action will be taken and the user will see a notification that the hotspot is occupied.

However, more than one hotspot can be given an identical spotTag name and the platform will randomly teleport to an unoccupied hotspot with the matching spotTag name.

Example: teleport player to spot with name "hotspot2"

Dialogue

[action:"teleportPlayerToSpotTag", spotTag:"hotspot2"]

onclick

{"action":"teleportPlayerToSpotTag", "spotTag":"hotspot2"}

Script

LB.Actions.teleportPlayerToSpotTag({spotTag:"hotspot2"});

Example: teleport player to hotspot with id 2 and don’t animate the camera

Dialogue

[action:"teleportPlayerToSpotTag", spotTag:"hotspot2", immediate:"true"]

onclick

{"action":"teleportPlayerToSpotTag", "spotTag":"hotspot2", "immediate":true}

Script

LB.Actions.teleportPlayerToSpotTag({spotTag:"hotspot2", immediate:true});

Parameters

spotTag

(required) hotspot tag defined in the template’s 3d scene

See VR Scenario – Bot Authoring section titled Actor Hotspots Assignments in Templates to see images of spot identifiers in the scenario templates. For example the office template hotspots are identified as follows:

office_hostpots.jpg

immediate

(optional) a value of true avoids the camera animation to the new location, false will animate the camera to the new hotspot (default)

Return value

null

setSpotTagActive

The setSpotTagActive() enables/disables a hotspot by tag.

Example: set hotspot2 to enabled

Dialogue

[action:"setSpotTagActive", spotTag:"hotspot2"]

onclick

{"action":"setSpotTagActive", "spotTag":"hotspot2"}

Script

LB.Actions.setSpotTagActive({spotTag:"hotspot2"});

Example: set hotspot 2 to disabled

Dialogue

[action:"setSpotTagActive", spotTag:"hotspot2", value:"false"]

onclick

{"action":"setSpotTagActive", "spotTag":"hotspot2", "value":false}

Script

LB.Actions.setSpotTagActive({spotTag:"hotspot2", value:false});

Parameters

spotTag

(required) hotspot tag defined in the template’s 3d scene. See VR Scenario – Bot Authoring section titled Actor Hotspots Assignments in Templates to see images of spot identifiers in the scenario templates. For example the office template hotspots are identified as follows:

office_hostpots.jpg

value

(optional) a value of true (default) enables the hotspot, false will disable the hotspot (default)

Return value

null

setUserVariable

Set a variable (which will also be reflected in ChatMapper) and updates objects in scene.

Example: set a ChatMapper variable users_name to Fred

Dialogue

[action:"setUserVariable", name:"users_name", value:"Fred"]

onclick

{"action":"setUserVariable", "name":"users_name", "value":"Fred"}

Script

LB.Actions.setUserVariable({name:"users_name", value:"Fred"});

Example: set a ChatMapper variable missionCompleted to true

Dialogue

[action:"setUserVariable", name:"missionCompleted", value:"true"]

onclick

{"action":"setUserVariable", "name":"missionCompleted", "value":"true"}

Script

LB.Actions.setUserVariable({name:"missionCompleted", value:"true"});

Parameters

name

(required) name of the ChatMapper variable

value

(required) the value you wish to set the variable to

Return value

null

getUserVariable 2.15+

Get the value of a certain variable (which can be set from ChatMapper as well).

Example: get the “users_name” variable, defaulting to “Fred” if the variable is not defined/has no value

Dialogue

[action:"getUserVariable", name:"users_name", default:"Fred"]

onclick

{"action":"getUserVariable", "name":"users_name", "default":"Fred"}

Script

LB.Actions.getUserVariable({name:"users_name", default:"Fred"});

Parameters

name

(required) name of the variable requested

default

A default value to return if the variable doesn’t exist

Return value

mixed

The value of the variable requested

displayNotification

The displayNotification() displays a notification in the top right of the screen, that can be fully customized.

Example: display a popup with the title The Popup Title with a message Hello world! and a OK button

Dialogue

[action:"displayNotification", message:"You just found a diamond!"]

onclick

{"action":"displayNotification", "message":"You just found a diamond!"}

Script

LB.Actions.displayNotification({message:"You just found a diamond!"});

Parameters

message

(required) the text to display as a message in the notification. Can be HTML.

type

(optional) the type of alert, it will change colors and default badge. See image below for every example. Available values are "success" (the default), "reward"(2.8+), "primary", "secondary", "warning", "error" or "danger", "info", "light", "dark"

badgeText

(optional) the text to put in the badge, if any. This can also be HTML.

fadeOutAfter

(optional) the number of milliseconds (thousandths of a second) after which the alert should start fading out

fadeOutDuration

(optional) the number of milliseconds the fade-out animation will take

playSfx

(optional, 2.9+) play a sound when displaying the notification. Defaults to false

sfxSrc

(optional, 2.9+) the URL of the audio file to be played. If no URL is provided, a default sound will play. The URL can also be the local path of a file included within the Scenario (through a CMPKG upload)

id

(optional, 3.0+) an identification to make the notification unique. Displaying a new notification using the same id will replace the previous one.

Return value

null

launchYammerFeed

The launchYammerFeed() pops up a Yammer feed.

Example: popup a basic yammer discussion board

Dialogue

[action:"launchYammerFeed", network:"hellonetwork", feedId:"0000000"]

onclick

{"action":"launchYammerFeed", "network":"hellonetwork", "feedId":"0000000"}

Script

LB.Actions.launchYammerFeed({network:"hellonetwork", feedId:"0000000"});

Example: popup an advanced yammer discussion board

Dialogue

[action:"launchYammerFeed", config:"{use_sso:true header:false footer:false showOpenGraphPreview:false defaultToCanonical:true hideNetworkName:true width:60vw height:40vw}", network:"hellonetwork", feedId:"0000000"]

onclick

{"action":"launchYammerFeed", "config":"{use_sso:true header:false footer:false showOpenGraphPreview:false defaultToCanonical:true hideNetworkName:true width:60vw height:40vw}", "network":"hellonetwork", "feedId":"0000000"}

Script

LB.Actions.launchYammerFeed({config:"{use_sso:true header:false footer:false showOpenGraphPreview:false defaultToCanonical:true hideNetworkName:true width:60vw height:40vw}", network:"hellonetwork", feedId:"0000000"});

Parameters

config

(required) an object containing:

{use_sso:' ' header:' ' footer:' ' showOpenGraphPreview:' ' defaultToCanonical:' ' hideNetworkName:' ' width:' ' height:' '}

network

(required) the yammer network name

feedId

(required) the feedId in the yammer network

Return value

null

callFunction

The callFunction() calls a function – only applicable to window level functions and 1 parameter.

Example: call a function

Dialogue

[action:"callFunction", name:"alert", parameter:"hello"]

onclick

{"action":"callFunction", "name":"alert", "parameter":"hello"}

Script

LB.Actions.callFunction({name:"alert", parameter:"hello"});

Parameters

name

(required) name of the function to call

parameter

(optional) one parameter to be passed to the function. If null, all parameters are passed in one object

Return value

null

displayIframe

The displayIframe() pops up a webpage.

Note: some sites have a security policy that blocks being displayed in an iFrame. You can confirm this by looking at your browser console for a message like:

Refused to display 'https://www.google.com/' in a frame because it set 'X-Frame-Options' to 'sameorigin'.

Example: popup a basic iframe

Dialogue

LB.Actions.displayIframe({url:'https://wikipedia.org', header: 'Wikipedia'});

onclick

{"action":"displayIframe", "url":"https://wikipedia.org", "header": "Wikipedia"}

Script

LB.Actions.displayIframe({url:'https://wikipedia.org', header: 'Wikipedia'});

Parameters

url

(required) source url of the page to display in the body of the popup

isPersistent

(optional, 2.8+) a persistent iframe will not be removed from the page even if the modal is hidden, so for instance a video embedded in this way will keep playing in the background even if it’s not visible. True by default.

header

(optional, 2.9+) the text to be included in the header of the modal, which will also include a "close" button. This text can be HTML.

Return value

null

displayForm

The displayForm() displays a form using web standard Alpaca Forms structure in a popup.

Script Example: popup a basic form

LB.Actions.displayForm({
   
name: "box1",
   
title: "Select Risk Type",
   
data: false,
   
options: {
     
rightLabel: "Mark this"
   },
   
width: "20em",
   
height: "3em"   
});

The schema and options can be defined as variables (in the first node of the ChatMapper conversation for example) and then used in parameters as a string. The string will be evaluated in JavaScript to get the object.

Example: popup a form with its schema and options defined in variables.

The schema and options variables (defined once in ChatMapper)

var sandbox_form_schema = {
   
"type": "string",
   
"enum": ["mobility", "vision", "equipment-built-environment", "electrical-burn","medication-nutritional","prior-injury"]
};

var sandbox_form_options = {
   
"type": "checkbox",
   
"optionLabels": [
       
"<img src='../../scenario_sandbox/assets/textures/0.png'>Mobility Hazard (Extrinsic)",
       
"<img src='../../scenario_sandbox/assets/textures/1.png'>Vision Hazard (Extrinsic)",
       
"<img src='../../scenario_sandbox/assets/textures/2.png'>Equipment / Built Environment Hazard (Extrinsic)",
       
"<img src='../../scenario_sandbox/assets/textures/3.png'>Electrical / Burn Hazard (Extrinsic)",
       
"<img src='../../scenario_sandbox/assets/textures/4.png'>Medication / Nutritional Hazard (Intrinsic)",
       
"<img src='../../scenario_sandbox/assets/textures/5.png'>Prior Injury (Intrinsic)"]
};

The form popup (used in nodes where you want the form to popup)

LB.Actions.displayForm({
   title:
"Select Risk Type",
   name:
"box2",
   schema: sandbox_form_schema,
   options: sandbox_form_options
 });

Parameters

Can contain any AlpacaForms parameter (schema, options, data, view, etc, (see documentation on AlpacaForms website)

view

data

name

if no name is provided, LB.Forms.results will be the result of that form. If a name is provided, it will be a property inside LB.Forms.results

title

the title for the popup

buttonText

the submit button text (default) Submit

saveToCMVariables

if true, responses will be set as ChatMapper variables too

width/height

string to be attached as css parameter (e.g. 100px, 100vw, 100em – px, vw, or em must be present)

callback

(formSettings, results) – callback will be triggered when the form is submitted. Not compatible with multiuser actions in 2.7+

schema

can be object or string

options

can be object or string

Return value

null

exitConversation

The exitConversation() exits the current ChatMapper conversation.

Example: exit the current conversation

Dialogue

[action:"exitConversation"]

onclick

{"action":"exitConversation"}

Script

LB.Actions.exitConversation();

Example: exit the current conversation and return to the previous space (of this world)

Dialogue

[action:"exitConversation", returnToLastScene:"true"]

onclick

{"action":"exitConversation", "returnToLastScene":true]

Script

LB.Actions.exitConversation({returnToLastScene:true});

Parameters

returnToLastScene

(optional) true returns to the last space (only in multi-space worlds), false stays in the current space (default)

Return value

null

openURLInNewWindow

The openURLInNewWindow() opens the url in a new window with a given title.

Example: open a new tab/window showing the given url

Dialogue

[action:"openURLInNewWindow", url:"https://google.com"]

onclick

{"action":"openURLInNewWindow", "url":"https://google.com"}

Script

LB.Actions.openURLInNewWindow({url:"https://google.com"});

Example: open a new tab/window showing the given url and title

Dialogue

[action:"openURLInNewWindow", url:"https://google.com", title:"Search_Tab"]

onclick

{"action":"openURLInNewWindow", "url":"https://google.com", "title":"Search_Tab"}

Script

LB.Actions.openURLInNewWindow({url:"https://google.com", title:"Search_Tab"});

Parameters

url

(required) source url of the page to display in the new tab/window

title

(optional) the text of the name for the new tab/window, can be useful to reference through script or to re-user/load content into the same named tab again later (default) blank

Return value

null

playGesture

The playGesture() action causes a named animation to be played on a character.  Learn more about gestures here.

Example: play the yes gesture on the current actor

Dialogue

[action:"playGesture", name:"yes"]

onclick

{"action":"playGesture", "name":"yes"}

Script

LB.Actions.playGesture({name:"yes"});

Example: play the no gesture on actor 2 and play it over 2.5 seconds (2500 milliseconds)

Dialogue

[action:"playGesture", name:"no", actorId:"2", duration:"2500"]

onclick

{"action":"playGesture", "name":"no", "actorId":"2", "duration":"2500"}

Script

LB.Actions.playGesture({name:"no", actorId:2, duration:"2500"});

Parameters

name

(required) name of animation (see Scenario Gestures docs for full list)

actorId

(optional) if not supplied the gesture will play on the current talking avatar of the dialogue node

externalId

(optional) the externalId of the avatar is also accepted

duration

(optional) duration of gesture animation (default) 2000 milliseconds.
Note: If you find an animation being cut short due to the 2000 millisecond default use “auto” for duration instead this will play the animation's full duration.

Return value

null

setAvatarLookTarget

The setAvatarLookTarget() sets lookTarget for the avatar, which will override everything else. Will affect the player if no avatar or actorId specified.

Making an avatar look at a fixed point

Each frame the avatar checks a prioritized list to decide where it should look towards.

The priority order is:

  1. lookTarget (if it's not null)
  2. ChatMapper conversant (if we're in a ChatMapper conversation)
  3. Follow the camera direction the player is looking in (if the actor is the player and the Space setting Avatar follow camera look at is on
  4. Hotspot target (if defined)
  5. Look towards the front

Example: player avatar to look to a defined point in the space

Dialogue

[action:"setAvatarLookTarget", lookTarget:"new THREE.Vector3(-3, 1, -3)"]

onclick

{"action":"setAvatarLookTarget", "lookTarget":"new THREE.Vector3(-3, 1, -3)"}

Script

LB.Actions.setAvatarLookTarget({
   lookTarget:
new THREE.Vector3(-3, 1, -3)
});

Example: remove the lookTarget property so the avatar would look for other parameters to look at (see priority list above)

Dialogue

[action:"setAvatarLookTarget", lookTarget:"null"]

onclick

{"action":"setAvatarLookTarget", "lookTarget":"null"}

Script

LB.Actions.setAvatarLookTarget({
   lookTarget:
null
});

Script Example: look at an item "breathalyzer" in the scene. Even if the item moves, the avatar will follow look at it

var b = LB.Utils.findItem("breathalyzer");
LB.Actions.setAvatarLookTarget({
   lookTarget: b
});

Example: actor with ID 1 will look at the actor with ID 2. Even if the actor 2 moves, avatar 1 will look to where it moves

Dialogue

[action:"setAvatarLookTarget", actorId:"1", lookTarget:"2"]

onclick

{"action":"setAvatarLookTarget", "actorId":"1", "lookTarget":"2"}

Script

LB.Actions.setAvatarLookTarget({
   actorId:
1,
   lookTarget:
2
});

Parameters

actorId

(optional) ChatMapper ID of the actor

avatar

(optional) avatar object (will override actorId)

lookTarget

(optional) target, this applies to the ChatMapper CAF avatar_lookTarget and the avatarLookAt action

null – avatar won’t take this parameter into account when updating its look direction

string:

"camera" – looks at the currentCamera

"none" –  unsets the lookTarget (sets the parameter to null)

"Name of an object" – looks for an object with that name to make the lookTarget

number – looks for an actor with that ID to be the lookTarget

object – is it THREE.Object3D? Then look at its position (deprecated in 2.7+, use object name instead)

vector3D – look at this position

Return value

null

fadeScene

The fadeScene() shows a black (customizable) overlay on top of the scene.

Note: fadeScene does not apply to VR/AR, it uses a 2D HTML layer which is only visible outside immersive view.

Parameters

direction

(required) "in" or "out" for fade-in or fade-out.

duration

(optional) duration of the animation in milliseconds. Default is 1000

color

(optional, 2.12+) color of the overlay, black by default. Any CSS-valid color property is accepted.

opacity

(optional, 2.12+) opacity of the overlay, from 0 (invisible) to 1 (completely opaque). 1 by default.

clickThrough

(optional, 2.12+) if true, the user can interact with the scene. If false, interactions are blocked. False by default, it can be useful to set it as true with low-opacity overlays.

Return value

null

Example: fade the scene to black

Dialogue

[action:"fadeScene", direction:"out"]

onclick

{"action":"fadeScene", "direction":"out"}

Script

LB.Actions.fadeScene({direction:"out"});

Example: fade the scene to yellow

Dialogue

[action:"fadeScene", direction:"out", color:"yellow"]

onclick

{"action":"fadeScene", "direction":"out", "color":"yellow"}

Script

LB.Actions.fadeScene({direction:"out", color:"yellow"});

Example: fade in scene from black

Dialogue

[action:"fadeScene", direction:"in"]

onclick

{"action":"fadeScene", "direction":"in"}

Script

LB.Actions.fadeScene({direction:"in"});

Example: fade in the scene from black to visible over 1.5 seconds

Dialogue

[action:"fadeScene", duration:"1500", direction:"in"]

onclick

{"action":"fadeScene", "duration":"1500", "direction":"in"}

Script

LB.Actions.fadeScene({duration:"1500", direction:"in"});

forceCameraShot

The forceCameraShot() forces the camera shot for some time, only in exploration mode.

Example: animate the camera shot (see shot code explanations below)

Dialogue

[action:"forceCameraShot", shotName:"XCU"]

onclick

{"action":"forceCameraShot", "shotName":"XLS"}

Example: animate the camera for 1 second to do a Big Close Up for 3 seconds

Dialogue

[action:"forceCameraShot", duration:"3000", animationTime:"1000", shotName:"BCU"]

onclick

{"action":"forceCameraShot", "duration":"3000", "animationTime":"1000", "shotName":"BCU"}

Script

LB.Actions.forceCameraShot({duration:"3000", animationTime:"1000", shotName:"BCU"});

Parameters

duration

(optional) forces the shot for a number of milliseconds

animationTime

(optional) duration of animation

shot

(optional) json object defining the new custom shot including a new shotName. Only use shot parameter if defining a new custom camera shot, use shotName parameter below for preconfigured camera shots

shotName

(optional) name of a preconfigured shot to use, one of:

  • 'XLS' – Extreme Long Shot
  • 'LS' – Long Shot
  • 'MLS' – Medium Long Shot
  • 'MS' – Medium Shot
  • 'MCU' – Medium Close Up
  • 'CU' – Close Up
  • 'BCU' – Big Close Up
  • 'XCU' – Extreme Close Up
  • ‘OSL’ – Over the Shoulder, Left side (2.9+)
  • ‘OSR’ – Over the Shoulder, Right side (2.9+)
  • Custom shotName created through shot parameter above

a_XLSopy.jpg

a_LS.jpg

a_MLS.jpg

a_Ms.jpg

XLS (Extra Long Shot)

LS (Long Shot)

MLS (Medium Long Shot)

MS (Medium Shot)

a_MCU.jpg

a_CU.jpg

a_BCU.jpg

a_XCU.jpg 

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+)

Return value

null

playCustomNode  2.7+  

The playCustomNode() executes a custom node using the Chatmapper dialog system. It can be used to have a bot speak custom text when clicked. Additional parameters from the Chatmapper dialog system can be used. See CM CAF document for more information.

Example: Make the player avatar say something without changing the camera shot (not entering CM mode)

Dialogue

<not applicable>

onclick

{"action":"playCustomNode", "text":"This is a test"}

Script

LB.Actions.playCustomNode({text:"This is a test"});

Example: Make the actor id 2 say something to actor id 3 going into CM Mode to use the avatar shot feature

Dialogue

<not applicable>

onclick

{"action":"playCustomNode", "actorId":2, "conversantId":3, "text":"Hello John, how are you?", "getIntoCMMode":true, "avatar_shot":"CU"}

Script

LB.Actions.playCustomNode({"actorId":2, "conversantId":3, "text":"Hello John, how are you?", "getIntoCMMode":true, "avatar_shot":"CU"});

Example: Make the actor id 2 say something to camera using a customs shot. Ignoring the parameter conversantId makes the actor look at the camera.

Dialogue

<not applicable>

onclick

{"action":"playCustomNode", "actorId":2, "text":"You can look around you to find hidden objects", "getIntoCMMode":true, "avatar_shot":"MS"}

Script

LB.Actions.playCustomNode({"actorId":2, "text":"You can look around you to find hidden objects", "getIntoCMMode":true, "avatar_shot":"MS"});

Parameters

text

(required) text that will get spoken by the avatar

actorId

(optional) actor which will speak. If not supplied the default is the player avatar.

avatar

(optional) avatar object (overwrites actorId) (deprecated in 2.7+, use externalId instead)

externalId

(optional) avatar externalId (overwrites actorId)

conversantId

(optional) actor the speaker will look to. If not supplied the speaker will look at camera

conversantAvatar

(optional) conversant avatar object (overwrites conversantId)

getIntoCMMode

(optional) whether or not game status is changed to CM mode (with prev/next/pause buttons and no navigation) (default is false)

<additional parameters>

Any Chatmapper node field is compatible, including Custom Asset Fields (CAF). See examples.

Return value

null

lookAt 2.7+

The lookAt() rotates the object towards a defined target..

Example: Make the object always face the camera (for billboards / animated sprites)

onfixedupdate

{"action":"lookAt", "target":"camera"}

Script

LB.Actions.lookAt({"target":"camera"});

Parameters

target

(required) Target object to look at. Can be:

  • "camera": The object will face the camera
  • Vector3: The object will look to that position in the scene
  • Number: The object will look to the actor with that ID

objectName

(optional) object to apply the action to. If not set, the action will be applied to the object triggering it.

Return value

null

setObjectVisible 2.7+

The setObjectVisible() shows or hides an object in the scene.

Example: Hide the object as default in the scene

onstart

{"action":"setObjectVisible", "visible":false}

Script

LB.Actions.setObjectVisible({"visible":false});

Example: When clicked on this object, hide another object in the scene

onclick

{"action":"setObjectVisible", "visible":false, "objectName":"otherObject"}

Script

LB.Actions.setObjectVisible({"visible":false, "objectName":"otherObject"});

Parameters

visible

(required) boolean value for visibility.

objectName

(optional) object to apply the action to. If not set, the action will be applied to the object triggering it.

Return value

null

fadeObject 2.7+

The fadeObject() shows or hides an object in the scene with a fade effect.

Parameters

direction

(required) whether it’s a fade-in or a fade-out. Possible values:

  • "in" (the object will become visible)
  • "out" (the object will become invisible)

objectName

(optional) object to apply the action to. If not set, the action will be applied to the object triggering it.

duration

(optional) how long the transition should take, in seconds. The default is 0.7s

Return value

null

Example: When clicked on this object, fade another object in.

onclick

{"action":"fadeObject", "direction":"in", "objectName":"otherObject"}

Script

LB.Actions.fadeObject({"direction":"in", "objectName":"otherObject"});

navigateTo 2.8+

The navigateTo() action will teleport the user to a different space within a world. Using a spaceId that is not from the same world will have no effect.

Two special values can be used: "next" and "previous". They will teleport the user to the following and preceding space in the world, respectively. This is mostly useful in "linear" worlds, where a user is expected to move from one space to another following their order.

onclick

{"action":"navigateTo", "spaceId":"spc123456"}

Script

LB.Actions.navigateTo({"spaceId":"spc123456"});

Parameters

spaceId

(required) the spaceId to teleport to. Can be "next" or "previous".

showConfirmation

(optional, 2.14+) show the user a confirmation popup before teleporting them. True by default

name

(optional, 2.14+) name of the space shown in the confirmation popup

Return value

null

startTask 2.8+

The startTask() action sets a task’s status as ‘started’.

Example: set a certain task as started when the user clicks on an object.

onclick

{"action":"startTask", "shortcode":"funny-sun-ae3e"}

Script

LB.Actions.startTask({"shortcode":"funny-sun-ae3e"});

Parameters

shortcode

(required if propertyId is not used) The task’s shortcode, usually obtained from app.learnbrite.com/trophio.

propertyId

(required if shortcode is not used) The task’s propertyId, usually obtained from app.learnbrite.com/trophio.

Return value

null

completeTask 2.8+

The completeTask() action sets a task’s status as ‘complete’.

Example: complete a certain task when the user clicks on an object.

onclick

{"action":"completeTask", "shortcode":"funny-sun-ae3e"}

Script

LB.Actions.completeTask({"shortcode":"funny-sun-ae3e"});

Parameters

shortcode

(required if propertyId is not used) The task’s shortcode, usually obtained from app.learnbrite.com/trophio.

propertyId

(required if shortcode is not used) The task’s propertyId, usually obtained from app.learnbrite.com/trophio.

Return value

null

getTaskStatus 2.8+

The getTaskStatus() action gets a task’s status.

Example: during a treasure hunt, the user finds a certain object, but we only set the task as complete if it was already "started" when the object was found.

onclick

{"action":"getTaskStatus", "shortcode":"funny-sun-ae3e"}

Script

result = LB.Actions.getTaskStatus({"shortcode":"funny-sun-ae3e"});

Parameters

shortcode

(required if propertyId is not used) The task’s shortcode, usually obtained from app.learnbrite.com/trophio.

propertyId

(required if shortcode is not used) The task’s propertyId, usually obtained from app.learnbrite.com/trophio.

Return value

string

The task’s status (one of "not-started", "started", or "complete")

updateTask 2.8+

The updateTask() action sets a task’s status to the given one.

Example: the user can find three different objects, two pieces of a map or a whole map. If they find one of the pieces, we set the task as ‘started’. If they find the whole map (whether in one go or by collecting the two pieces) we set the task as complete.

onclick

{"action":"updateTask", "shortcode":"funny-sun-ae3e", "status":"started"}

Script

LB.Actions.updateTask({"shortcode":"funny-sun-ae3e", "status":"started"});

Parameters

shortcode

(required if propertyId is not used) The task’s shortcode, usually obtained from app.learnbrite.com/trophio.

propertyId

(required if shortcode is not used) The task’s propertyId, usually obtained from app.learnbrite.com/trophio.

status

(required) the new status of this task (one of "not-started", "started", or "complete")

Return value

null

collectItem 2.8+

The collectItem() action "collects" an item by marking its status as "collected".

Example: in a treasure hunt, this is useful to mark an item as collected.

onclick

{"action":"collectItem", "item":"towel"}

Script

LB.Actions.collectItem({"item":"towel"});

Parameters

item

(required) the item’s name.

Return value

null

dropItem 2.8+

The dropItem() action "drops" an item by marking its status as "dropped". Note that this won’t delete the item from the user’s inventory.

Example: in a multiuser treasure hunt, there could be only one "copy" of an item, that can be stolen from its current owner by doing something. The item could then be set as "collected" for the new owner and as "dropped" for the previous one.

onclick

{"action":"dropItem", "item":"towel"}

Script

LB.Actions.dropItem({"item":"towel"});

Parameters

item

(required) the item’s name.

Return value

null

checkIfCollected 2.8+

The checkIfCollected() action checks if the given item is marked as "collected".

Example: only show a special hotspot if an item called "key" has been found.

onclick

{"action":"checkIfCollected", "item":"towel"}

Script

result = LB.Actions.checkIfCollected({"item":"towel"});

Parameters

item

(required) the item’s name.

Return value

boolean

true if the item is collected, false otherwise.

getItemStatus 2.8+

The getItemStatus() action returns the status of the given item.

Important note: this only applies to the space it is called in. An itemStatus can be set and retrieved only in the same space, the itemStatus is not available in other spaces in a world.

Example: display a mediaboard only if a certain item was collected.

onclick

{"action":"getItemStatus", "item":"towel"}

Script

result = LB.Actions.getItemStatus({item:"towel"});

Parameters

item

(required) the item’s name.

Return value

string

the item’s status

setItemStatus 2.8+

The setItemStatus() action sets an item’s status to the given one.

Important note: this only applies to the space it is called in. An itemStatus can be set and retrieved only in the same space, the itemStatus is not available in other spaces in a world.

Example: set an item as collected or dropped based on a certain condition.

onclick

{"action":"setItemStatus", "item":"towel", "status":"started"}

Script

LB.Actions.setItemStatus({item:"towel", status:"started"});

Parameters

item

(required) the item’s name.

status

(required) the new status for the item.

Return value

null

playExplojis 2.8+

The playExplojis() action creates a particle effect at the avatar’s head made from emojis

Example: Play a set of predefined explojis

onclick

{"action":"playExplojis", "text":":)"}

Script

LB.Actions.playExplojis("text":":)"});

Example: Trigger an array of custom emojis

Dialogue

[action:"playExplojis", emojisArr:["😁",""]]

onclick

{"action":"playExplojis", "emojisArr":["😁",""]}

Script

LB.Actions.playExplojis({"emojisArr":["😁",""]});

Parameters

actorId

(optional) actor which will speak. If not supplied the default is the player avatar.

avatar

(optional) avatar object (overwrites actorId) (deprecated in 2.7+, use externalId instead)

externalId

(optional) avatar externalId (overwrites actorId)

text

(optional) text with emojis. Only some of them are supported for now:

  • 🙂
  • 🙁
  • <3

emojisArr

(optional) array of emojis to display

Return value

null

setAvatarMood 2.8+

The setAvatarMood() action changes the mood of an avatar, affecting its idle animation and other gestures.  Available moods:

  • (empty) – Default mood
  • blue
  • hiphop
  • preppy
  • angry
  • happy
  • waiting

Example: set the mood happy on the current actor

Dialogue

[action:"setAvatarMood", mood:"happy"]

onclick

{"action":"setAvatarMood", "mood":"happy"}

Script

LB.Actions.setAvatarMood({mood:"happy"});

Example: set the mood angry on actor 2

Dialogue

[action:"setAvatarMood", mood:"angry", actorId:"2"]

onclick

{"action":"setAvatarMood", "mood":"angry", "actorId":"2"}

Script

LB.Actions.setAvatarMood({mood:"angry", actorId:"2"});

Parameters

mood

(required) name of mood

actorId

(optional) if not supplied the gesture will play on the current talking avatar of the dialogue node

externalId

(optional) the externalId of the avatar is also accepted

Return value

null

setVideoboardControls 2.8+

Control a video element in the 3D environment. Use videoForcePlay to start the video playing, use videoForcePause to pause the video.

Dialogue

[action:"setVideoboardControls","video":"Mediaboard_[NAME]", videoForcePlay:"true"]

onclick

{"action":"setVideoboardControls","video":"Mediaboard_[NAME]", "videoForcePlay":true}

Script

LB.Actions.setVideoboardControls({videoForcePlay:true,video:"Mediaboard_[NAME]"});

Example of setting video controls for Staff,Owner,Editors, Presenters but restricting controls to Zoom, Mute and Back for participants

{"action":"setVideoboardControls","type":"video","video":"Mediaboard_[NAME]","videoControlAllowedRoles":"Owner,Editor,Presenter,Staff","videoProxy":false,"videoHlsLoopFix":true}

Example of looping a video with no controls

{"action":"setVideoboardControls","type":"video","video":"Mediaboard_[NAME]","videoControlAllowedRoles":"","videoProxy":false,"videoHlsLoopFix":true,"loop":true}

Parameters

video

Name of the mediaboard/object on which this action is called

videoSource

Change the video URL to another

videoPreviousSource

If true, go back to the previous URL used

videoCurrentTime

Go to a selected time in the video

videoForcePause

Force a pause

videoForcePlay

Force playing the video

videoControlAllowedRoles

Roles that are allowed to control the video playback (default Owner,Editor,Presenter,VIP,User,Guest,Staff)

syncVideoStatus

Synchronize the status of the video across users (default true).  2.14+

videoSyncAllowedRoles

Only allow synchronization for these roles (default Editor,Presenter,Staff,Owner). 2.14+

loop

Whether the video should loop (false by default) 2.14+

muted

Whether the video should be muted (false by default) 2.14+

volume

The volume of the video, from 0 to 100 (the default) 2.15+

Return value

null

playSFX 2.9+

The playSFX() action plays a sound given by a url

Parameters

url

(required) url address of the file

loop

(optional) the sound will repeat. Default is false

volume

(optional) Volume to apply to this sound (ignores the volume settings). Range is 0 to 100.

Example:

Dialogue

[action:"playSFX", url:"https://url-to-mp3-file"]

onclick

{"action":"playSFX", "url":"https://url-to-mp3-file"}

Script

LB.Actions.playSFX({url:"https://url-to-mp3-file", volume:50});

playAmbient 2.9+

The playAmbient() action plays a sound given by a url as a background ambient

Parameters

url

(required) url address of the file

loop

(optional) the sound will repeat. Default is true

resume

(optional) When stopped and played again, the sound will resume from where it was stopped. Default is true

volume

(optional) Volume to apply to this sound (ignores the volume settings). Range is 0 to 100.

Example:

Dialogue

[action:"playAmbient", url:"https://cache.learnbrite.com/_assets_/audio/ambientmusic/Roboskater.mp3",volume:5]

onclick

{"action":"playAmbient","url":"https://cache.learnbrite.com/_assets_/audio/ambientmusic/Roboskater.mp3","volume":5}

Script

LB.Actions.playAmbient({url:"https://cache.learnbrite.com/_assets_/audio/ambientmusic/Roboskater.mp3",volume:5});

stopAmbient 2.9+

The stopAmbient() stops the background sound

Parameters

Example:

Dialogue

[action:"stopAmbient"]

onclick

{"action":"stopAmbient"}

Script

LB.Actions.stopAmbient({});

setObjectField 2.9+

The setObjectField() action modifies a parameter for the selected object. The parameter must be one of the editableFields supported by that object.

Example: When the specified object is clicked, change the html content in the Note.

onclick

{"action":"setObjectField", "objectName":"Note-ABCD-1234", "fieldName":"innerHTML", "fieldValue":"This is a note"}

Script

LB.Actions.setObjectField({"objectName":"Note-ABCD-1234", "fieldName":"innerHTML", "fieldValue":"This is a note"});

Parameters

fieldName

(required) Name of the field to change

fieldValue

(required) Value for the field

objectName

Object to apply the action to. If not set, the action will be applied to the object triggering it.

Return value

null


displayImage 2.9+

Display an image in an arbitrary position.

onclick

{"action":"displayImage", "url":"https://cache.learnbrite.com/my-username/my-image.jpg", "position":"top-right"}

Script

LB.Actions.displayImage({"url":"https://cache.learnbrite.com/my-username/my-image.jpg", "position":"top-right"});

Parameters

url

(required) URL of the image

position

One of the following. Note that this will not have an effect when in VR:

  • center (default)
  • center-large
  • top-left
  • top
  • top-large
  • top-right
  • right
  • right-large
  • bottom-right
  • bottom
  • bottom-large
  • bottom-left
  • left
  • left-large

id

The HTML id given to the modal

lifetime

The number of seconds the image should stay on screen. The default value is 0, a special value to make the image stay on screen indefinitely. Note that this is always overridden by the time it takes for the text in the node in the node to be read out loud (unless no text is present).

altText

Set the alt text of the image, for accessibility purposes. Empty by default.

showCloseButton

Whether a close button should be shown on the image. True by default.

pauseConversation

Whether the image should pause conversation until the image is closed. True by default.

closeButtonStyle

(2.12+) The default (0) will show an X button in the top right corner. Setting this to 1 will show a button with text below the image.

closeButtonText

(2.12+) If closeButtonStyle is 1, this parameter can be used to set the text of the button.

closeButtonOverlapsImage

(2.12+) If closeButtonStyle is 1, this parameter decides whether the button should be within the area of the image (true) or outside (false, the default).

Return value

jQuery

A reference to the jQuery object of the image

setVolume 2.10+

Sets the audio volume. Can set the volume for specific types of sounds. All volume ranges are from 0 to 100.

Parameters

volume

(optional) Volume to be applied to all types of sounds.

SFXVolume

(optional) Volume for effect sounds.

ambientVolume

(optional) Volume for ambient sounds.

speechVolume

(optional) Volume for speech sounds.

Example:

Sets the volume as 50 for all sounds

Dialogue

[action:"setVolume", volume:50]

onclick

{"action":"setVolume", volume:50}

Script

LB.Actions.setVolume({volume:50});

Sets the volume as 0 for sound effects (SFX)

Dialogue

[action:"setVolume", SFXVolume:0]

onclick

{"action":"setVolume", SFXVolume:0}

Script

LB.Actions.setVolume({SFXVolume:0});

Sets the volume as 0 for ambient audio

Dialogue

[action:"setVolume", ambientVolume:0]

onclick

{"action":"setVolume", ambientVolume:0}

Script

LB.Actions.setVolume({ambientVolume:0});

Sets the volume as 0 for speech

Dialogue

[action:"setVolume", speechVolume:0]

onclick

{"action":"setVolume", speechVolume:0}

Script

LB.Actions.setVolume({speechVolume:0});

changeMediaboardImage 2.11+

Changes the displayed image on a mediaboard. An image set this way won’t be saved (it will revert to the original when reloading). Only works with image mediaboards, i.e. mediaboards created from an image link.

Parameters

name

(required) name of the mediaboard of which the image needs to be changed

url

(required) URL of the new image

Return value

Object

A javascript reference to the mediaboard

Examples:

[action:"changeMediaboardImage", name:"Mediaboard_laptop", url:"https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Random-image.jpg/640px-Random-image.jpg"]

onclick

{"action":"changeMediaboardImage", "name":"Mediaboard_laptop", "url":"https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Random-image.jpg/640px-Random-image.jpg"}

Script

LB.Actions.changeMediaboardImage({name:"Mediaboard_laptop", url:"https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Random-image.jpg/640px-Random-image.jpg"});

displayVideo 2.11+

Displays a video in an arbitrary position. Currently only supports mp4 and YouTube videos.

onclick

{"action":"displayVideo", "url":"https://cache.learnbrite.com/my-username/my-video.mp4", "position":"center-large"}

Script

LB.Actions.displayVideo({"url":"https://cache.learnbrite.com/my-username/my-video.mp3=4", "position":"top-right"});

Parameters

url

(required) URL of the video

position

One of the following. Note that this will not have an effect when in VR.

  • center
  • center-large (default)
  • top-left
  • top
  • top-large
  • top-right
  • right
  • right-large
  • bottom-right
  • bottom
  • bottom-large
  • bottom-left
  • left
  • left-large

id

The id given to the HTML element.

lifetime

The number of seconds the video should stay on screen. The default value is 0, a special value to make the video stay on screen indefinitely. Note that, unless no text is present, this is always overridden by the time it takes for the text in the node in the node to be read out loud.

showCloseButton

Whether a close button should be shown. True by default.

pauseConversation

Whether showing the video should pause conversation until the video is closed. True by default.

autoplay

Autoplay the video, if allowed. In Immersive/VR mode, this will automatically mute the video (even if “muted” is false). True by default.

loop

Whether the video should loop when finished. False by default.

controls

Show video controls (true by default). In Immersive/VR, this will only show the mute/unmute button.

muted

Whether the video should be muted. False by default.

poster

URL of the image to display before the video is started. Empty by default, and does not have an effect in Immersive/VR.

hideBorder

By default, a white border is shown around the video. By setting this to true, it’s hidden.

Return value

jQuery

A reference to the jQuery object of the video

setStatusMeterVisible 2.12+

Displays a status meter on the avatar. This visual meter is used to represent any status of the avatar, for example how happy or sad it is, health, energy, progress, etc.

Parameters

visible

(required) true or false

actorId

(optional) actor for the status meter. If not supplied the default is the player avatar.

externalId

(optional) avatar externalId (overwrites actorId)

Advanced parameters can be supplied as part of the action to configure the status meter. Check the Status Meter guide for setup parameters.

setStatusMeterValue 2.12+

Changes the value of the status meter for an avatar.

Parameters

actorId

(optional) actor for the status meter. If not supplied the default is the player avatar.

externalId

(optional) avatar externalId (overwrites actorId)

value

(optional) the value to be set

increment

(optional) if increment is provided along with a value, the parameter value will be ignored, and the increment will be added to the current value of the meter. The increment can be negative to subtract points.

animate

(optional) the progress bar will animate. Default is true

shootExplojis

(optional) explojis will be launched. Default is true.

Examples:

Increment the status meter of the actor with id 1 by 2

[action:"setStatusMeterValue", actorId:1, increment:2]

onclick

{"action":"setStatusMeterValue", "actorId":1, "increment":2}

Script

LB.Actions.setStatusMeterValue({actorId:1, increment:2});

setAvatarOutfit 2.11+

Changes the appearance of the avatar. It can clone the aspect of another avatar supplying an externalId, or replace individual pieces by supplying sku numbers. It can also do both at the same time.

Important note: Not specifying actorId or externalId will result in the changes being applied to the player. So, when propagating the action, make sure you specify the externalId of the avatar you want the outfit to change, otherwise the outfit will be changed for each user’s main avatar.

Important note: An sku may be designed for a particular body shape such as masculine or feminine. Changing the sku to one that uses an alternative body shape to the current avatar can swap the mesh creating unexpected results.

Parameters

actorId

(optional) actor to apply the outfit to. If not supplied the default is the player avatar.

externalId

(optional) avatar externalId (overwrites actorId)

copyFromExternalId

(optional) externalId of the avatar to clone the aspect from.

<drawer>

(optional) if a SKU used, this piece of clothing will replace the existing one for this drawer. This value will override the outfit loaded by using copyFromExternalId. This value can also be set to false and it will act as a mask for the outfit loaded by copyFromExternalId. See examples below.

save 2.16+

(optional) If set to true, the outfit will be saved permanently. In multiuser settings you should propagate the action so all other participants see the outfit update. Propagating the action through multiuser is designed to only execute the save action once at the origin.

Examples:

Replace the whole outfit of the player with the aspect from bot with externalId 12345678

[action:"setAvatarOutfit", copyFromExternalId:"bot12345678"]

onclick

{"action":"setAvatarOutfit", "copyFromExternalId":"bot12345678"}

Script

LB.Actions.setAvatarOutfit({copyFromExternalId:"bot12345678"});

Replace the player’s outfit with the aspect from bot with externalId 12345678, but keep the original face, eyes, and skin

[action:"setAvatarOutfit", copyFromExternalId:"bot12345678", face:false, eyes:false, skin:false]

onclick

{"action":"setAvatarOutfit", "copyFromExternalId":"bot12345678", "face":false, "eyes":false, "skin":false}

Script

LB.Actions.setAvatarOutfit({copyFromExternalId:"bot12345678", face:false, eyes:false, skin:false});

Replace the player’s outfit with the aspect from bot with externalId 12345678, leave the face untouched and force the hair to be the sku 9876

[action:"setAvatarOutfit", copyFromExternalId:"bot12345678", face:false, hair:9876]

onclick

{"action":"setAvatarOutfit", "copyFromExternalId":"bot12345678", "face":false, "hair":9876}

Script

LB.Actions.setAvatarOutfit({copyFromExternalId:"bot12345678", face:false, hair:9876});

Replace the avatar’s tshirt with the one with sku 100133, save the change permanently and propagate the action so all other participants see the outfit update.

[action:"setAvatarOutfit", torso:100133, save:true, propagate:true]

onclick

{"action":"setAvatarOutfit", "torso":100133, save:true, propagate:true}

Script

LB.Actions.setAvatarOutfit({torso:100133,save:true,propagate:true});

playStatusMeterExploji 2.12+

Triggers the exploji animation on an avatar’s status meter. Check the Status Meter guide for setup parameters.

Parameters

actorId

(optional) actor for the status meter. If not supplied the default is the player avatar.

externalId

(optional) avatar externalId (overwrites actorId)

value

(required) the emoji to be displayed. Can be a url or a previously configured emoji related to an action:

  • increment
  • decrement
  • neutral

Check the Status Meter guide for detailed information about these values.

Three useful values are:

img/icon_smiley_sad_color.png

img/icon_smiley_neutral_color.png

img/icon_smiley_happy_color.png

Examples:

Dialogue Text

[action:"playStatusMeterExploji", actorId:1, value:"img/icon_smiley_happy_color.png"]

onclick

{"action":"playStatusMeterExploji", "actorId":1, "value":"img/icon_smiley_sad_color.png"}

Script

LB.Actions.playStatusMeterExploji({actorId:1, value:"img/icon_smiley_neutral_color.png"});

getStatusMeterValue 2.12+

Get the current value of an avatar’s status meter.

Parameters

actorId

(optional) Actor for the status meter. If not supplied the default is the player avatar.

externalId

(optional) An avatar’s externalId. If set, this is used instead of actorId.

Return value

number/null

Current value of the status meter for the given avatar. “null” if no status meter is set.

Examples:

Script

LB.Actions.getStatusMeterValue({ actorId:1 });

pauseConversation 2.12+

Pauses the conversation after the current node has finished.

Parameters

immediate

(optional) Pauses the conversation immediately. The current dialog line will be stopped. This is equivalent to clicking the UI pause button. False by default.

resumeAfterMs

(optional) The conversation will be resumed after this delay.

Return value

null

Examples:

Script. Introduces a delay in the conversation after the current node of 3 seconds.

LB.Actions.pauseConversation({ resumeAfterMs:3000 });

resumeConversation 2.12+

After the conversation was paused, this action will resume it.

Parameters

 none

Return value

null

Examples:

Script

LB.Actions.resumeConversation();

repeatAction 2.12+

Repeat an action every N seconds. Generally used alongside stopRepeatingAction.

Parameters

actionName

(required) Name of the action to repeat.

interval

(required) Number of seconds between each repetition. For instance, 0.5 means that the action will be repeated every half second.

(other params)

Any parameters used by the action that will be repeated.

Return value

id

ID of the repeating interval that was created.

Examples:

Script

var intervalId = LB.Actions.repeatAction({ actionName:'playSFX', interval:1, url:'https://url-to-mp3-file', volume:50 });

stopRepeatingAction 2.12+

Stop an action from repeating. If an ID is provided, it will stop that action. Otherwise, it will stop all repeating actions triggered by repeatAction.

Parameters

id

(optional) ID of the interval to stop. Usually obtained as the return value of LB.Actions.repeatAction

Examples:

Script

LB.Actions.stopRepeatingAction({ id:intervalId });

LB.Actions.stopRepeatingAction();

UI.openLocations 2.12+

Open the locations menu, which contains a list of other locations in the same world.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openLocations"}

Script

LB.Actions.UI.openLocations();

UI.openAchievements 2.12+

Open the achievements menu, which contains a list of the tasks available in the space or world.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openAchievements"}

Script

LB.Actions.UI.openAchievements();

UI.openShare 2.12+

Open the sharing menu, which allows you to invite others into the space or world.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openShare"}

Script

LB.Actions.UI.openShare();

UI.openParticipants 2.12+

Open the participants menu, which contains a list of other users in the same world/space. This will show a notification if the current user is the only one.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openParticipants"}

Script

LB.Actions.UI.openParticipants();

UI.openSettings 2.12+

Open the settings menu.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openSettings"}

Script

LB.Actions.UI.openSettings();

UI.openProfile 2.12+

Open the profile menu of the current user, or of another user..

Parameters

externalId

(optional) the ID of the user whose profile should be visualized. If left empty, the user’s own profile (which can be edited) is shown.

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openProfile", "externalId":"123abc"}

 

Script

LB.Actions.UI.openProfile({externalId: '123abc'});

UI.openContacts 2.12+

Open the user’s contact and requests list.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openContacts"}

Script

LB.Actions.UI.openContacts();

UI.openSideMenu 2.12+

Open the left-side menu, usually triggered by clicking on the logo or hamburger menu icon (three horizontal bars) in the top left corner.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openSideMenu"}

Script

LB.Actions.UI.openSideMenu();

UI.openAdditionalMenu 2.12+

Open the right-side menu, usually triggered by clicking on the “more” (three vertical dots) icon in the top right corner.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openAdditionalMenu"}

Script

LB.Actions.UI.openAdditionalMenu();

UI.openAvatarCreator 2.12+

Open the avatar creator/customizer menu.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openAvatarCreator"}

Script

LB.Actions.UI.openAvatarCreator();

doNothing 2.13+

At times, you just want clicking on an object to still count as a click/tap, but do nothing.

Examples:

onclick

{"action":"doNothing"}

Script

LB.Actions.doNothing();

displayPoll 2.14+

Display a poll to users so that they might vote. If the user already voted in the poll, nothing will be displayed.

Parameters

pollId

(required) The ID of the poll whose options should be displayed.

Examples:

Script

LB.Actions.displayPoll({pollId: 3});

displayPollResults 2.14+

Display the results of a poll. Can be configured to display them as different types of charts on a mediaboard.

Parameters

pollId

(required) The ID of the poll whose results should be displayed.

type

(optional) The type of chart to display. Current options are “bar” and “pie”.

mediaboard

(optional) The name of the mediaboard the results should appear on

Examples:

Script

LB.Actions.displayPollResults({ pollId: 3, type: 'bar', mediaboard: 'Mediaboard_z9qf'});

UI.openQnA 2.14+

Show the Q&A panel.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.openQnA"}

Script

LB.Actions.UI.openQnA();

UI.displayDialInDetails 2.14+

Show dial-in details for built-in conferencing.

Parameters

hideOtherModals

(optional) If true, other modals will be hidden prior to opening this one. True by default.

Examples:

onclick

{"action":"UI.displayDialInDetails"}

Script

LB.Actions.UI.displayDialInDetails();

sendUserToSpace 2.14+

Teleports the user to another space in a World. This will only work within a World, it is not possible to send users to arbitrary spaces that are not part of the same World.

Parameters

externalId

(optional) User to apply the action to. If none is provided, the action will apply to the player.

externalIdList

(optional) An array of externalIds. Useful to send users in bulk so there’s no need to propagate one action per user.

spaceId

(required) The space to send the user to

force

(optional) When true, the popup displayed will not have a cancel button.

Examples:

onclick

{"action":"sendUserToSpace","spaceId":"spcXXXXXXXX","force":false}

Script

LB.Actions.sendUserToSpace({spaceId: "spcXXXXXXXX", force: false});

startTimer 2.15+

Starts a timer

Parameters

objectName

(required) Name of the object.

reset

Bool (optional, default false) If true, the timer is reset.

pauseTimer 2.15+

Pauses a timer

Parameters

objectName

(required) Name of the object.

resetTimer 2.15+

Resets a timer

Parameters

objectName

(required) Name of the object.

stop

Bool (optional, default true) If true, the timer will not start.

requestInput 2.15+

Ask users to provide an input. Optionally supports a "quiz mode" with a list of acceptable answers.

Parameters

id

(required) ID of the popup, will be supplied to the "OnInputReceived" event that fires once the user confirms

title

(required) Title of the popup

text

(required) Text of the popup (allows HTML)

inputLabel

Label to show above the input

answerList

If included, the input will be matched against these options, which allows for quizzes. Please note that when comparing with these options, the user’s input will be trimmed of any spaces at the beginning and end, and will be turned to lowercase.

allowWrongAnswers

If included alongside answerList, will allow the user to give a wrong answer (false by default, i.e. the default behaviour is for the popup to not disappear until the user answers correctly)

messageForWrongAnswers

If included alongside answerList, this message will be shown when a wrong answer is written. If allowWrongAnswers is true, this will of course not be displayed

showCloseButton

Whether the close button in the upper right corner should be shown; defaults to true

showCancelButton

Whether the red cancel button should be shown; default value is true

onClose

Function to run when the popup is closed. This parameter is only useful for Javascript masters 🙂

saveAnswerTo

Name of the variable in which the user input is stored. If not provided, the id will be used to generate such a variable, named “UserInput_<ID>”. This variable can be obtained with the getUserVariable action

dismissable

Whether users can dismiss the popup (true by default).

validator

A validating function, receiving what the user wrote as an input. It should return a falsy value for success, and a string (the validation message) for failure. Ignored if allowWrongAnswers is true.

forceLowerCase

(2.16+ only, default true) If set to true, it will force the answer to lowercase.

inputType

(2.16+ only, default text) Type of input
text one line
textarea multiline

storeInGamification

(2.16+ only, default false) Store answer in gamification as a collected item

Here is an example popup that shows how title, text and inputLabel appear

LB.Actions.requestInput({id:"Example1",  title:"Title",  text:"Text text text text text", inputLabel:"inputLabel"});

A typical popup might look like this

LB.Actions.requestInput({id:"Example2", title:"Answer me this!", text:"<i>This is the devious riddle written on the small note</i>", inputLabel:"2 + 2?", showCancelButton:false});

Retrieving answers

The answer entered by the user is saved to a variable called UserInput_<ID>, where <ID> is the ID of our popup. In our case that’s “Example2”, so the variable will be called “UserInput_Example2” and we can retrieve it with getUserVariable.

LB.Actions.getUserVariable({name: "UserInput_Example2"});

With the saveAnswerTo parameter it’s possible to define the destination variable, so if we called the action like this:

LB.Actions.requestInput({id:"Example2b", title:"Answer me this!", text:"<i>This is the devious riddle written on the small note</i>", inputLabel:"2 + 2?", showCancelButton:false, saveAnswerTo: "MyVariable"});

we could retrieve the value by doing

LB.Actions.getUserVariable({name: "MyVariable"});

Note that these variables are available in ChatMapper, and can therefore be used in your ChatMapper scripts and conditions as well.

Quizzing users

It’s possible to check the user’s input against a list of answers, provided through the answerList parameter.

LB.Actions.requestInput({id:"Example3", title:"🐻", text:"Write at least one bear color", answerList:["black", "brown", "white"]});

In this case, if the user writes any value that isn’t “black”, “brown” or “white” the popup will tell them their answer is wrong.

It’s possible to turn this off with the allowWrongAnswers parameter, and to customize the message with the messageForWrongAnswers parameter.

Validator example

In the example below, if the user does not write “black”, “brown”, or “white”, the validation message will say “Think about grizzly bears. What color are they?”

LB.Actions.requestInput({
id:
"Example4",
title:
"🐻",
text:
"Write at least one bear color",
answerList:[
"black", "brown", "white"],
 validator: function(input) {
 if([
"black", "brown", "white"].indexOf(input.toLowerCase()) === -1) {
  return
"Think about grizzly bears. What color are they?"
 }
 return
false;
},

});

dropConferenceCall 2.15+

Drop the current conference call, if any is active. This only works with built-in conferencing.

Parameters

affectHosts

(optional, default false) Whether the action works on hosts (Editors, Presenters)

notifyUser

(optional, default true) Show a notification to the user that a host disconnected them from the call

For example, this is how a user can be disconnected from a conference call (without showing a notification).

To execute this when they click on an object, it should be placed in the onclick field of that object, but it can also be activated with a zone trigger or in any other “action” field.

{"action":"dropConferenceCall", "affectHosts":true, "notifyUser":false}

zoomInObject 2.15+

Moves the camera towards the object and frames it fullscreen. Only supported objects are: Mediaboards, Slideshows, Whiteboards. This action doesn’t have any effect while in VR.

Parameters

objectName

(required) Name of the object to zoom-in to.

animate

(optional, default true) Camera will animate towards the shot

duration

(optional, default 1 sec) Duration of the animation

For example, zoom into a mediaboard.

{"action":"zoomInObject", "objectName":"Mediaboard_DpCG"}

zoomOutObject 2.15+

Exits zoom-in mode

For example, zoom out from the zoomed-in state. If the user is not zoomed into an object they will see no change to their view.

{"action":"zoomOutObject"}

avatarWalkTo 2.15+

Animates an avatar as they walk to the given destination.

Parameters

to

(required) Destination of the avatar, in an x,y,z format (see examples)

externalId

(optional) The ID of the avatar that should move (e.g. a bot’s ID). If left out, it will be the player’s avatar

from

(optional) The starting position of the animation. If omitted, it will be the current position of the selected avatar

speed

(optional) The animation speed (0.8 by default)

callback

(optional) A function to call when the animation is over

Examples

The correct format for the “from” and “to” parameters is {x:NUMBER, y:NUMBER, z:NUMBER}. The y value is the vertical axis, so in most cases unless the floor of your 3D environment is raised or recessed, it should not be modified.

An example of making a bot with ID “bot1234” walk from its current position to {x:10, y:0, z:10} is

LB.Actions.avatarWalkTo({externalId:"bot1234", to: {x:10, y:0, z:10}});

This can also be used in ChatMapper. For example, making the player walk from {x:0, y:0, z:0} to {x:2, y:0, z:-2} (and slightly faster than default) is

{"action":"avatarWalkTo", "from":{"x":0, "y":0, "z":0}, "to":{"x":2, "y":0, "z":-2}, "speed":1}

displayMediaboard 2.16+

Displays a 2d popup with embedded content

Parameters

url

(required) URL of the content to be embedded

id

(optional) The html id of the dom element. It will be randomly generated if not assigned

withBackground

(optional, default true) If set to true, a dark background will be displayed behind the popup

pauseConversation

(optional, default true) Conversations will be paused until the popup is closed

jumpNextWhenLoaded

(optional, default false) Conversation will jump to the next node after the content has been displayed

UI.setRaiseHand 2.16+

Set the raised hand state for the player.

Parameters

value

(default) If true, other modals will be hidden prior to opening this one. True by default.

Examples to raise hand:

onclick

{"action":"UI.setRaiseHand"}

Script

LB.Actions.UI.setRaiseHand();

onclick

{"action":"UI.setRaiseHand","value":true}

Script

LB.Actions.UI.setRaiseHand({value:true});

Examples to lower hand:

onclick

{"action":"UI.setRaiseHand","value":false}

Script

LB.Actions.UI.setRaiseHand({value:false});

rollDice 2.16+

Rolls a dice in the experience and shows the result in the chat.

Parameters

expression

(required) Expression to be used for the dice(s) in regular dice notation. Examples:
– 1d6 (roll 1 dice of 6 faces)
– 2d20 (roll 2 dice of 20 faces)
– 1d6 + 1d12 (roll 1d6, 1d12 and add both results together)

outputToChat

(optional, default true) If true, sends an announcement to the chat with the result

setCMVariable

(optional, default true) If true, sets a dialogue variable with the result

cmVariableName

(optional, default ‘rolldiceResult’) Name of the dialogue variable to set

Examples:

onclick

{"action":"rollDice", "expression":"2d6 + 10"}

setSlideshowIndex 2.16+

Sets the slide for a slideshow.

Parameters

objectName

(required) Name of the slideshow

index

(required) 0-based index for the slide to show

Examples:

On click (resets the slideshow to the first slide)

{"action":"setSlideshowIndex", "objectName":"mySlideshow", "index":0}

UI.takeScreenshot 3.0+

Takes a screenshot of the 3d environment and prompts the user to download as a file.

Parameters

fileName

(optional) Name for the file. Must include the extension .png

If not provided, the file is named after the space’s name.

Examples:

On click (resets the slideshow to the first slide)

{"action":"UI.takeScreenshot", "fileName":"myCapture.png"}

How useful was this article?

Click on a star to rate it!

We are sorry that this article was not useful for you!

Let us improve this article!

Tell us how we can improve this article?