Variables

Variables enables you to store your own data structures in the Toto backend and access these via scripts in order to implement your own game mechanics.

The Toto game engine distinguishes between three kind of variables: system, implicit and dynamic.

System variables

System variables are defined by the system and provide system properties at runtime. These are:

name description
currentTime The current UNIX time in milliseconds.
dayOfWeek The day of the current week as a number between 1 (Monday) and 7 (Sunday).
dayOfMonth The day of the current month as a number.
dayOfYear The day of the current year as a number.

System variables are available in scripts but for all events. They are not provided to the client directly.

Implicit variables

These variables implicitly exists in the context of a session and can be accessed in various events.

name description
username Name which has been used to register in Toto.
screenName Currently choosen visible name of the user. This name can be edited anytime by the user.
userId ID of the user account.
score Total score of the user session.
teamName Name of the team the user is being part of.
sessionId ID of the session.
attendeeLang Language the user chose within the session.
elementId ID of the currently processed element.
elementTitle Title of the currently processed element.
challengeId ID of the currently processed challenge.
challengeTitle Title of the currently processed challenge.
storyId ID of the story the user is playing.
storyTitle Title of the story the user is playing.
repoId ID of the repository the currently played story belongs to.
repoTitle Title of the repository the currently played story belongs to.
solutionAt Timestamp of the moment where the element has been processed successfully (solving task, acknowledging info…).
solutionText Content of a text solution which has just been submitted to solve a task.
solutionInput Content of an user input solution text which just has been submitted successfully to solve a task.
solutionImageId ID of an user input solution image which just has been uploaded successfully to solve a task.
solutionImageUrl URL of an user input solution image which just has been uploaded successfully to solve a task.
solutionLat Latitude of a geofence solution which just has been submitted successfully to solve a task.
solutionLon Longitude of a geofence solution which just has been submitted successfully to solve a task.
solutionScore Score which has been gained by processing an element successfully (solving task, acknowledging info…).

Events

Not all of these implicit variables do exists for every trigger event. For example, for the trigger on story start, the implicit variable elementTitle does not exist, because in the context of starting a session, no element is involved and therefore no title can be provided. Here is a matrix which implicit variables are supported for which trigger event.

  on story initialize on story join on story start on story cancel on story finish on challenge release on challenge finish on element release (1) on element success (2) on element error (3) on task skip
username
screenName
userId
score
teamName
sessionId
attendeeLang
elementId              
elementTitle              
challengeId          
challengeTitle          
storyId
storyTitle
repoId
repoTitle
solutionAt                
solutionText (4)                
solutionInput (5)                
solutionImageId (5)                
solutionImageUrl (5)                      
solutionLat (6)                
solutionLon (6)                
solutionScore  

(1) Due to lack of space on element release represents the following events in this matrix: on task release, on info release, on choice release and on dynamic release.
(2) Due to lack of space on element success represents the following events in this matrix: on task solve, on info acknowledge, on choice make, on dynamic success and on coinc collect.
(3) Due to lack of space on element success represents the following events in this matrix: on task error and on dynamic error.
(4) Available for tasks containing the solution type text (multiple choice/free text).
(5) Available for tasks containing the solution type user input.
(6) Available for tasks containing the solution type geofence.

Dynamic variables

A dynamic variable can be seen as a definition of user data that can be used throughout a game session to build all kind of game mechanics. Variables are Toto entities, so they can have a name, a title, a description and so on.

During a game session, instances of these variables are created which contain the actual data. Theses instances will be created in a lazy way, which means, only if they are requested the first time.

There are two important properties a variable can have: type and scope.

Types

Toto currently supports three types:

name description
string A variable contains data which is interpreted as a text.
number A variable contains data which is interpreted as a number.
boolean A variable contains data which is interpreted as true or false.

Scopes

There are three different scopes a variable can have. The scope determines how instances of a particular variable are created.

name description
repository Using this scope there will only be one instance of this variable. If the variable is changed by a script, it is changed for everything and everyone throughout the repository.
user Using this scope, for each user an instance is created when it is first requested. Use this scope if you want to persist user specific data that will live for all stories/sessions in the repository where this variable is defined.
session Using this scope, an instance of this variable will be created for each session.

Scripting

Currently Toto supports JavaScript as a scripting language.

If a script returns an error or does not finish execution after 1000 ms, the value of the instance is left unchanged and an error message is logged as a TotoActivity which can be monitored at runtime in the activity tab.

Note

No support for 3rd party libraries is provided! You can use Vanilla JS (ECMAScript 5) only.

Usage

In scripts as well as in payloads you can reference variables. At runtime, these will be replaced by the values of the actual variable instances. If an instance does not exist yet (e.g. when it is used the first time), the defaultValue of a variable is used.

Syntax for accessing the value of a variable in scripts and paylods:

// system variable
{{s:<variable_name>}}

// implicit variable
{{i:<variable_name>}}

// dynamic variable
{{d:<variable_name>}}

Examples

Substitutes the username:

{{i:username}}

Substitutes the day of the current week as a number:

{{s:dayOfWeek}}

Substitutes the number of keys the user has collected so far (assuming there is a variable with name keysCollected defined):

{{d:keysCollected}}