Scenario Actions

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

Properties

nid/nodeid

cnvid (conversation ID)

actorId

Modes

Conversation mode

Exploration mode

API

playNode

playConversationId

playConversation (deprecated, use playConversationId)

teleportActorToSpotTag

teleportPlayerToSpotTag

setSpotTagActive

setItemStatus <2.8

setUserVariable

displayBasicPopup (deprecated, use displayNotification or displayIframe)

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+

playSFX 2.9+

playAmbient 2.9+

stopAmbient 2.9+

setObjectField 2.9+

displayImage 2.9+

setVolume 2.10+

changeMediaboardImage 2.11+

displayVideo 2.11+

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":"displayBasicPopup","title":"Popup Title","message":"Hello world!","buttonText":"OK"} ]

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)

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"});

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

Picture showing where to find this in ChatMapper

Modes

There are two modes in Scenario they are explained here

Conversation mode

Exploration mode

API

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

playConversation (deprecated, use playConversationId)

The playConversation() action plays a node of the conversation. To be overridden by playConversationId in the future.

Example: play conversation 5 starting at node 1

Dialogue

[action:"playConversation", cnvid:"5", nid:"1"]

onclick

{"action":"playConversation", "cnvid":"5", "nid":"1"}

Script

LB.Actions.playConversation({cnvid:"5", nid:"1"});

Parameters

cnvid

(required) ChatMapper conversation number to play

nid

(optional) ChatMapper dialogue node number in the current conversation

Return value

null


teleportActorToSpotTag

The teleportActorToSpotTag() teleports an actor to a hotspot.

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.

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

setItemStatus <2.8

The setItemStatus() sets a gamification item’s status.

Example: set a task as started

Dialogue

[action:"setItemStatus", itemType:"task", itemId:"make-friends", status:"started"]

onclick

{"action":"setItemStatus", "itemType":"task", "itemId":"make-friends", "status":"started"}

Script

LB.Actions.setItemStatus({itemType:"task", itemId:"make-friends", status:"started"});

Parameters

itemType

(required) type of "item" you're changing, e.g. `item`, `task`, etc.

itemId

(required) the uniqueID of the item in question (what in new gamification would be the propertyId)

status

(required) is any data, changes depending on the type of item

it's like the item's "primary" data

so for tasks it would be `started`, `not-started` or `complete`, but for a normal item it could be `collected`, for score it's a number, etc.

Return value

null


setUserVariable

The setUserVariable() sets a ChatMapper variable value 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


displayBasicPopup (deprecated, use displayNotification or displayIframe)

The displayBasicPopup() displays a simple popup message with a title and button.

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

Dialogue

[action:"displayBasicPopup", title:"The Popup Title", message:"Hello world!", buttonText:"OK"]

onclick

{"action":"displayBasicPopup", "title":"The Popup Title", "message":"Hello world!", "buttonText":"OK"}

Script

LB.Actions.displayBasicPopup({title:"The Popup Title", message:"Hello world!", buttonText:"OK"});

Parameters

title

(optional) the text to display in the top of the popup header (default) blank

message

(optional) the text to display as a message in the body of the popup (default) blank

buttonText

(optional) the text for the button that appears at the foot of the popup (default) 'OK'

Return value

null


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)

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 alpacacaforms website)

view

data

name

if none provided, LB.Forms.result 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 (defaul) Submit

saveToCMVariables

if true, responses will be set as ChatMapper variables too

width/height

string to be attached as css parameter (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

Not Yet Implemented: use the following in Script in the meantime

Script

window.open("https://www.w3schools.com");

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

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 "breathalizer" in the scene. Even if the item moves, the avatar will follow look at it

var b = LB.Utils.findItem("breathalizer");
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 overlay on top of the scene.

Example: fade the scene to black

Dialogue

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

onclick

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

Script

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

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"});

Parameters

duration

(optional) duration of the animation in milliseconds (default) 1000

direction

(required) "in" or "out" for fadein or fadeout of the scene

Return value

null

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:"XLS"]

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

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

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

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

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

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

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

onclick

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

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

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

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

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

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

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

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

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 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.playCustomMode({"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.executeAction(myObject, {"action":"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.executeAction(myObject, {"action":"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.executeAction(myObject, {"action":"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.

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

onclick

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

Script

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

Parameters

direction

(required) Whether it’s a fadein or a fadeout. Possible values:

  • "in"
  • "out"

objectName

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

Return value

null


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".

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.executeAction(myObject, {"action":"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.executeAction(myObject, {"action":"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

LB.Actions.executeAction(myObject, {"action":"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.executeAction(myObject, {"action":"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.

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.executeAction(myObject, {"action":"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.executeAction(myObject, {"action":"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

LB.Actions.executeAction(myObject, {"action":"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.

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

onclick

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

Script

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.

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.setItemStatus({"action":"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


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://url-to-mp3-file"]

onclick

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

Script

LB.Actions.playAmbient({url:"https://url-to-mp3-file"});

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.executeAction(null, {"action":"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://assets.learnbrite.com/my-username/my-image.jpg", "position":"top-right"}

Script

LB.Actions.displayImage({"url":"https://assets.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.

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 videos.

onclick

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

Script

LB.Actions.displayVideo({"url":"https://assets.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 (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 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 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).

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.

Return value

jQuery

A reference to the jQuery object of the video

setSentimentMeterVisible 2.11+

Displays a sentiment meter next to the avatar. This visual meter is used to represent the status (emotion) of the avatar, for example how happy or sad it is.

Parameters

visible

(required) true or false

actorId

(optional) actor for the sentiment 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 sentiment meter. Check the Sentiment Meter guide for setup parameters.

setSentimentMeterValue 2.11+

Changes the value of the sentiment meter for an avatar.

Parameters

actorId

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

externalId

(optional) avatar externalId (overwrites actorId)

value

(required) the value to be set

increment

(optional) if used, the parameter value will be ignored, and the increment will be added to the current value of the meter. The value 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 sentiment meter of the actor with id 1 by 2

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

onclick

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

Script

LB.Actions.changeMediaboardImage({action:"setSentimentMeterValue", actorId:1, increment:2});

© 2019 LearnBrite – Commercial In Confidence

Trademarks & Copyrights are property of their respective owners. Pictures are indicative only & may not reflect final production.

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!