Variables allow you to store data in the computer memory like numbers and text (string). You can imagine variables as boxes where you store notes that you want to remember later. Using variables we can store any type of data like player health, ammo, name, items count, high score, everything that you want to remember later in the game.

Variable and Data Types

Different types of value need to be stored in different types of variables. In computer science, there are many different types of data but GDevelop simplifies it only for two types. Text and Number. When you store a value, you need to consider how you going to use this value later. If you would like to do mathematical operations with the value like reducing the player health or increase the score for example, then you must store the player health and score as a number inside a number variable. Likewise, if you would like to store the name of the player, it must be stored as text inside a text variable. Number and text values cannot be mixed without converting the value first so you need to make sure you assign number values to number variables and text values to text variables.

We can convert between number and text using expressions if necessary. To learn more about expressions, visit this page about expressions.

Scope of variables

The scope of a variable determines where a variable can be accessed and how long it stored in memory. In GDevelop, three variable scopes are available:

  • Global variables are stored in memory as long the game is running and can be used to store data that we want to share between all scenes in the entire game. For instance, it can be used to store the player's overall score for the game that we can access from every scene. A global variable is deleted from memory only when we quit the game.
  • Scene variables are stored in memory as long the scene is active and can be used to store data that we don't want to share between different scenes. For instance, it can be used to store the number of enemies in the scene. A scene variable is deleted from memory when we change to a different scene in the game.
  • Object variables are defined for each individual instances of an object and stored in memory for each instance as long the instance is present in the scene. We can use object variables to store data that we don't want to share between instances of an object but we want to store the data for each instance individually. For example, we can use object variable to store the health for each instance of an enemy object so we can reduce the health of each enemy instance independently from each other. An object variable is deleted from memory when we delete the instance of the object from the scene.

Defining variables

Using the editor:

Global, scene and object variables can be defined using the variable editors. For global variables, the Project Manager has a link to global variables. For scene variables, right click on a scene. Then, click on “properties”. For object variables, right click on an object in the list and choose “edit object variables”. Variable editors declare variables along with their initial values.

Using events:

Variables can also be defined by directly start referencing them in actions and conditions. If a variable doesn't exist it will be created automatically in memory during the execution of the event to avoid any crashes and errors and will be initialized with the value 0 or an empty text “”. In case it is an assignment operation, the value will be assigned to the variable afterward.

It works in most cases and makes the use of the editors optional. However, in some rare cases, it is necessary to have the variables defined before we execute certain events. For example in the case we read a value from storage into a scene variable we need to make sure we have the scene variable defined before we execute the action. Otherwise, we find the action doesn't work because by the time GDevelop defines the variable, the action to read a value from storage into the variable been already executed and failed because the variable was undefined at the time. GDevelop defines the variable too late in this case.

So even though GDevelop makes this very convenient for us and using the editors is optional, it is recommended to use the editors to make sure we have all the variables defined and initialized before executing any events to avoid errors in certain cases and to also keep our variables organized.

Naming the variables

When naming our variables, there are a few rules we need to follow. Variable names can not begin with a dot (.) or comma (,) but other than that, we can use any characters in our variable names.

Use variables in expressions

Variables can be accessed from conditions, modified from actions and can also be read in expressions.

In an expression computing a number, use:

  • GlobalVariable(name) to read the value of a global variable
  • Variable(name) to read the value of a scene variable
  • ObjectName.Variable(name) to read the variable of the object called “ObjectName”.

In an expression returning a text, use instead:

  • GlobalVariableString(name) to read the text of a global variable
  • VariableString(name) to read the text of a scene variable
  • ObjectName.VariableString(name) to read the variable of the object called “ObjectName”.

See variables in the debugger

FIXME This section is in construction. You can write it yourself by creating an account on the wiki!

Structure variables

GDevelop supports an advanced feature for variables called Structures. Variables in GDevelop can be a number, text or a structure. In this case, it has no value, but it contains instead other variables, called child variables. Of course, these child variables can be numbers, text or also structure variables themselves.

If you want to use a variable as a structure, you just have to avoid changing its value or text (structure variables do not have any value). Then, to modify the value of a child variable, just enter as variable name: the name of the variable followed by a period and finally the name of the child variable. For example: PlayersStats.NumberOfDeaths.

As normal variables, if the child does not exists, it will be created. There is also a condition testing for the existence of a child, and even an action to remove a child from a structure variable.

Dynamic access to the children

Children of a structure can also be accessed using a text expression, using this syntax: Variable[expression]. For example, we can imagine that you're storing the stats of the player for each level, called Level1, Level2, Level3… If you want to show to the player the stats for a specific level, you may store the number of the level in a variable called CurrentLevel. Then, you can access to the stats using this syntax: PlayersStats[“Level”+ToString(Variable(CurrentLevel))].

Other advanced uses

Structures are useful to store structured data. You can also uses them when you need array: Just name the children 0, 1, 2… Actions and expressions are also available to convert a structure from/to a JSON string, a notation currently used on the web to exchange data.