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` ⁽¹⁾	`on element success` ⁽²⁾	`on element error` ⁽³⁾	`on task skip`
`username`	●	●	●	●	●	●	●	●	●	●	●
`screenName`	●	●	●	●	●	●	●	●	●	●	●
`userId`	●	●	●	●	●	●	●	●	●	●	●
`score`	●	●	●	●	●	●	●	●	●	●	●
`teamName`	●	●	●	●	●	●	●	●	●	●	●
`sessionId`	●	●	●	●	●	●	●	●	●	●	●
`attendeeLang`	●	●	●	●	●	●	●	●	●	●	●
`elementId`								●	●	●	●
`elementTitle`								●	●	●	●
`challengeId`						●	●	●	●	●	●
`challengeTitle`						●	●	●	●	●	●
`storyId`	●	●	●	●	●	●	●	●	●	●	●
`storyTitle`	●	●	●	●	●	●	●	●	●	●	●
`repoId`	●	●	●	●	●	●	●	●	●	●	●
`repoTitle`	●	●	●	●	●	●	●	●	●	●	●
`solutionAt`									●	●	●
`solutionText` ⁽⁴⁾									●	●	●
`solutionInput` ⁽⁵⁾									●	●	●
`solutionImageId` ⁽⁵⁾									●	●	●
`solutionImageUrl` ⁽⁵⁾
`solutionLat` ⁽⁶⁾									●	●	●
`solutionLon` ⁽⁶⁾									●	●	●
`solutionScore`	●	●	●	●	●	●	●		●	●	●

⁽¹⁾ 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.
⁽²⁾ 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.
⁽³⁾ Due to lack of space on element success represents the following events in this matrix: on task error and on dynamic error.
⁽⁴⁾ Available for tasks containing the solution type text (multiple choice/free text).
⁽⁵⁾ Available for tasks containing the solution type user input.
⁽⁶⁾ 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}}