Basics: Math Functions

As discussed earlier in our Basics series, Variables are a core component of making a game in GB Studio. To use variables to their full potential, it’s important to know which events you can use to manipulate variables, and the limits to each event’s usage.

There are 15 events in GB Studio that directly deal with a variable’s values, not including more advanced events that store elements in variables. Four of these events are connected to the concept of Variable Flags, and will be covered in a future article. In this article, we will review the standard variable events, comparing variables, and the multiple features found in the Variable: Math Functions event.

Standard Variable Events

Variable: Increment by 1 / Variable: Decrement by 1

Incrementing a variable increases its value by 1 each time the event runs, to a maximum of 255. Decrementing a variable decreases its value by 1 each time the event runs, to a minimum of 0.

Incrementing and Decrementing variables can be a quick way to manage variables that track items or simple counters, and the built in clamp can be quite convenient. However, Incrementing and Decrementing are limited by only being able to adjust a variable’s values by 1 at a time.

Variable: Set to True / Variable: Set to False / Variable: Set to Value

Variable values can also be set directly. An important consideration for working with values is that True and False are not special settings for a Variable, they are simply binary values. When a variable is 0, it is false. When a Variable has a non-zero value, it is true.

Setting a Variable to True changes its value to 1, while setting it to False changes its value to 0.

Setting a Variable to a Value changes a variable from its current value to the new specific value.

Setting variables to true and false are useful for tracking simple states (whether something has been interacted with, if an objective is complete, etc). Setting variable values directly is useful for managing variable states at the beginning of a game or scene, such as setting an HP value.

Math Functions for Variables

All of the standard variable events can be replicated in a single event: [Variable: Math Functions]. This event requires more input to work, but also introduces more options to all the events listed previously.

Using the first drop down field on the left lets you choose the function for the event. The second drop down on the right provides the options for this function (more on these options below).

The 6 functions for a Math event are:

  • Set To: Sets or defines your variable
  • Add: Adds to the variable
  • Subtract: Subtracts from the variable
  • Multiply: Multiplies the variable
  • Divide: Divides the variable
  • Modulus: Runs a Modulus function on the variable (more on this below!)

With Variable Math, you can Add, Subtract, Multiply, and Divide the values of a Variable. These functions operate exactly as they do in normal mathematics, but there are a few GB Studio concepts to take note of when using them:

  • Unlike with Incrementing and Decrementing variables, when using Variable Math, a Variable’s values will wrap if they exceed 255 or go below 0. If you want to limit your variable’s values to the minimums and maximum values (0 and 255), you’ll want to check the “Clamp Value between 0 and 255” check box in the event.
  • Division in GB Studio will always round down.

One of the benefits of using math functions over standard variable events, is that you can specify the values you’d like to add/subtract/etc. This gives you more options than incrementing or decrementing by 1, but you are not just limited to working with Values.

Using the second drop down box on the right, you can choose from 5 options when using a math function.

  • True: This option is the same as a value of 1.
  • False: This option is the same as a value of 0.
  • Variable: This allows you to select another variable for the math operation to be performed with.
  • Value: Allows you to enter a specific value to use.
  • Random: Allows you to enter a range of values, and GB Studio will use a random value from within that range. Note: The ranges are Inclusive.

For example, using a Math Function event like the one below is the same as using an “Increment Variable by 1” event, because we’re only adding 1 to the variable and we’re clamping the result at 255.

The value can be set to any number however, allowing for far more flexibility. You could instead use the “Random” option to add a random number:

Note: When using the random options, be sure to review our article on how GB Studio handles randomness, as the behavior may appear different than what you expect.

And when you start using multiple variables, you can combine your variables to do new things.

Let’s say you have a battle system and you want to increase your player’s damage based on their strength stat. If you’re tracking the player’s stats separately, you can modify the damage in your battle system using math events:

While the “Set To” option changes a variable’s values directly just like the “Set Variable to Value” event, using it in a math function gives you more control over what you set a variable to. Just like with addition/subtraction, etc, you can set a variable to True/False, a set Value, a random number, or even another variable’s value!

The final option you have for Variable Math is the Modulus function.

A modulo operation divides one number by another, but it returns the remainder of the division. For example, performing a normal division operation of 95 by 10, the result is 9.5 (in GB Studio, this would display as 9 since the engine always rounds down). If you were to use a Modulus operation: 95 mod 10, it would display a result of 5 since there is a remainder of 5 left over from the division. For another example, 12 mod 10 would result in 2, and so would 12 mod 5.

This may sound complicated at first, but it is a very useful function when using variables to store information. For example, how many coins a player has: 99 coins can be thought of as 9 tens and 9 ones, and a modulus function can check the ones value. Don’t worry if you don’t see an immediate application for Modulus in your game just yet, more advanced tutorials will make use of this function.

Variable Checks

Once you’ve started working with and manipulating variables, you’ll likely want to use them to check if certain conditions have been met. By using the events to check your variables, you can control which scripts run in your actors, triggers, etc.

The most straightforward ways to check variables are to see if they are True or False. This is done using the [If Variable is True] or [If Variable is False] event. Remember, all variables are false if their value is 0 (and all variables start at 0), and a variable is true as long as its value is a non-zero number.

The second way to check your variables is to compare them. There are two compare events: Variable Compare to Value, and Variable Compare to Variable. Both events have a similar setup, the event compares the current value of the selected variable, and checks if it is:

  • Equal to a Value/Variable
  • Less than a Value/Variable
  • Less than or Equal to a Value/Variable
  • Greater than a Value/Variable
  • Greater than or Equal to a Value/Variable

Comparing variables has many uses! You can check if a player has found a certain number of items, if an NPC has been talked to a certain number of times, if a player can afford to purchase an item from a shop, etc. Comparison events are the backbone of many RPG battle systems, too.

If you find yourself checking the same variable with multiple comparison events, you may want to use a switch in its place. You can learn more about switches in this article.

If you want to download the ROM and GB Studio Project file we created for the demonstration in this article, check out our Itch Page.