Scenario Actions

Actions described here apply to Scenario version 2.5 or above

Triggering Actions from ChatMapper Dialogue

Triggering Actions from ChatMapper Scripts

Triggering Actions from Scenario onclick

Two Actions in One 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+

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+

Triggering Actions from ChatMapper Dialogue

Actions can be triggered from ChatMapper by adding javascript calls to the script tag, but they can also be launched using a special tag right in the dialogue node text.

Recommended convention is:

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

Scenario will also accept

[action:"actionName"  param1:"value"  param2:"value"] (spaces instead of commas)

[action="actionName", param1="value", param2="value"] (equal instead of colon)

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

Items in the 3d editor allow you to add onclick actions for mediaboards or 3D items.  These are accessible in Edit mode then choosing the Items List. Edit an item and if it has the onclick field you can place an action in there.

Two Actions in One 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.

Syntax

[ {action1}, {action2} ]

Example Teleport actor 1 to hotspot 2 AND display a popup with the title The Popup Title with a message Hello world! and a OK button

onclick

[ {"action":"teleportActorToSpotTag","actorId":"1","spotTag":"hotspot2"}, {"action":"displayBasicPopup","title":"The 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


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+

displayImage() displays an image in an arbitrary position (2D UI only, does not work in VR).

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

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:

  • 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. False by default.

pauseConversation

Whether the image should pause conversation until the image is closed. False 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});

© 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!