In the “Basics” series, we’ll be going over all the technical foundations needed to start building a GB Studio game. If you’re a GB Studio Beginner, then these articles are for you. Seasoned GB Studio devs may still find different ways to tackle challenges with these articles, so it should be worth the read.

---

Variables are one of the core components of building a game. Variables are used to store information, and you can use that information to control your game behind the scenes. If you’re working on a project in GB Studio, you’ll eventually need to work with variables, and this article will introduce you to the types of variables and how you can use them.

What is a Variable?

You have probably heard the term “variable” in math class. If you have asked for help on how to do something in GB Studio, you’ve probably been told it can be done with variables. But what is a variable?

In a math problem, such as “x + 2 = 4”, x is a variable – a way to represent a value that can change. Just like in math, variables in game design are placeholders for information. They are empty containers that we can use to store a value, and later call on to change how our game works.

Types & Limits

To make the most of variables in your game, it’s important to familiarize yourself with the types of variables and their limitations in GB Studio. There are 3 types of variables in GB Studio: Global, Local, and Temp* variables, each type has its own uses. (*Temp variables are only available in the 2.0 Beta)

Global variables can be tracked across scenes, actors, and triggers. Your game can have 512 global variables. Global variables are very useful for keeping track of information through your entire game, such as how much money the player has or whether or not they’ve completed a quest. If multiple actors, triggers, or scenes will need to know the information in the variable, you’ll want it to be global.

Local variables are only stored within the Actor, Trigger, or Scene that owns them. Every Actor, Trigger, and Scene in your game has 6 local variables to work with. Since Local Variables cannot be affected by other actors, triggers, or scenes, they have more limited uses than Global Variables, but are still quite useful!

Some examples of local variables are:

Actor Local Variable: checking if you’ve opened a treasure chest already
Trigger Local Variable: checking if you’ve stepped on a trap tile already
Scene Local Variable: checking if a script (like a cutscene) has already been played

Temp Variables are new to the 2.0 Beta. You have 2 temp variables to use in your scripts, and like Global Variables, the 2 temp variables are used across all Actors, Triggers, and Scenes. However, Temp variables are not tracked like global variables: they are temporary. In most cases, after a Temp variable is used, it is cleared from memory.

This may sound contradictory – if the point of a variable is to store information, why would we want it to be cleared? Temp variables are useful for manipulating other variables or creating menus – instead of using a Local or Global variable to track a menu selection for instance, or if a dialogue choice does not need to be remembered, you can use a temp variable in its place to free one of the Local or Global variables.

What’s Stored in a Variable?

All variables, regardless of type, can store a number between 0 and 255.

All variables start at 0, or false, by default. If a variable is assigned a number above 0, it becomes true. Checking if a variable is True or False is the simplest way to use a variable. As you advance, you can start checking variables for specific numbers, and use those numbers or ranges to control things in your game.

You can use different events in GB Studio to change variable values. If an event or math increases a variable above 255, or decreases it below 0, the variable will loop and continue counting! It’s important to keep this in mind – if you add or subtract too much, your scripts or game may not work because the values are not what you expect!

To avoid this, if you are using the 2.0 Beta, you can clamp a variable: this will limit the variable to never going higher than 255, and never going lower than 0.

Don’t worry – if you are not using the 2.0 Beta, you can still limit your variables, but you will need to manually script in limits.

Variables can also have up to 8 Flags. Each flag is tied to a specific number, and adding or removing flags changes a variable’s value, ranging from 0 – 255 depending on which flags a variable has set.

Using Variables

Earlier, we listed a few ways you can use variables, like keeping track of a treasure chest. Let’s take a look at how we’d actually script that in GB Studio.

In our scene, we have a “Treasure Chest” actor. Whenever the player interacts with the chest, we’ll display some dialogue. But if the player leaves the room and comes back, the chest doesn’t remember that it’s been opened already.

To track if we’ve already used the chest, let’s use a Local Variable – we’ll rename $L0$ to “Chest Opened“. Using an [If Variable False] event, we can check if the chest has been used already, and avoid player’s getting too much treasure!

Now those greedy players can’t exploit our treasure chests, but let’s show them that the chest has already been used even before they interact with it. Since we are already setting “Chest Opened” to true or false, we can use that variable to change the Treasure Chest’s animation frame.

In our Interact Tab, let’s change the animation frame when the player opens the chest. Then, on the “Init” tab, we’ll check if the chest has been opened. If “Chest Opened” is true, we’ll show the open chest frame, but if the variable is false, it will stay closed.

Looks great! We’re using the same variable to control two different behaviors. Now, let’s actually give the players an item when they open the chest. That dog in the scene looks like it could use a bone – let’s give it one!

In this case, we want the Treasure Chest (Actor 1) to give the bone to the player, and the Dog (Actor 2), to check that variable. Since the Dog is another actor, we’ll need to use a Global Variable.

In our Treasure Chest, let’s add an event: [Variable: Increment by 1], and select Global Variable 00 (which we’ll rename to Dog Bone). This will increase our current count of Dog Bones by 1, and since we haven’t used that variable yet, it starts at 0.

Now, when the player uses the chest, they gain a Dog Bone. But how does the dog know we have a bone?

In our Dog actor, let’s add a [Compare Variable with Value] event. This event lets us pick a variable, and then compare it to a number. Since we want to check if we have a Dog Bone to give, select our Global Variable 00 (Dog Bone), and check if it’s greater than 0.

If we have a bone, we can give it to the dog, and the first script runs. But if we don’t have a bone, the “else” will run. Let’s see how that works in action:

Great! We’ve now learned how Local and Global Variables interact, and how to check them to control different scripts. There are many other ways we can manipulate or check variables, but understanding the basics of True / False and comparing Values are the core mechanics. In later articles, we’ll cover the more advanced events and math using variables.

Tips and Tricks

Keep it simple – variables, and their related events, are very powerful, and you can do a lot with variables. As you get familiar with variables, try to work with simple math and checks to practice.

Rename your variables! Giving your variables clear names can help you search for them faster and recognize what is being used when you go back to look at older scripts.

Keep track of your variables. Later versions of GB Studio show lists of Global Variables in the UI, but keeping a spreadsheet of what your global variables are and what they do at certain values can help you reference them later.

Don’t forget to clamp your variables – if you don’t want a variable to loop, you’ll want to clamp (or use events to reset values); having a variable at the wrong value can break your game!

Check your work! If you want to see how a variable is working or being tracked, you can display a variable in text using $<variable number>$; inserting dialogue events between math or checkpoints can show what a variable is storing, helping you pinpoint where a value may have been changed incorrectly.