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