The detailed guide on actions available within the platform. Actions described here apply to Scenario version 2.5 or above. If the action is only available from a certain version onwards, it will be indicated beside its name.
Triggering Actions from ChatMapper Dialogue
Triggering Actions from ChatMapper Scripts
Triggering Actions from Scenario onclick
Multiple actions within a single onclick
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"] |
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"} |
Hiding the mouse over feedback
This is useful when an object needs to be clickable but the experience needs the user not to tell when moving the mouse over the object (the default behavior is to show the hand cursor to highlight that the object is clickable)
By adding the parameter showFeedbackOver:false to the action, no feedback will be provided to the user. This is also useful when placing an invisible plane in order to avoid clicking through walls.
Following the example before, the action will result as:
{"action":"teleportActorToSpotTag", "actorId":"1", "spotTag":"hotspot2", "showFeedbackOver":false} |
Note: When using multiple actions, the parameter can be added to any of them.
Multiple actions within a single onclick
It is possible to trigger multiple actions on a single onclick. Note that all actions trigger at the same time, not one after the other.
The syntax is simple, it requires including all actions within square brackets, and separating each with a comma.
[ {action1}, {action2}, {action3} ] |
In the following example,
- Actor 1 is teleported to hotspot2, AND
- A popup is displayed with title "Popup Title", the message "Hello world!" and an OK button
[ {"action":"teleportActorToSpotTag","actorId":"1","spotTag":"hotspot2"}, {"action":"displayNotification","message":"Hello!"} ] |
Delaying Actions
You may want an action to happen a little after the node has started. You can achieve this with the delay attribute.
Example: play the yes gesture on the current actor after 2 seconds (2000 milliseconds)
There are two parameters available for specifying a delay:
- delayMs – takes a value in milliseconds, eg. 2000 milliseconds is 2 seconds
- delay – takes a value in seconds, eg. 2 seconds
delayMs
Dialogue
[action:"playGesture", name:"yes", delayMs:2000] |
onclick
{"action":"playGesture", "name":"yes", "delayMs":"2000"} |
Script
LB.Actions.playGesture({name:"yes", delayMs:2000}); |
Syntax
Dialogue
[action:"actionName", param1:"value", param2:"value", delayMs:"milliseconds"] |
onclick
{"action":"actionName", "param1":"value", "param2":"value", "delayMs":"milliseconds"} |
Script
LB.Actions.actionName({param1:"value", param2:"value", delayMs:"milliseconds"}); |
delay
Dialogue
[action:"playGesture", name:"yes", delay:2] |
onclick
{"action":"playGesture", "name":"yes", "delay":"2"} |
Script
LB.Actions.playGesture({name:"yes", delay:2}); |
Syntax
Dialogue
[action:"actionName", param1:"value", param2:"value", delay:"seconds"] |
onclick
{"action":"actionName", "param1":"value", "param2":"value", "delay":"seconds"} |
Script
LB.Actions.actionName({param1:"value", param2:"value", delay:"seconds"}); |
Conditional Actions
An action that only runs if an item was collected
{"action":"displayNotification", "message":"The door is now open", "condition":"item.goldenkey.collected"} |
Properties
nid/nodeid
Node ID is shown in the top left in the dialogue tree in ChatMapper
cnvid (conversation ID)
Conversation ID (cnvid) is shown in the left of the Conversations list in ChatMapper
actorId
ActorID is generally the order in which an avatar appears in the list, starting from one.
However:
Actors in ChatMapper store their ID at time of creation, so if at some point there were 5 actors and the fourth was deleted, actor #5 would still have ID=5.
The ID for bots is their bot ID, e.g. "bot2i39pthzmhp8fidw03232hat". This can be seen in the Bots app
Modes
There are two modes in Scenario they are explained here
Conversation mode
This mode is when you are actively in a scenario conversation (typically built in ChatMapper).
When in conversation mode a toolbar with conversation controls is shown at the bottom of the screen, by default it includes the controls to rewind, pause, fast forward, toggle captions and mute audio.
By default the camera in non-immersive devices will be locked on the conversation and any camera angles defined.
In immersive devices such as VR and AR the player can look around freely and the controls will follow as a heads up display (HUD) at the bottom of their view.
It is also possible to force the freedom of looking around while a conversation is playing in non-immersive devices. Simply add an extra parameter getIntoCMMode to the action and set it to false.
{"action":"playConversationId", "cnvid":6764, "getIntoCMMode":false} |
Exploration mode
Where the participant is free to look and move around the environment
API
Common parameters
propagate | (bool, optional, default false) The action will be propagated to all users in the space so it will run for every user |
propagationAllowedRoles | (string or array, optional, default empty) Restrict the propagation capabilities for these roles. Leaving this parameter empty will allow anybody to propagate the action |
onExecuted 2.15+ | (function, optional) This callback will be called when the action has been executed locally |
onRemotelyExecuted 2.15+ | (function, optional) This callback will be called when the action has been executed in other users’ devices. Argument: externalId |
delay | takes a value in seconds, eg. 2 seconds |
delayMs | takes a value in milliseconds, eg. 2000 milliseconds is 2 seconds |
condition | (string, optional) Gamification condition to be checked before running the action |
playNode
The playNode() action plays a node of the conversation.
Dialogue Example
[action:"playNode", nodeid:"5", getIntoCMMode:true] |
onclick Example
{"action":"playNode", "nodeid":"5", "getIntoCMMode":true} |
Script Example
LB.Actions.playNode({nodeid:"5", getIntoCMMode:true}); |
Parameters
nodeid | (required) ChatMapper dialogue node number in the current conversation |
getIntoCMMode | (optional) true to change game status to Conversation Mode (with prev/next/pause buttons and no navigation), false to remain in the current interaction mode (default) |
Return value
null |
playConversationId
The playConversationId() action plays a conversation optionally jumping to a specific node with control over the user interface mode of conversation or interactive.
Example: play ChatMapper conversation 5 and remain in interactive interface mode
Dialogue
[action:"playConversationId", cnvid:"5"] |
onclick
{"action":"playConversationId", "cnvid":"5"} |
Script
LB.Actions.playConversationId({cnvid:"5"}); |
Example: play ChatMapper conversation 5 from node 3 and use conversation interface
Dialogue
[action:"playConversationId", cnvid:"5", nid:"3", getIntoCMMode:true] |
onclick
{"action":"playConversationId", "cnvid":"5", "nid":"3", "getIntoCMMode":true} |
Script
LB.Actions.playConversationId({cnvid:"5", nid:"3", getIntoCMMode:true}); |
Parameters
cnvid | (required) ChatMapper conversation number to play |
nid | (optional) ChatMapper dialogue node number in the current conversation |
getIntoCMMode | (optional) true to change game status to Conversation Mode (with prev/next/pause buttons and no navigation), false to remain in the current interaction mode (default) |
Return value
null |
teleportActorToSpotTag
The teleportActorToSpotTag() teleports an actor to a hotspot with the matching spotTag name.
Each hotspot has a spotTag field, here you can enter any text name to identify the hotspot.
Note: a hotspot can only accept one character occupying it at one time. If you try to teleport an actor or player to the spot when it is occupied no action will be taken.
However, more than one hotspot can be given an identical spotTag name and the platform will randomly teleport to an unoccupied hotspot with the matching spotTag name.
Example: move actor 1 to hotspot2
Dialogue
[action:"teleportActorToSpotTag", actorId:"1", spotTag:"hotspot2"] |
onclick
{"action":"teleportActorToSpotTag", "actorId":"1", "spotTag":"hotspot2"} |
Script
LB.Actions.teleportActorToSpotTag({actorId:1, spotTag:"hotspot2"}); |
Parameters
actorId | (required) ChatMapper actor ID |
spotTag | (required) hotspot tag defined in the template’s 3d scene See VR Scenario – Bot Authoring section titled Actor Hotspots Assignments in Templates to see images of spot identifiers in the scenario templates. For example the office template hotspots are identified as follows: |
Return value
null |
teleportPlayerToSpotTag
The teleportPlayerToSpotTag() teleports the player to a hotspot.
Each hotspot has a spotTag field, here you can enter any text name to identify the hotspot.
Note: a hotspot can only accept one character occupying it at one time. If you try to teleport an actor or player to the spot when it is occupied no action will be taken and the user will see a notification that the hotspot is occupied.
However, more than one hotspot can be given an identical spotTag name and the platform will randomly teleport to an unoccupied hotspot with the matching spotTag name.
Example: teleport player to spot with name "hotspot2"
Dialogue
[action:"teleportPlayerToSpotTag", spotTag:"hotspot2"] |
onclick
{"action":"teleportPlayerToSpotTag", "spotTag":"hotspot2"} |
Script
LB.Actions.teleportPlayerToSpotTag({spotTag:"hotspot2"}); |
Example: teleport player to hotspot with id 2 and don’t animate the camera
Dialogue
[action:"teleportPlayerToSpotTag", spotTag:"hotspot2", immediate:"true"] |
onclick
{"action":"teleportPlayerToSpotTag", "spotTag":"hotspot2", "immediate":true} |
Script
LB.Actions.teleportPlayerToSpotTag({spotTag:"hotspot2", immediate:true}); |
Parameters
spotTag | (required) hotspot tag defined in the template’s 3d scene See VR Scenario – Bot Authoring section titled Actor Hotspots Assignments in Templates to see images of spot identifiers in the scenario templates. For example the office template hotspots are identified as follows: |
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: |
value | (optional) a value of true (default) enables the hotspot, false will disable the hotspot (default) |
Return value
null |
setUserVariable
Set a variable (which will also be reflected in ChatMapper) and updates objects in scene.
Example: set a ChatMapper variable users_name to Fred
Dialogue
[action:"setUserVariable", name:"users_name", value:"Fred"] |
onclick
{"action":"setUserVariable", "name":"users_name", "value":"Fred"} |
Script
LB.Actions.setUserVariable({name:"users_name", value:"Fred"}); |
Example: set a ChatMapper variable missionCompleted to true
Dialogue
[action:"setUserVariable", name:"missionCompleted", value:"true"] |
onclick
{"action":"setUserVariable", "name":"missionCompleted", "value":"true"} |
Script
LB.Actions.setUserVariable({name:"missionCompleted", value:"true"}); |
Parameters
name | (required) name of the ChatMapper variable |
value | (required) the value you wish to set the variable to |
Return value
null |
getUserVariable 2.15+
Get the value of a certain variable (which can be set from ChatMapper as well).
Example: get the “users_name” variable, defaulting to “Fred” if the variable is not defined/has no value
Dialogue
[action:"getUserVariable", name:"users_name", default:"Fred"] |
onclick
{"action":"getUserVariable", "name":"users_name", "default":"Fred"} |
Script
LB.Actions.getUserVariable({name:"users_name", default:"Fred"}); |
Parameters
name | (required) name of the variable requested |
default | A default value to return if the variable doesn’t exist |
Return value
mixed | The value of the variable requested |
displayNotification
The displayNotification() displays a notification in the top right of the screen, that can be fully customized.
Example: display a popup with the title The Popup Title with a message Hello world! and a OK button
Dialogue
[action:"displayNotification", message:"You just found a diamond!"] |
onclick
{"action":"displayNotification", "message":"You just found a diamond!"} |
Script
LB.Actions.displayNotification({message:"You just found a diamond!"}); |
Parameters
message | (required) the text to display as a message in the notification. Can be HTML. Following code displays a notification with a hyperlink: {"action":"displayNotification","message":"For more details about actions please visit <a href='https://hyperspace.mv/academy/scenario-actions/'>Scenario Actions Academy Page</a>"} |
type | (optional) the type of alert, it will change colors and default badge. See image below for every example. Available values are "success" (the default), "reward"(2.8+), "primary", "secondary", "warning", "error" or "danger", "info", "light", "dark" |
badgeText | (optional) the text to put in the badge, if any. This can also be HTML. |
fadeOutAfter | (optional) the number of milliseconds (thousandths of a second) after which the alert should start fading out |
fadeOutDuration | (optional) the number of milliseconds the fade-out animation will take |
playSfx | (optional, 2.9+) play a sound when displaying the notification. Defaults to false |
sfxSrc | (optional, 2.9+) the URL of the audio file to be played. If no URL is provided, a default sound will play. The URL can also be the local path of a file included within the Scenario (through a CMPKG upload) |
id | (optional, 3.0+) an identification to make the notification unique. Displaying a new notification using the same id will replace the previous one. |
Return value
null |
launchYammerFeed
The launchYammerFeed() pops up a Yammer feed.
Example: popup a basic yammer discussion board
Dialogue
[action:"launchYammerFeed", network:"hellonetwork", feedId:"0000000"] |
onclick
{"action":"launchYammerFeed", "network":"hellonetwork", "feedId":"0000000"} |
Script
LB.Actions.launchYammerFeed({network:"hellonetwork", feedId:"0000000"}); |
Example: popup an advanced yammer discussion board
Dialogue
[action:"launchYammerFeed", config:"{use_sso:true header:false footer:false showOpenGraphPreview:false defaultToCanonical:true hideNetworkName:true width:60vw height:40vw}", network:"hellonetwork", feedId:"0000000"] |
onclick
{"action":"launchYammerFeed", "config":"{use_sso:true header:false footer:false showOpenGraphPreview:false defaultToCanonical:true hideNetworkName:true width:60vw height:40vw}", "network":"hellonetwork", "feedId":"0000000"} |
Script
LB.Actions.launchYammerFeed({config:"{use_sso:true header:false footer:false showOpenGraphPreview:false defaultToCanonical:true hideNetworkName:true width:60vw height:40vw}", network:"hellonetwork", feedId:"0000000"}); |
Parameters
config | (required) an object containing: {use_sso:' ' header:' ' footer:' ' showOpenGraphPreview:' ' defaultToCanonical:' ' hideNetworkName:' ' width:' ' height:' '} |
network | (required) the yammer network name |
feedId | (required) the feedId in the yammer network |
Return value
null |
callFunction
The callFunction() calls a function – only applicable to window level functions and 1 parameter.
Example: call a function
Dialogue
[action:"callFunction", name:"alert", parameter:"hello"] |
onclick
{"action":"callFunction", "name":"alert", "parameter":"hello"} |
Script
LB.Actions.callFunction({name:"alert", parameter:"hello"}); |
Parameters
name | (required) name of the function to call |
parameter | (optional) one parameter to be passed to the function. If null, all parameters are passed in one object |
Return value
null |
displayIframe
The displayIframe() pops up a webpage.
Note: some sites have a security policy that blocks being displayed in an iFrame. You can confirm this by looking at your browser console for a message like:
Refused to display 'https://www.google.com/' in a frame because it set 'X-Frame-Options' to 'sameorigin'. |
Example: popup a basic iframe
Dialogue
LB.Actions.displayIframe({url:'https://wikipedia.org', header: 'Wikipedia'}); |
onclick
{"action":"displayIframe", "url":"https://wikipedia.org", "header": "Wikipedia"} |
Script
LB.Actions.displayIframe({url:'https://wikipedia.org', header: 'Wikipedia'}); |
Parameters
url | (required) source url of the page to display in the body of the popup |
isPersistent | (optional, 2.8+) a persistent iframe will not be removed from the page even if the modal is hidden, so for instance a video embedded in this way will keep playing in the background even if it’s not visible. True by default. |
header | (optional, 2.9+) the text to be included in the header of the modal, which will also include a "close" button. This text can be HTML. |
Return value
null |
displayForm
The displayForm() displays a form using web standard Alpaca Forms structure in a popup.
Script Example: popup a basic form
LB.Actions.displayForm({ |
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 = { |
The form popup (used in nodes where you want the form to popup)
LB.Actions.displayForm({ |
Parameters
Can contain any AlpacaForms parameter (schema, options, data, view, etc, (see documentation on AlpacaForms website)
view | |
data | |
name | if no name is provided, LB.Forms.results will be the result of that form. If a name is provided, it will be a property inside LB.Forms.results |
title | the title for the popup |
buttonText | the submit button text (default) Submit |
saveToCMVariables | if true, responses will be set as ChatMapper variables too |
width/height | string to be attached as css parameter (e.g. 100px, 100vw, 100em – px, vw, or em must be present) |
callback | (formSettings, results) – callback will be triggered when the form is submitted. Not compatible with multiuser actions in 2.7+ |
schema | can be object or string |
options | can be object or string |
Return value
null |
exitConversation
The exitConversation() exits the current ChatMapper conversation.
Example: exit the current conversation
Dialogue
[action:"exitConversation"] |
onclick
{"action":"exitConversation"} |
Script
LB.Actions.exitConversation(); |
Example: exit the current conversation and return to the previous space (of this world)
Dialogue
[action:"exitConversation", returnToLastScene:"true"] |
onclick
{"action":"exitConversation", "returnToLastScene":true] |
Script
LB.Actions.exitConversation({returnToLastScene:true}); |
Parameters
returnToLastScene | (optional) true returns to the last space (only in multi-space worlds), false stays in the current space (default) |
Return value
null |
openURLInNewWindow
The openURLInNewWindow() opens the url in a new window with a given title.
Example: open a new tab/window showing the given url
Dialogue
[action:"openURLInNewWindow", url:"https://google.com"] |
onclick
{"action":"openURLInNewWindow", "url":"https://google.com"} |
Script
LB.Actions.openURLInNewWindow({url:"https://google.com"}); |
Example: open a new tab/window showing the given url and title
Dialogue
[action:"openURLInNewWindow", url:"https://google.com", title:"Search_Tab"] |
onclick
{"action":"openURLInNewWindow", "url":"https://google.com", "title":"Search_Tab"} |
Script
LB.Actions.openURLInNewWindow({url:"https://google.com", title:"Search_Tab"}); |
Parameters
url | (required) source url of the page to display in the new tab/window |
title | (optional) the text of the name for the new tab/window, can be useful to reference through script or to re-user/load content into the same named tab again later (default) blank |
Return value
null |
playGesture
The playGesture() action causes a named animation to be played on a character. Learn more about gestures here.
Example: play the yes gesture on the current actor
Dialogue
[action:"playGesture", name:"yes"] |
onclick
{"action":"playGesture", "name":"yes"} |
Script
LB.Actions.playGesture({name:"yes"}); |
Example: play the no gesture on actor 2 and play it over 2.5 seconds (2500 milliseconds)
Dialogue
[action:"playGesture", name:"no", actorId:"2", duration:"2500"] |
onclick
{"action":"playGesture", "name":"no", "actorId":"2", "duration":"2500"} |
Script
LB.Actions.playGesture({name:"no", actorId:2, duration:"2500"}); |
Parameters
name | (required) name of animation (see Scenario Gestures docs for full list) |
actorId | (optional) if not supplied the gesture will play on the current talking avatar of the dialogue node |
externalId | (optional) the externalId of the avatar is also accepted |
duration | (optional) duration of gesture animation (default) 2000 milliseconds. |
mask | (optional) defines which parts of the body the animation is applied to. Check the Animation Masks section below. Default is set in the state such as standing (FULL), sitting (torso up), sitting-idle Available animation masks: FULL BOT MID TOP HEAD LEGS ARMS MOUTH EYES EYEBALLS EYEBROWS ARM_LEFT ARM_RIGHT HEADNOEYEBALLS FACE FACENOEYEBALLS TORSOLEGS EYELIDS HEADNOFACE NONE TORSOHEAD CHAIRBOT HANDS |
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:
- lookTarget (if it's not null)
- ChatMapper conversant (if we're in a ChatMapper conversation)
- 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
- Hotspot target (if defined)
- 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({ |
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({ |
Script Example: look at an item "breathalyzer" in the scene. Even if the item moves, the avatar will follow look at it
var b = LB.Utils.findItem("breathalyzer"); |
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({ |
Parameters
actorId | (optional) ChatMapper ID of the actor |
avatar | (optional) avatar object (will override actorId) |
lookTarget | (optional) target, this applies to the ChatMapper CAF avatar_lookTarget and the avatarLookAt action null – avatar won’t take this parameter into account when updating its look direction string: "camera" – looks at the currentCamera "none" – unsets the lookTarget (sets the parameter to null) "Name of an object" – looks for an object with that name to make the lookTarget number – looks for an actor with that ID to be the lookTarget object – is it THREE.Object3D? Then look at its position (deprecated in 2.7+, use object name instead) vector3D – look at this position |
Return value
null |
fadeScene
The fadeScene() shows a black (customizable) overlay on top of the scene.
Note: fadeScene does not apply to VR/AR, it uses a 2D HTML layer which is only visible outside immersive view.
Parameters
direction | (required) "in" or "out" for fade-in or fade-out. |
duration | (optional) duration of the animation in milliseconds. Default is 1000 |
color | (optional, 2.12+) color of the overlay, black by default. Any CSS-valid color property is accepted. |
opacity | (optional, 2.12+) opacity of the overlay, from 0 (invisible) to 1 (completely opaque). 1 by default. |
clickThrough | (optional, 2.12+) if true, the user can interact with the scene. If false, interactions are blocked. False by default, it can be useful to set it as true with low-opacity overlays. |
Return value
null |
Example: fade the scene to black
Dialogue
[action:"fadeScene", direction:"out"] |
onclick
{"action":"fadeScene", "direction":"out"} |
Script
LB.Actions.fadeScene({direction:"out"}); |
Example: fade the scene to yellow
Dialogue
[action:"fadeScene", direction:"out", color:"yellow"] |
onclick
{"action":"fadeScene", "direction":"out", "color":"yellow"} |
Script
LB.Actions.fadeScene({direction:"out", color:"yellow"}); |
Example: fade in scene from black
Dialogue
[action:"fadeScene", direction:"in"] |
onclick
{"action":"fadeScene", "direction":"in"} |
Script
LB.Actions.fadeScene({direction:"in"}); |
Example: fade in the scene from black to visible over 1.5 seconds
Dialogue
[action:"fadeScene", duration:"1500", direction:"in"] |
onclick
{"action":"fadeScene", "duration":"1500", "direction":"in"} |
Script
LB.Actions.fadeScene({duration:"1500", direction:"in"}); |
forceCameraShot
The forceCameraShot() forces the camera shot for some time, only in exploration mode.
Example: animate the camera shot (see shot code explanations below)
Dialogue
[action:"forceCameraShot", shotName:"XCU"] |
onclick
{"action":"forceCameraShot", "shotName":"XLS"} |
Example: animate the camera for 1 second to do a Big Close Up for 3 seconds
Dialogue
[action:"forceCameraShot", duration:"3000", animationTime:"1000", shotName:"BCU"] |
onclick
{"action":"forceCameraShot", "duration":"3000", "animationTime":"1000", "shotName":"BCU"} |
Script
LB.Actions.forceCameraShot({duration:"3000", animationTime:"1000", shotName:"BCU"}); |
Parameters
duration | (optional) forces the shot for a number of milliseconds |
animationTime | (optional) duration of animation |
shot | (optional) json object defining the new custom shot including a new shotName. Only use shot parameter if defining a new custom camera shot, use shotName parameter below for preconfigured camera shots |
shotName | (optional) name of a preconfigured shot to use, one of:
|
XLS (Extra Long Shot) | LS (Long Shot) | MLS (Medium Long Shot) | MS (Medium Shot) |
| |||
MCU (Medium Close Up) | CU (Close Up) | BCU (Big Close Up) | XCU (Extra Close Up) |
OSL (Over the Shoulder, Left) (2.9+) | OSR (Over the Shoulder, Right) (2.9+) |
Return value
null |
playCustomNode 2.7+
The playCustomNode() executes a custom node using the Chatmapper dialog system. It can be used to have a bot speak custom text when clicked. Additional parameters from the Chatmapper dialog system can be used. See CM CAF document for more information.
Example: Make the player avatar say something without changing the camera shot (not entering CM mode)
Dialogue
<not applicable> |
onclick
{"action":"playCustomNode", "text":"This is a test"} |
Script
LB.Actions.playCustomNode({text:"This is a test"}); |
Example: Make the actor id 2 say something to actor id 3 going into CM Mode to use the avatar shot feature
Dialogue
<not applicable> |
onclick
{"action":"playCustomNode", "actorId":2, "conversantId":3, "text":"Hello John, how are you?", "getIntoCMMode":true, "avatar_shot":"CU"} |
Script
LB.Actions.playCustomNode({"actorId":2, "conversantId":3, "text":"Hello John, how are you?", "getIntoCMMode":true, "avatar_shot":"CU"}); |
Example: Make the actor id 2 say something to camera using a customs shot. Ignoring the parameter conversantId makes the actor look at the camera.
Dialogue
<not applicable> |
onclick
{"action":"playCustomNode", "actorId":2, "text":"You can look around you to find hidden objects", "getIntoCMMode":true, "avatar_shot":"MS"} |
Script
LB.Actions.playCustomNode({"actorId":2, "text":"You can look around you to find hidden objects", "getIntoCMMode":true, "avatar_shot":"MS"}); |
Parameters
text | (required) text that will get spoken by the avatar |
actorId | (optional) actor which will speak. If not supplied the default is the player avatar. |
avatar | (optional) avatar object (overwrites actorId) (deprecated in 2.7+, use externalId instead) |
externalId | (optional) avatar externalId (overwrites actorId) |
conversantId | (optional) actor the speaker will look to. If not supplied the speaker will look at camera |
conversantAvatar | (optional) conversant avatar object (overwrites conversantId) |
getIntoCMMode | (optional) whether or not game status is changed to CM mode (with prev/next/pause buttons and no navigation) (default is false) |
<additional parameters> | Any Chatmapper node field is compatible, including Custom Asset Fields (CAF). See examples. |
Return value
null |
lookAt 2.7+
The lookAt() rotates the object towards a defined target..
Example: Make the object always face the camera (for billboards / animated sprites)
onfixedupdate
{"action":"lookAt", "target":"camera"} |
Script
LB.Actions.lookAt({"target":"camera"}); |
Parameters
target | (required) Target object to look at. Can be:
|
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 a named object or multiple tagged objects in the scene.
Example: Hide the object as default in the scene
onstart
{"action":"setObjectVisible", "visible":false} |
Script
LB.Actions.setObjectVisible({"visible":false}); |
Example: When clicked on this object, hide another object in the scene defined by objectName or if objectName is the name of a tag, hide all objects with the matching tag.
onclick
{"action":"setObjectVisible", "visible":false, "objectName":"otherObject"} |
Script
LB.Actions.setObjectVisible({"visible":false, "objectName":"otherObject"}); |
Parameters
visible | (required) boolean value for visibility. |
objectName | (optional) object to apply the action to or name of a tag in multiple objects. If not set, the action will be applied to the object triggering it. |
Return value
null |
fadeObject 2.7+
The fadeObject() shows or hides an object in the scene with a fade effect.
Parameters
direction | (required) whether it’s a fade-in or a fade-out. Possible values:
|
objectName | (optional) object to apply the action to. If not set, the action will be applied to the object triggering it. |
duration | (optional) how long the transition should take, in seconds. The default is 0.7s |
Return value
null |
Example: When clicked on this object, fade another object in.
onclick
{"action":"fadeObject", "direction":"in", "objectName":"otherObject"} |
Script
LB.Actions.fadeObject({"direction":"in", "objectName":"otherObject"}); |
navigateTo 2.8+
The navigateTo() action will teleport the user to a different space within a world. Using a spaceId that is not from the same world will have no effect.
Two special values can be used: "next" and "previous". They will teleport the user to the following and preceding space in the world, respectively. This is mostly useful in "linear" worlds, where a user is expected to move from one space to another following their order.
Recommend using sendUserToSpace action instead. However navigateTo does respect space Access Code setting and will prompt for a code before allowing teleportation.
onclick
{"action":"navigateTo", "spaceId":"spc123456"} |
Script
LB.Actions.navigateTo({"spaceId":"spc123456"}); |
Parameters
spaceId | (required) the spaceId to teleport to. Can be "next" or "previous". |
showConfirmation | (optional, 2.14+) show the user a confirmation popup before teleporting them. True by default |
name | (optional, 2.14+) name of the space shown in the confirmation popup |
Return value
null |
startTask 2.8+
The startTask() action sets a task’s status as ‘started’.
Example: set a certain task as started when the user clicks on an object.
onclick
{"action":"startTask", "shortcode":"funny-sun-ae3e"} |
Script
LB.Actions.startTask({"shortcode":"funny-sun-ae3e"}); |
Parameters
shortcode | (required if propertyId is not used) The task’s shortcode, usually obtained from app.learnbrite.com/trophio. |
propertyId | (required if shortcode is not used) The task’s propertyId, usually obtained from app.learnbrite.com/trophio. |
Return value
null |
completeTask 2.8+
The completeTask() action sets a task’s status as ‘complete’.
Example: complete a certain task when the user clicks on an object.
onclick
{"action":"completeTask", "shortcode":"funny-sun-ae3e"} |
Script
LB.Actions.completeTask({"shortcode":"funny-sun-ae3e"}); |
Parameters
shortcode | (required if propertyId is not used) The task’s shortcode, usually obtained from app.learnbrite.com/trophio. |
propertyId | (required if shortcode is not used) The task’s propertyId, usually obtained from app.learnbrite.com/trophio. |
Return value
null |
getTaskStatus 2.8+
The getTaskStatus() action gets a task’s status.
Example: during a treasure hunt, the user finds a certain object, but we only set the task as complete if it was already "started" when the object was found.
onclick
{"action":"getTaskStatus", "shortcode":"funny-sun-ae3e"} |
Script
result = LB.Actions.getTaskStatus({"shortcode":"funny-sun-ae3e"}); |
Parameters
shortcode | (required if propertyId is not used) The task’s shortcode, usually obtained from app.learnbrite.com/trophio. |
propertyId | (required if shortcode is not used) The task’s propertyId, usually obtained from app.learnbrite.com/trophio. |
Return value
string | The task’s status (one of "not-started", "started", or "complete") |
updateTask 2.8+
The updateTask() action sets a task’s status to the given one.
Example: the user can find three different objects, two pieces of a map or a whole map. If they find one of the pieces, we set the task as ‘started’. If they find the whole map (whether in one go or by collecting the two pieces) we set the task as complete.
onclick
{"action":"updateTask", "shortcode":"funny-sun-ae3e", "status":"started"} |
Script
LB.Actions.updateTask({"shortcode":"funny-sun-ae3e", "status":"started"}); |
Parameters
shortcode | (required if propertyId is not used) The task’s shortcode, usually obtained from app.learnbrite.com/trophio. |
propertyId | (required if shortcode is not used) The task’s propertyId, usually obtained from app.learnbrite.com/trophio. |
status | (required) the new status of this task (one of "not-started", "started", or "complete") |
Return value
null |
collectItem 2.8+
The collectItem() action "collects" an item by marking its status as "collected".
Example: in a treasure hunt, this is useful to mark an item as collected.
onclick
{"action":"collectItem", "item":"towel"} |
Script
LB.Actions.collectItem({"item":"towel"}); |
Parameters
item | (required) the item’s name. |
Return value
null |
dropItem 2.8+
The dropItem() action "drops" an item by marking its status as "dropped". Note that this won’t delete the item from the user’s inventory.
Example: in a multiuser treasure hunt, there could be only one "copy" of an item, that can be stolen from its current owner by doing something. The item could then be set as "collected" for the new owner and as "dropped" for the previous one.
onclick
{"action":"dropItem", "item":"towel"} |
Script
LB.Actions.dropItem({"item":"towel"}); |
Parameters
item | (required) the item’s name. |
Return value
null |
checkIfCollected 2.8+
The checkIfCollected() action checks if the given item is marked as "collected".
Example: only show a special hotspot if an item called "key" has been found.
onclick
{"action":"checkIfCollected", "item":"towel"} |
Script
result = LB.Actions.checkIfCollected({"item":"towel"}); |
Parameters
item | (required) the item’s name. |
Return value
boolean | true if the item is collected, false otherwise. |
getItemStatus 2.8+
The getItemStatus() action returns the status of the given item.
Important note: this only applies to the space it is called in. An itemStatus can be set and retrieved only in the same space, the itemStatus is not available in other spaces in a world.
Example: display a mediaboard only if a certain item was collected.
onclick
{"action":"getItemStatus", "item":"towel"} |
Script
result = LB.Actions.getItemStatus({item:"towel"}); |
Parameters
item | (required) the item’s name. |
Return value
string | the item’s status |
setItemStatus 2.8+
The setItemStatus() action sets an item’s status to the given one.
Important note: this only applies to the space it is called in. An itemStatus can be set and retrieved only in the same space, the itemStatus is not available in other spaces in a world.
Example: set an item as collected or dropped based on a certain condition.
onclick
{"action":"setItemStatus", "item":"towel", "status":"started"} |
Script
LB.Actions.setItemStatus({item:"towel", status:"started"}); |
Parameters
item | (required) the item’s name. |
status | (required) the new status for the item. |
Return value
null |
playExplojis 2.8+
The playExplojis() action creates a particle effect at the avatar’s head made from emojis
Example: Play a set of predefined explojis
onclick
{"action":"playExplojis", "text":":)"} |
Script
LB.Actions.playExplojis("text":":)"}); |
Example: Trigger an array of custom emojis
Dialogue
[action:"playExplojis", emojisArr:["😁","❤"]] |
onclick
{"action":"playExplojis", "emojisArr":["😁","❤"]} |
Script
LB.Actions.playExplojis({"emojisArr":["😁","❤"]}); |
Parameters
actorId | (optional) actor which will speak. If not supplied the default is the player avatar. |
avatar | (optional) avatar object (overwrites actorId) (deprecated in 2.7+, use externalId instead) |
externalId | (optional) avatar externalId (overwrites actorId) |
text | (optional) text with emojis. Only some of them are supported for now:
|
emojisArr | (optional) array of emojis to display |
Return value
null |
setAvatarMood 2.8+
The setAvatarMood() action changes the mood of an avatar, affecting its idle animation and other gestures. Available moods:
- (empty) – Default mood
- blue
- hiphop
- preppy
- angry
- happy
- waiting
Example: set the mood happy on the current actor
Dialogue
[action:"setAvatarMood", mood:"happy"] |
onclick
{"action":"setAvatarMood", "mood":"happy"} |
Script
LB.Actions.setAvatarMood({mood:"happy"}); |
Example: set the mood angry on actor 2
Dialogue
[action:"setAvatarMood", mood:"angry", actorId:"2"] |
onclick
{"action":"setAvatarMood", "mood":"angry", "actorId":"2"} |
Script
LB.Actions.setAvatarMood({mood:"angry", actorId:"2"}); |
Parameters
mood | (required) name of mood |
actorId | (optional) if not supplied the gesture will play on the current talking avatar of the dialogue node |
externalId | (optional) the externalId of the avatar is also accepted |
Return value
null |
setVideoboardControls 2.8+
Control a video element in the 3D environment. Use videoForcePlay to start the video playing, use videoForcePause to pause the video.
Dialogue
[action:"setVideoboardControls","video":"Mediaboard_[NAME]", videoForcePlay:"true"] |
onclick
{"action":"setVideoboardControls","video":"Mediaboard_[NAME]", "videoForcePlay":true} |
Script
LB.Actions.setVideoboardControls({videoForcePlay:true,video:"Mediaboard_[NAME]"}); |
Example of setting video controls for Staff,Owner,Editors, Presenters but restricting controls to Zoom, Mute and Back for participants
{"action":"setVideoboardControls","type":"video","video":"Mediaboard_[NAME]","videoControlAllowedRoles":"Owner,Editor,Presenter,Staff","videoProxy":false,"videoHlsLoopFix":true} |
Example of looping a video with no controls
{"action":"setVideoboardControls","type":"video","video":"Mediaboard_[NAME]","videoControlAllowedRoles":"","videoProxy":false,"videoHlsLoopFix":true,"loop":true} |
Parameters
video | Name of the mediaboard/object on which this action is called |
videoSource | Change the video URL to another |
videoPreviousSource | If true, go back to the previous URL used |
videoCurrentTime | Go to a selected time in the video |
videoForcePause | Force a pause |
videoForcePlay | Force playing the video |
videoControlAllowedRoles | Roles that are allowed to control the video playback (default Owner,Editor,Presenter,VIP,User,Guest,Staff) |
syncVideoStatus | Synchronize the status of the video across users (default true). 2.14+ |
videoSyncAllowedRoles | Only allow synchronization for these roles (default Editor,Presenter,Staff,Owner). 2.14+ |
loop | Whether the video should loop (false by default) 2.14+ |
muted | Whether the video should be muted (false by default) 2.14+ |
volume | The volume of the video, from 0 to 100 (the default) 2.15+ |
Return value
null |
playSFX 2.9+
The playSFX() action plays a sound given by a url
Parameters
url | (required) url address of the file |
loop | (optional) the sound will repeat. Default is false |
volume | (optional) Volume to apply to this sound (ignores the volume settings). Range is 0 to 100. |
Example:
Dialogue
[action:"playSFX", url:"https://url-to-mp3-file"] |
onclick
{"action":"playSFX", "url":"https://url-to-mp3-file"} |
Script
LB.Actions.playSFX({url:"https://url-to-mp3-file", volume:50}); |
playAmbient 2.9+
The playAmbient() action plays a sound given by a url as a background ambient
Parameters
url | (required) url address of the file |
loop | (optional) the sound will repeat. Default is true |
resume | (optional) When stopped and played again, the sound will resume from where it was stopped. Default is true |
volume | (optional) Volume to apply to this sound (ignores the volume settings). Range is 0 to 100. |
Example:
Dialogue
[action:"playAmbient", url:"https://cache.learnbrite.com/_assets_/audio/ambientmusic/Roboskater.mp3",volume:5] |
onclick
{"action":"playAmbient","url":"https://cache.learnbrite.com/_assets_/audio/ambientmusic/Roboskater.mp3","volume":5} |
Script
LB.Actions.playAmbient({url:"https://cache.learnbrite.com/_assets_/audio/ambientmusic/Roboskater.mp3",volume:5}); |
stopAmbient 2.9+
The stopAmbient() stops the background sound
Parameters
Example:
Dialogue
[action:"stopAmbient"] |
onclick
{"action":"stopAmbient"} |
Script
LB.Actions.stopAmbient({}); |
setObjectField 2.9+
The setObjectField() action modifies a parameter for the selected object. The parameter must be one of the editableFields supported by that object.
Example: When the specified object is clicked, change the html content in the Note.
onclick
{"action":"setObjectField", "objectName":"Note-ABCD-1234", "fieldName":"innerHTML", "fieldValue":"This is a note"} |
Script
LB.Actions.setObjectField({"objectName":"Note-ABCD-1234", "fieldName":"innerHTML", "fieldValue":"This is a note"}); |
Parameters
fieldName | (required) Name of the field to change |
fieldValue | (required) Value for the field |
objectName | Object to apply the action to. If not set, the action will be applied to the object triggering it. |
Return value
null |
displayImage 2.9+
Display an image in an arbitrary position.
onclick
{"action":"displayImage", "url":"https://cache.learnbrite.com/my-username/my-image.jpg", "position":"top-right"} |
Script
LB.Actions.displayImage({"url":"https://cache.learnbrite.com/my-username/my-image.jpg", "position":"top-right"}); |
Parameters
url | (required) URL of the image |
position | One of the following. Note that this will not have an effect when in VR:
|
id | The HTML id given to the modal |
lifetime | The number of seconds the image should stay on screen. The default value is 0, a special value to make the image stay on screen indefinitely. Note that this is always overridden by the time it takes for the text in the node in the node to be read out loud (unless no text is present). |
altText | Set the alt text of the image, for accessibility purposes. Empty by default. |
showCloseButton | Whether a close button should be shown on the image. True by default. |
pauseConversation | Whether the image should pause conversation until the image is closed. True by default. |
closeButtonStyle | (2.12+) The default (0) will show an X button in the top right corner. Setting this to 1 will show a button with text below the image. |
closeButtonText | (2.12+) If closeButtonStyle is 1, this parameter can be used to set the text of the button. |
closeButtonOverlapsImage | (2.12+) If closeButtonStyle is 1, this parameter decides whether the button should be within the area of the image (true) or outside (false, the default). |
Return value
jQuery | A reference to the jQuery object of the image |
setVolume 2.10+
Sets the audio volume. Can set the volume for specific types of sounds. All volume ranges are from 0 to 100.
Parameters
volume | (optional) Volume to be applied to all types of sounds. |
SFXVolume | (optional) Volume for effect sounds. |
ambientVolume | (optional) Volume for ambient sounds. |
speechVolume | (optional) Volume for speech sounds. |
Example:
Sets the volume as 50 for all sounds
Dialogue
[action:"setVolume", volume:50] |
onclick
{"action":"setVolume", volume:50} |
Script
LB.Actions.setVolume({volume:50}); |
Sets the volume as 0 for sound effects (SFX)
Dialogue
[action:"setVolume", SFXVolume:0] |
onclick
{"action":"setVolume", SFXVolume:0} |
Script
LB.Actions.setVolume({SFXVolume:0}); |
Sets the volume as 0 for ambient audio
Dialogue
[action:"setVolume", ambientVolume:0] |
onclick
{"action":"setVolume", ambientVolume:0} |
Script
LB.Actions.setVolume({ambientVolume:0}); |
Sets the volume as 0 for speech
Dialogue
[action:"setVolume", speechVolume:0] |
onclick
{"action":"setVolume", speechVolume:0} |
Script
LB.Actions.setVolume({speechVolume:0}); |
changeMediaboardImage 2.11+
Changes the displayed image on a mediaboard. An image set this way won’t be saved (it will revert to the original when reloading). Only works with image mediaboards, i.e. mediaboards created from an image link.
Parameters
name | (required) name of the mediaboard of which the image needs to be changed |
url | (required) URL of the new image |
Return value
Object | A javascript reference to the mediaboard |
Examples:
[action:"changeMediaboardImage", name:"Mediaboard_laptop", url:"https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Random-image.jpg/640px-Random-image.jpg"] |
onclick
{"action":"changeMediaboardImage", "name":"Mediaboard_laptop", "url":"https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Random-image.jpg/640px-Random-image.jpg"} |
Script
LB.Actions.changeMediaboardImage({name:"Mediaboard_laptop", url:"https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Random-image.jpg/640px-Random-image.jpg"}); |
displayVideo 2.11+
Displays a video in an arbitrary position. Currently only supports mp4 and YouTube videos.
onclick
{"action":"displayVideo", "url":"https://cache.learnbrite.com/my-username/my-video.mp4", "position":"center-large"} |
Script
LB.Actions.displayVideo({"url":"https://cache.learnbrite.com/my-username/my-video.mp3=4", "position":"top-right"}); |
Parameters
url | (required) URL of the video |
position | One of the following. Note that this will not have an effect when in VR.
|
id | The id given to the HTML element. |
lifetime | The number of seconds the video should stay on screen. The default value is 0, a special value to make the video stay on screen indefinitely. Note that, unless no text is present, this is always overridden by the time it takes for the text in the node in the node to be read out loud. |
showCloseButton | Whether a close button should be shown. True by default. |
pauseConversation | Whether showing the video should pause conversation until the video is closed. True by default. |
autoplay | Autoplay the video, if allowed. In Immersive/VR mode, this will automatically mute the video (even if “muted” is false). True by default. |
loop | Whether the video should loop when finished. False by default. |
controls | Show video controls (true by default). In Immersive/VR, this will only show the mute/unmute button. |
muted | Whether the video should be muted. False by default. |
poster | URL of the image to display before the video is started. Empty by default, and does not have an effect in Immersive/VR. |
hideBorder | By default, a white border is shown around the video. By setting this to true, it’s hidden. |
Return value
jQuery | A reference to the jQuery object of the video |
setStatusMeterVisible 2.12+
Displays a status meter on the avatar. This visual meter is used to represent any status of the avatar, for example how happy or sad it is, health, energy, progress, etc.
Parameters
visible | (required) true or false |
actorId | (optional) actor for the status meter. If not supplied the default is the player avatar. |
externalId | (optional) avatar externalId (overwrites actorId) |
Advanced parameters can be supplied as part of the action to configure the status meter. Check the Status Meter guide for setup parameters.
setStatusMeterValue 2.12+
Changes the value of the status meter for an avatar.
Parameters
actorId | (optional) actor for the status meter. If not supplied the default is the player avatar. |
externalId | (optional) avatar externalId (overwrites actorId) |
value | (optional) the value to be set |
increment | (optional) if increment is provided along with a value, the parameter value will be ignored, and the increment will be added to the current value of the meter. The increment can be negative to subtract points. |
animate | (optional) the progress bar will animate. Default is true |
shootExplojis | (optional) explojis will be launched. Default is true. |
Examples:
Increment the status meter of the actor with id 1 by 2
[action:"setStatusMeterValue", actorId:1, increment:2] |
onclick
{"action":"setStatusMeterValue", "actorId":1, "increment":2} |
Script
LB.Actions.setStatusMeterValue({actorId:1, increment:2}); |
setAvatarOutfit 2.11+
Changes the appearance of the avatar. It can clone the aspect of another avatar supplying an externalId, or replace individual pieces by supplying sku numbers. It can also do both at the same time.
Important note: Not specifying actorId or externalId will result in the changes being applied to the player. So, when propagating the action, make sure you specify the externalId of the avatar you want the outfit to change, otherwise the outfit will be changed for each user’s main avatar.
Important note: An sku may be designed for a particular body shape such as masculine or feminine. Changing the sku to one that uses an alternative body shape to the current avatar can swap the mesh creating unexpected results.
Parameters
actorId | (optional) actor to apply the outfit to. If not supplied the default is the player avatar. |
externalId | (optional) avatar externalId (overwrites actorId) |
copyFromExternalId | (optional) externalId of the avatar to clone the aspect from. |
<drawer> | (optional) if a SKU used, this piece of clothing will replace the existing one for this drawer. This value will override the outfit loaded by using copyFromExternalId. This value can also be set to false and it will act as a mask for the outfit loaded by copyFromExternalId. See examples below. |
save 2.16+ | (optional) If set to true, the outfit will be saved permanently. In multiuser settings you should propagate the action so all other participants see the outfit update. Propagating the action through multiuser is designed to only execute the save action once at the origin. |
Examples:
Replace the whole outfit of the player with the aspect from bot with externalId 12345678
[action:"setAvatarOutfit", copyFromExternalId:"bot12345678"] |
onclick
{"action":"setAvatarOutfit", "copyFromExternalId":"bot12345678"} |
Script
LB.Actions.setAvatarOutfit({copyFromExternalId:"bot12345678"}); |
Replace the player’s outfit with the aspect from bot with externalId 12345678, but keep the original face, eyes, and skin
[action:"setAvatarOutfit", copyFromExternalId:"bot12345678", face:false, eyes:false, skin:false] |
onclick
{"action":"setAvatarOutfit", "copyFromExternalId":"bot12345678", "face":false, "eyes":false, "skin":false} |
Script
LB.Actions.setAvatarOutfit({copyFromExternalId:"bot12345678", face:false, eyes:false, skin:false}); |
Replace the player’s outfit with the aspect from bot with externalId 12345678, leave the face untouched and force the hair to be the sku 9876
[action:"setAvatarOutfit", copyFromExternalId:"bot12345678", face:false, hair:9876] |
onclick
{"action":"setAvatarOutfit", "copyFromExternalId":"bot12345678", "face":false, "hair":9876} |
Script
LB.Actions.setAvatarOutfit({copyFromExternalId:"bot12345678", face:false, hair:9876}); |
Replace the avatar’s tshirt with the one with sku 100133, save the change permanently and propagate the action so all other participants see the outfit update.
[action:"setAvatarOutfit", torso:100133, save:true, propagate:true] |
onclick
{"action":"setAvatarOutfit", "torso":100133, save:true, propagate:true} |
Script
LB.Actions.setAvatarOutfit({torso:100133,save:true,propagate:true}); |
playStatusMeterExploji 2.12+
Triggers the exploji animation on an avatar’s status meter. Check the Status Meter guide for setup parameters.
Parameters
actorId | (optional) actor for the status meter. If not supplied the default is the player avatar. |
externalId | (optional) avatar externalId (overwrites actorId) |
value | (required) the emoji to be displayed. Can be a url or a previously configured emoji related to an action:
Check the Status Meter guide for detailed information about these values. |
Three useful values are:
img/icon_smiley_sad_color.png | img/icon_smiley_neutral_color.png | img/icon_smiley_happy_color.png |
Examples:
Dialogue Text
[action:"playStatusMeterExploji", actorId:1, value:"img/icon_smiley_happy_color.png"] |
onclick
{"action":"playStatusMeterExploji", "actorId":1, "value":"img/icon_smiley_sad_color.png"} |
Script
LB.Actions.playStatusMeterExploji({actorId:1, value:"img/icon_smiley_neutral_color.png"}); |
getStatusMeterValue 2.12+
Get the current value of an avatar’s status meter.
Parameters
actorId | (optional) Actor for the status meter. If not supplied the default is the player avatar. |
externalId | (optional) An avatar’s externalId. If set, this is used instead of actorId. |
Return value
number/null | Current value of the status meter for the given avatar. “null” if no status meter is set. |
Examples:
Script
LB.Actions.getStatusMeterValue({ actorId:1 }); |
pauseConversation 2.12+
Pauses the conversation after the current node has finished.
Parameters
immediate | (optional) Pauses the conversation immediately. The current dialog line will be stopped. This is equivalent to clicking the UI pause button. False by default. |
resumeAfterMs | (optional) The conversation will be resumed after this delay. |
Return value
null |
Examples:
Script. Introduces a delay in the conversation after the current node of 3 seconds.
LB.Actions.pauseConversation({ resumeAfterMs:3000 }); |
resumeConversation 2.12+
After the conversation was paused, this action will resume it.
Parameters
none
Return value
null |
Examples:
Script
LB.Actions.resumeConversation(); |
repeatAction 2.12+
Repeat an action every N seconds. Generally used alongside stopRepeatingAction.
Parameters
actionName | (required) Name of the action to repeat. |
interval | (required) Number of seconds between each repetition. For instance, 0.5 means that the action will be repeated every half second. |
(other params) | Any parameters used by the action that will be repeated. |
Return value
id | ID of the repeating interval that was created. |
Examples:
Script
var intervalId = LB.Actions.repeatAction({ actionName:'playSFX', interval:1, url:'https://url-to-mp3-file', volume:50 }); |
stopRepeatingAction 2.12+
Stop an action from repeating. If an ID is provided, it will stop that action. Otherwise, it will stop all repeating actions triggered by repeatAction.
Parameters
id | (optional) ID of the interval to stop. Usually obtained as the return value of LB.Actions.repeatAction |
Examples:
Script
LB.Actions.stopRepeatingAction({ id:intervalId }); LB.Actions.stopRepeatingAction(); |
UI.openLocations 2.12+
Open the locations menu, which contains a list of other locations in the same world.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openLocations"} |
Script
LB.Actions.UI.openLocations(); |
UI.openAchievements 2.12+
Open the achievements menu, which contains a list of the tasks available in the space or world.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openAchievements"} |
Script
LB.Actions.UI.openAchievements(); |
UI.openShare 2.12+
Open the sharing menu, which allows you to invite others into the space or world.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openShare"} |
Script
LB.Actions.UI.openShare(); |
UI.openParticipants 2.12+
Open the participants menu, which contains a list of other users in the same world/space. This will show a notification if the current user is the only one.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openParticipants"} |
Script
LB.Actions.UI.openParticipants(); |
UI.openSettings 2.12+
Open the settings menu.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openSettings"} |
Script
LB.Actions.UI.openSettings(); |
UI.openProfile 2.12+
Open the profile menu of the current user, or of another user..
Parameters
externalId | (optional) the ID of the user whose profile should be visualized. If left empty, the user’s own profile (which can be edited) is shown. |
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openProfile", "externalId":"123abc"} |
Script
LB.Actions.UI.openProfile({externalId: '123abc'}); |
UI.openContacts 2.12+
Open the user’s contact and requests list.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openContacts"} |
Script
LB.Actions.UI.openContacts(); |
UI.openSideMenu 2.12+
Open the left-side menu, usually triggered by clicking on the logo or hamburger menu icon (three horizontal bars) in the top left corner.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openSideMenu"} |
Script
LB.Actions.UI.openSideMenu(); |
UI.openAdditionalMenu 2.12+
Open the right-side menu, usually triggered by clicking on the “more” (three vertical dots) icon in the top right corner.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openAdditionalMenu"} |
Script
LB.Actions.UI.openAdditionalMenu(); |
UI.openAvatarCreator 2.12+
Open the avatar creator/customizer menu.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openAvatarCreator"} |
Script
LB.Actions.UI.openAvatarCreator(); |
doNothing 2.13+
At times, you just want clicking on an object to still count as a click/tap, but do nothing.
Examples:
onclick
{"action":"doNothing"} |
Script
LB.Actions.doNothing(); |
displayPoll 2.14+
Display a poll to users so that they might vote. If the user already voted in the poll, nothing will be displayed.
Parameters
pollId | (required) The ID of the poll whose options should be displayed. |
Examples:
Script
LB.Actions.displayPoll({pollId: 3}); |
displayPollResults 2.14+
Display the results of a poll. Can be configured to display them as different types of charts on a mediaboard.
Parameters
pollId | (required) The ID of the poll whose results should be displayed. |
type | (optional) The type of chart to display. Current options are “bar” and “pie”. |
mediaboard | (optional) The name of the mediaboard the results should appear on |
Examples:
Script
LB.Actions.displayPollResults({ pollId: 3, type: 'bar', mediaboard: 'Mediaboard_z9qf'}); |
UI.openQnA 2.14+
Show the Q&A panel.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.openQnA"} |
Script
LB.Actions.UI.openQnA(); |
UI.displayDialInDetails 2.14+
Show dial-in details for built-in conferencing.
Parameters
hideOtherModals | (optional) If true, other modals will be hidden prior to opening this one. True by default. |
Examples:
onclick
{"action":"UI.displayDialInDetails"} |
Script
LB.Actions.UI.displayDialInDetails(); |
sendUserToSpace 2.14+
Teleports the user to another space in a World. This will only work within a World, it is not possible to send users to arbitrary spaces that are not part of the same World.
Parameters
externalId | (optional) User to apply the action to. If none is provided, the action will apply to the player. |
externalIdList | (optional) An array of externalIds. Useful to send users in bulk so there’s no need to propagate one action per user. |
spaceId | (required) The space to send the user to |
force | (optional) When true, the popup displayed will not have a cancel button. |
Examples:
onclick
{"action":"sendUserToSpace","spaceId":"spcXXXXXXXX","force":false} |
Script
LB.Actions.sendUserToSpace({spaceId: "spcXXXXXXXX", force: false}); |
startTimer 2.15+
Starts a timer
Parameters
objectName | (required) Name of the object. |
reset | Bool (optional, default false) If true, the timer is reset. |
pauseTimer 2.15+
Pauses a timer
Parameters
objectName | (required) Name of the object. |
resetTimer 2.15+
Resets a timer
Parameters
objectName | (required) Name of the object. |
stop | Bool (optional, default true) If true, the timer will not start. |
requestInput 2.15+
Ask users to provide an input. Optionally supports a "quiz mode" with a list of acceptable answers.
Parameters
id | (required) ID of the popup, will be supplied to the "OnInputReceived" event that fires once the user confirms |
title | (required) Title of the popup |
text | (required) Text of the popup (allows HTML) |
inputLabel | Label to show above the input |
answerList | If included, the input will be matched against these options, which allows for quizzes. Please note that when comparing with these options, the user’s input will be trimmed of any spaces at the beginning and end, and will be turned to lowercase. |
allowWrongAnswers | If included alongside answerList, will allow the user to give a wrong answer (false by default, i.e. the default behaviour is for the popup to not disappear until the user answers correctly) |
messageForWrongAnswers | If included alongside answerList, this message will be shown when a wrong answer is written. If allowWrongAnswers is true, this will of course not be displayed |
showCloseButton | Whether the close button in the upper right corner should be shown; defaults to true |
showCancelButton | Whether the red cancel button should be shown; default value is true |
onClose | Function to run when the popup is closed. This parameter is only useful for Javascript masters 🙂 |
saveAnswerTo | Name of the variable in which the user input is stored. If not provided, the id will be used to generate such a variable, named “UserInput_<ID>”. This variable can be obtained with the getUserVariable action |
dismissable | Whether users can dismiss the popup (true by default). |
validator | A validating function, receiving what the user wrote as an input. It should return a falsy value for success, and a string (the validation message) for failure. Ignored if allowWrongAnswers is true. |
forceLowerCase | (2.16+ only, default true) If set to true, it will force the answer to lowercase. |
inputType | (2.16+ only, default text) Type of input |
storeInGamification | (2.16+ only, default false) Store answer in gamification as a collected item |
Here is an example popup that shows how title, text and inputLabel appear
LB.Actions.requestInput({id:"Example1", title:"Title", text:"Text text text text text", inputLabel:"inputLabel"}); |
A typical popup might look like this
LB.Actions.requestInput({id:"Example2", title:"Answer me this!", text:"<i>This is the devious riddle written on the small note</i>", inputLabel:"2 + 2?", showCancelButton:false}); |
Retrieving answers
The answer entered by the user is saved to a variable called UserInput_<ID>, where <ID> is the ID of our popup. In our case that’s “Example2”, so the variable will be called “UserInput_Example2” and we can retrieve it with getUserVariable.
LB.Actions.getUserVariable({name: "UserInput_Example2"}); |
With the saveAnswerTo parameter it’s possible to define the destination variable, so if we called the action like this:
LB.Actions.requestInput({id:"Example2b", title:"Answer me this!", text:"<i>This is the devious riddle written on the small note</i>", inputLabel:"2 + 2?", showCancelButton:false, saveAnswerTo: "MyVariable"}); |
we could retrieve the value by doing
LB.Actions.getUserVariable({name: "MyVariable"}); |
Note that these variables are available in ChatMapper, and can therefore be used in your ChatMapper scripts and conditions as well.
Quizzing users
It’s possible to check the user’s input against a list of answers, provided through the answerList parameter.
LB.Actions.requestInput({id:"Example3", title:"🐻", text:"Write at least one bear color", answerList:["black", "brown", "white"]}); |
In this case, if the user writes any value that isn’t “black”, “brown” or “white” the popup will tell them their answer is wrong.
It’s possible to turn this off with the allowWrongAnswers parameter, and to customize the message with the messageForWrongAnswers parameter.
Validator example
In the example below, if the user does not write “black”, “brown”, or “white”, the validation message will say “Think about grizzly bears. What color are they?”
LB.Actions.requestInput({ |
dropConferenceCall 2.15+
Drop the current conference call, if any is active. This only works with built-in conferencing.
Parameters
affectHosts | (optional, default false) Whether the action works on hosts (Editors, Presenters) |
notifyUser | (optional, default true) Show a notification to the user that a host disconnected them from the call |
For example, this is how a user can be disconnected from a conference call (without showing a notification).
To execute this when they click on an object, it should be placed in the onclick field of that object, but it can also be activated with a zone trigger or in any other “action” field.
{"action":"dropConferenceCall", "affectHosts":true, "notifyUser":false} |
zoomInObject 2.15+
Moves the camera towards the object and frames it fullscreen. Only supported objects are: Mediaboards, Slideshows, Whiteboards. This action doesn’t have any effect while in VR.
Parameters
objectName | (required) Name of the object to zoom-in to. |
animate | (optional, default true) Camera will animate towards the shot |
duration | (optional, default 1 sec) Duration of the animation |
For example, zoom into a mediaboard.
{"action":"zoomInObject", "objectName":"Mediaboard_DpCG"} |
zoomOutObject 2.15+
Exits zoom-in mode
For example, zoom out from the zoomed-in state. If the user is not zoomed into an object they will see no change to their view.
{"action":"zoomOutObject"} |
avatarWalkTo 2.15+
Animates an avatar as they walk to the given destination.
Parameters
to | (required) Destination of the avatar, in an x,y,z format (see examples) |
externalId | (optional) The ID of the avatar that should move (e.g. a bot’s ID). If left out, it will be the player’s avatar |
from | (optional) The starting position of the animation. If omitted, it will be the current position of the selected avatar |
speed | (optional) The animation speed (0.8 by default) |
callback | (optional) A function to call when the animation is over |
Examples
The correct format for the “from” and “to” parameters is {x:NUMBER, y:NUMBER, z:NUMBER}. The y value is the vertical axis, so in most cases unless the floor of your 3D environment is raised or recessed, it should not be modified.
An example of making a bot with ID “bot1234” walk from its current position to {x:10, y:0, z:10} is
LB.Actions.avatarWalkTo({externalId:"bot1234", to: {x:10, y:0, z:10}}); |
This can also be used in ChatMapper. For example, making the player walk from {x:0, y:0, z:0} to {x:2, y:0, z:-2} (and slightly faster than default) is
{"action":"avatarWalkTo", "from":{"x":0, "y":0, "z":0}, "to":{"x":2, "y":0, "z":-2}, "speed":1} |
displayMediaboard 2.16+
Displays a 2d popup with embedded content
Parameters
url | (required) URL of the content to be embedded |
id | (optional) The html id of the dom element. It will be randomly generated if not assigned |
withBackground | (optional, default true) If set to true, a dark background will be displayed behind the popup |
pauseConversation | (optional, default true) Conversations will be paused until the popup is closed |
jumpNextWhenLoaded | (optional, default false) Conversation will jump to the next node after the content has been displayed |
UI.setRaiseHand 2.16+
Set the raised hand state for the player.
Parameters
value | (default) If true, other modals will be hidden prior to opening this one. True by default. |
Examples to raise hand:
onclick
{"action":"UI.setRaiseHand"} |
Script
LB.Actions.UI.setRaiseHand(); |
onclick
{"action":"UI.setRaiseHand","value":true} |
Script
LB.Actions.UI.setRaiseHand({value:true}); |
Examples to lower hand:
onclick
{"action":"UI.setRaiseHand","value":false} |
Script
LB.Actions.UI.setRaiseHand({value:false}); |
rollDice 2.16+
Rolls a dice in the experience and shows the result in the chat.
Parameters
expression | (required) Expression to be used for the dice(s) in regular dice notation. Examples: |
outputToChat | (optional, default true) If true, sends an announcement to the chat with the result |
setCMVariable | (optional, default true) If true, sets a dialogue variable with the result |
cmVariableName | (optional, default ‘rolldiceResult’) Name of the dialogue variable to set |
Examples:
onclick
{"action":"rollDice", "expression":"2d6 + 10"} |
setSlideshowIndex 2.16+
Sets the slide for a slideshow.
Parameters
objectName | (required) Name of the slideshow |
index | (required) 0-based index for the slide to show |
Examples:
On click (resets the slideshow to the first slide)
{"action":"setSlideshowIndex", "objectName":"mySlideshow", "index":0} |
UI.takeScreenshot 3.0+
Takes a screenshot of the 3d environment and prompts the user to download as a file.
Parameters
fileName | (optional) Name for the file. Must include the extension .png If not provided, the file is named after the space’s name. |
Examples:
On click (resets the slideshow to the first slide)
{"action":"UI.takeScreenshot", "fileName":"myCapture.png"} |