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 when the action is executed.

Variables are identified in adaptor:ex by enclosing two square brackets. It then looks like this, for example:

[[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, it is [[Player.name]] replaced by the name of the player who is currently playing the level.

In this Twilio Send SMS action we use a variable to personalize the address:

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 the 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 may be added.

There are different places in adaptor:ex where variable data is stored and different ways of referencing that data, i.e. using variables to refer to that data. In the following, you will find out what data and forms of references there are.

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.

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

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.

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 they are addressed.

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!