Variables, data, references
Variables allow you to use changeable values in your actions. Variables are placeholders for text, numerical values or more complex data that only get a fixed value once the action is executed.
Variables are identified in adaptor:ex by enclosing two square brackets. That might look like this:
[[Player.name]]
At the moment when we design our level, it is still unclear which Player will play the level later - and therefore the name is still variable .
If a session of the level is then started in live mode and the action is executed, [[Player.name]] is replaced by the name of the player that is currently playing the level.
In this Twilio Send SMS action we use a variable to personalize how the player is being addressed:
If the level is played by a player for whom the name 'Ada Lovelace' was saved somewhere else, the SMS will look like this: Hello Ada Lovelace! How is it going?
Variables can be used in almost any action. You can drag a variable from the TOOLBAR 's VARIABLES MENU into your action or type it in yourself.
In the VARIABLES TOOLBAR you will find the variables that adaptor:ex has collected from existing data. However, there can also be variables that are not (yet) listed there, and the variables in the TOOLBAR could also refer to nothing at the moment they are called.
Variables, especially Items, can contain other variables. Therefore, the TOOLBAR is structured similar to a file directory. If you drag a variable over, the path that leads to the actual variable would be added.
There are different places in adaptor:ex where variable data is stored and different ways of referencing that data. In the following paragraph, you will find out how to create, change and use variable data in adaptor:ex.
Local Variables
Local variables are data that only last for the course of a level session.
For example, with the Set Data action, you can create a local variable and assign it a value, or modify an existing one.
For example, you can save the information at one point in the level as to whether a player has taken the left or the right path, so that you can go back to it at the end of the game.
You can later use this variable in a text or use it in the Switch Logic action to determine which state to continue with.
Level Attributes
In the level -> config you can specify Attributes for your level. Attributes allow you to set properties for your level.
Address Attributes at the appropriate level by prefixing the variable level, i.e. :
[[level.reward]]
Each live session of the level accesses the same variable here. So if a level attribute is changed in one session, it will be changed for all sessions.
Levels Attribute can be used well in the launch session. Then you can determine the level that should be started based on its attributes.
Collections and Data Items
Each Data Item is a data set that can have different properties and is associated with a collection of items.
Note
A good introduction to working with collections and items is the tutorial on creating and using a synonym dictionary.
Under Game -> settings -> collections you will find the data items that currently exist in your game. Here you can also add new items, change the properties of existing items or create a completely new collection.
With the Add Item action you can create new items in one of your collections during the course of a level.
Data items can be used in every level and persist if the session of a level is finished. This is important e.g. if your game is played by different players, who make different progress during the game, collect points, change their name and so on.
Plugins like telegram and twilio automatically create new items in the players collection, e.g. when a game is contacted by a previously unknown phone number. Therefore every adaptor:ex game has a players collection from the beginning.
There are several ways to use data items in a level.
Name Reference
Data items that have a name property that is already known can be used with it directly.
[[players.Ada]]
gives you the data item with the name property Ada in the players collection.
To get a property of the data item, add it to the end, separated with dot notation. E.g.:
Hello Ada, your score is [[players.Ada.score]]
Info
Names that are used in this way must not contain spaces.
Inline Query
The database type that feeds adaptor:ex behind the scenes allows us to use find queries to refer to items. find queries can be very complex and impressive. Most of the time, however, we only need very simple, easy-to-understand queries to get the right data.
Mark inline queries by enclosing them in curly brackets. Usually, we use a key and a value to make a query to the database.
[[players.{name:'Ada'}.score]] returns the same item and value as the variable above, which works with the name property. But we can do more with queries.
For example, we can also use any other properties that an item has acquired throughout the game to identify it.
[[players.{location:'At the pub'}.score]] gives us the score of the players collection who is At the pub at the moment. Note that as long as the value is a string, it must be enclosed in quotes.
Queries offer many other ways of finding items. If you want to learn more about it, take a look at the documentation of mongo DB - the database type that adaptor:ex works with.
Referencing items
With the data action Get Item you can link items to a variable name during the level.
Using a query (see above) or the item's name property, you can address it and give it a name that will be valid throughout the level. You can then use the item's properties via dot notation. For example: [[MyItem.some_value]]
The following Get Item action:
Will create a reference CurrentLocation to e.g. the following item from the locations collection:
All following actions in this level can then access the item with CurrentLocation:
Also some other actions (e.g. Add Item) allow to directly reference items created by the action. The item is created independently of the level session and is still present at the end of the session, but it can be read and modified directly in the level with the specified reference name.
Level Arguments
When a session is started based on a level, it is possible to forward items as arguments. This means that the reference to an item is created when a session is started.
Arguments can be edited, removed and added in the level config. Here we can also specify default references that will be used in the level session if no other item was specified for this argument when the level session was started.
Each level already has a Player argument defined at the beginning. The other argument settings are optional. With collection it can be specified from which collection the item that is passed must come from. Default allows to specify which item will be referenced if no other item is specified for this argument at the start of the levels session.
Which item is passed in a newly started level session is determined when the session is launched. If you create a session manually in live mode you can specify the reference at startup. Also the control action Launch Session allows to specify level arguments via the arguments property.
When launching a level session, arguments can also be forwarded that were not defined in the level config. The reference name is then set when starting the session or by editing the Launch Session action.
To access the item inside the level, we use the name of the argument. As with other item references, we can use it to insert, modify and add new item properties. For example, if we want to use the phone_number property of the Player argument, we use dot notation, as with name and query references.
[[Player.phone_number]]
Depending on which players item was passed manually or automatically at level session start, [[Player.phone_number]] refers to the phone_number property of the respective player.
Plugins like telegram and twilio automatically pass level arguments if there are incoming messages from contacts for which no level is running yet. If such a default level is started, it is checked if there is an item in the players collection with appropriate contact data (e.g. a phone number) to pass this item to the level session as Player argument. If no suitable item exists, a new one is created and then passed to the level session as Player argument.
If you create a reference with Get Item or another action that has the same name as one of the level arguments, the argument will be overwritten with the new reference.
Referencing multiple items
It is possible to refer to several items at the same time under one reference name. This can be the case if you formulate an Inline Query or the find query in Get Item in such a way that it matches several items in a collection.
The query players.{score:3} refers to all items in the players collection that have a score of 3. This can be none, 1 or several items.
The query players.{} even refers to all items that are in the players collection.
If you use a query that refers to several items, for example in the Set action, the respective variables in all items that match the query are changed or created.
With the settings option multiple items all DATA actions allow you to specify whether all items or only 1 item should be effected by the action.
Some actions always use only one item, even if several items are referenced. This is the case, for example, when a variable of an item is used inside a text.
E.G.: Even if players.{score:3} refers to several items in the players collection, [[players.{score:3}.name]] will only output one name.
If you want to make sure what value will be used, try to formulate the corresponding query more precisely or take a look at the $sort, $limit and $skip operators.
Sort and narrow down item references
In some cases the order in which items are referenced or returned might be important. Use $sort to determine within a query how the found items should be sorted.
Specify the parameter sorting is based on within an object, together with the direction, 1 for ascending and -1 for descending. For example, $sort:{the_value:1} to sort in ascending order according to the_value.
[[teams.{$sort:{score:1}}.name]] for example results in the name of the team with the highest score value.
If no sorting is specified, data items are arranged in the order in which they were added to the collection.
With the $sort query we can adjust the order for further use. [[teams.{$sort:{score:1}}.name]] would then result in green in the teams list above.
| name | level | score |
|---|---|---|
| green | 3 | 12 |
| red | 1 | 8 |
| blue | 2 | 6 |
| yellow | 3 | 5 |
| purple | 1 | 3 |
You can use more than one parameter to determine the order of items.
[[teams.{$sort:{level:-1, name:1}}.name]] will results in the name of the team with the lowest level. If there are several teams with the same level value, they are sorted by name. (here: purple)
| name | level | score |
|---|---|---|
| purple | 1 | 3 |
| red | 1 | 8 |
| blue | 2 | 6 |
| green | 3 | 12 |
| yellow | 3 | 5 |
Note
In the Get Item query or with Iterate you can of course use $sort to access the complete, then sorted list of referenced items.
In addition to $sort you can use the operators $skip and $limit to determine more precisely which items are returned within the query selection.
With $skip you can determine how many items will be left out up front. skip: 2 in example will make the query only return or reference the 3rd item that corresponds to the query or rather the items from the 3rd onwards.
In our example case [[teams.{$skip:2}.name]] will result in green, being the first items name that is not skipped.
| name | level | score |
|---|---|---|
| blue | 2 | 6 |
| red | 1 | 8 |
| green | 3 | 12 |
| purple | 1 | 3 |
| yellow | 3 | 5 |
With $limit you can set a maximum number of items that will be returned or referenced.
For example, {$limit:3} will result in a maximum of 3 items being referenced or returned.
| name | level | score |
|---|---|---|
| blue | 2 | 6 |
| red | 1 | 8 |
| green | 3 | 12 |
| purple | 1 | 3 |
| yellow | 3 | 5 |
$limit obviously has no effect if you only access the value of a single item or have set multiple to false.
Note
The $sort, $limit and $skip query operators follow the syntax of the corresponding mongodb cursor methods sort(), limit() and skip().
You can of course also, in addition to other query parameters, use all 3 operators within one query .
For example, use
to limit the query to teams that have a score > 3 and only get the teams 2 and 3 from the teams with the highest level value.
| name | level | score |
|---|---|---|
| green | 3 | 12 |
| yellow | 3 | 5 |
| blue | 2 | 6 |
| purple | 1 | 3 |
| red | 1 | 8 |
Action Data
Some actions save data that occurs during the game and thus make it possible to access it throughout the level.
Such action data can be read using the keyword state, the state name in which the action is located, and the name of the action:
[[state.MyState.onSms_1.text]] contains the text of this SMS as soon as the state MyState has been triggered and an SMS has been received.
The VARIABLES menu in the sidebar shows you which of your actions in the course of the level can contain data and how to address them.
From there you can simply drag them into the action in which you want to use them as variables.
In Live mode you can view action data that has been stored by an action by clicking on the inbox icon.
Functions
It is also possible to use the range of functions, which can be easily expanded, to add text variably, to check conditions or to change items.
A function variable is replaced with the respective return value of the function when the corresponding action is executed.
It is [[functions.getTime()]] now results in It is 16:00 now.
You can find all available functions in the VARIABLES TOOLBAR under FUNCTIONS.
In the Javascript functions chapter you will learn how to use functions and how to create and add functions to your adaptor:ex game.
Missing and empty variables
If a variable does not result in a value or item, it is undefined. This can be the case because the referenced property or item does not (yet) exist, or because the variable contains a (typo) error.
In a text that contains an empty or missing variable, undefined is also added at this point. Like: Hello [[Player.name]]!, if no player exists or has Player no nameproperty, to Hello undefined!