In GDevelop, you can use variables to store temporary data, such as numbers and text. For example, you might use variables to store the player's name, current health, and score.
To learn how to store data that isn't temporary, such as a player's saved progress, refer to storage.
All variables have a data type. The data type of a variable determines what type of data the variable can contain.
In GDevelop, variables can contain the following types of data:
Number, Text and Boolean are primitive types: they store a value. Structure and Array are collection types: they store multiple variables.
A variable with the Number data type can contain numeric values, such as
-10. You can perform mathematical calculations on variables that have this data type, such as multiplication or division.
A variable with the Text data type can contain text, such as the words
Hello world. In programming languages, this data type is often referred to as a string. In this documentation,
the terms text and string are used interchangeably.
A variable with the Boolean data type contains the simplest form of information: either yes or no, 1 or 0, true or false. They are useful as they can be easily toggled.
A Structure variable maps names to other variables (called "child variables").
For example, a simple structure can map the name "Hello" to one sub-variable and the name "World" to another sub-variable. You can use this data type to organize related variables within a single variable.
In programming languages, this data type is often referred to as an object, map, hash, or dictionary.
Structures can be created in the Variables Editor, using events or by using an extension like JSON resource loader.
An Array variable, also sometimes called list in programming languages, is like a list of variables.
Each variable in an Array has an index, which defines their position in the array. The indices begin at 0 and go up to however long the array is.
Arrays can be created in the Variables Editor, using events or by using an extension like JSON resource loader.
Using a variable in expressions
Once a variable is added in the variables editor of a project or a scene, you can simply write its name in an expression to use it. For example, if you have a variable named "Score":
"Your total points are:" + Score
For a variable of an object, you write the object name first followed by a dot and the variable name. For example:
"The player points are" + Player.Points
If multiple variables or objects have the same name, or if they are conflicting with a parameter (in a function) or a property (in a custom behavior or custom object) the order is as follows:
- In a scene: Object > Scene Variable > Global Variable,
- In an extension: Object > Parameter > Property > Shared Property.
This means if there are conflicting names, the object will always be used in priority. Otherwise, in the events of a scene, it will be a scene variable if it exists, otherwise a global variable if it exists. In an extension, the parameter with the given name will be used first, other a property if it exists.
Accessing child variables in structures or arrays
Variables that exist within a collection variable (i.e: an array or a structure) are known as child variables. To access the value of a child variable, use the following syntax in an expressions, replacing the values in angled brackets with variable names:
To get the value
123 we can write the following expression
Or, using brackets:
<child_variable> is the name of the child variable. On arrays it is the index of the child variable. Only numbers work as indices for arrays.
If a child variable doesn't exist, GDevelop creates it automatically.
Collection variables (structures and arrays) can contain other collection variables. This makes it possible to store complex data in a single variable. This is helpful when dealing with structured data coming from various sources, including data served from web services or third parties.
Just be careful the data doesn't become too difficult to manage if you create structures with a lot of variables.
Accessing child variables dynamically
You can use expressions to dynamically access child variables.
For example, imagine storing the player's score for each level, called
Level3. If you want to show the player's score for a specific level, you may store the current level number in a variable called
CurrentLevel. You could then use the following syntax to access the score:
PlayerScore["Level" + CurrentLevel]
Whatever is inside the square brackets will be interpreted as the name of the child.
If you need to use a variable to define part of the child path, all the subsequent children in the path will need to be in square brackets as well. In the above example if you wanted to address a child called
PlayerScore.Level1.enemies.killbonus but still define the level dynamically, it would look like this:
PlayerScore["Level" + CurrentLevel].enemies.killbonus
Note that this is equivalent to writing:
PlayerScore["Level" + CurrentLevel]["enemies"]["killbonus"]
The scope of a variable determines:
- where the variable can be accessed from,
- how long the variable is stored in memory,
- the steps required to create the variable.
In GDevelop, there are three variable scopes:
Refer to the linked pages for more information about each variable scope.
Sometimes, in particular in extensions, variables are not recommended because there are better alternatives. For example, in a custom behavior, you can use the properties of the behavior to store data inside the behavior.
Variable names should not contain dots (periods), commas or spaces. Other characters are also reserved by GDevelop. If you use something forbidden, GDevelop will automatically correct the name you've entered.
Using variables without declaring them
It's highly recommended that any variable that you use is declared. This means that it was added in the variables editor (either in the global variables of the project, or in the variables of the scene, or in the variables of an object).
GDevelop still support using variables not "declared" in an editor.
For example, if you reference a variable that doesn't exist in an action or condition, GDevelop automatically initializes the variable with a default value. The default value is determined by the data type of the variable:
- Numeric variables are initialized with a value of
- Text variables are initialized with a value of
""(an empty string).
This approach is less efficient, as GDevelop has to initialize the variable during the game and can't optimize their usage. A variable that is not "declared" is also not usable in expressions.
When developing a game, bugs can occur because the value of a variable isn't what you expect it to be. If something in your game isn't working and you think the problem might relate to a variable, use GDevelop's debugger to figure out what's wrong.
For more information, refer to debugger.
All actions, conditions and expressions are listed in the variables reference page.