Bit Switches

This script introduces a new type of switch called a “bit switch”. These switches operate on numbers stored in game variables. The purpose is to allow you to group a collection of related switches into a single variable rather than reserving multiple game switches, allowing you to manage larger projects more easily.

A bit switch is a single digit in the binary representation of a number stored in the variable. So for example, the number 6 in binary is written as 110. If we treat each digit as a switch, then we have three bit switches in the number 6. This doesn’t seem like much, but what if we consider a number like 13456730, which in binary is

110011010101010101011010

Suddenly, a single variable can represent 24 switches independently. You could have variables representing 50 or 100 or even 500 switches if necessary. How’s that for saving on switches?

Of course, this script allows you to avoid all of the math and technical details involved (such as the description above), using a simple set of script calls to set switches and check them.

Download

Script: download here

This tutorial may be useful to understand how to use this script

Installation

Place this script below Materials and above Main

Understanding Bit Switches

Bit switches have the property that a value of 1 is ON and a value of 0 is OFF. Bit switches are read from right to left, so the first bit switch is the digit on the very right, and the second bit switch is the digit next to it. The number 6 (if you recall, is represented as 110 in binary) means

bitswitch 1 is OFF
bitswitch 2 is ON
bitswitch 3 is ON

We can perform batch switch processing using “bit masks”. A “bit mask” is a collection of bit switches. Rather than checking multiple bit switches separately, we can check them all at the same time. Similarly, we can also set multiple bit switches using a bit mask.

Example

Suppose our variable holds the number 102. In binary, this is 1100110.
If we wanted to know whether bit switch 2 and bit switch 7 are ON, we use the
following bit mask: 1000010. Observe that digits 2 and 7 are ON (why?)

The mask is applied to the variable using a bitwise AND operation as follows

  1100110 : value
& 1000010 : mask
= 1000010 : result, equal to mask

If the result is equal to our mask switch, then it will return true.
Otherwise, if even one bit switch is different, then our result is false.

If our variable had a value of 101, or in binary 1100101, our mask would have
failed as follows:

  1100101 : value
& 1000010 : mask
= 1000000 : result, not equal to mask

Usage

Summary

These are all the methods that you will need

set_bit_switch(var_id, bit, value)   - set a bit-switch to true/false
set_mask_switch(var_id, mask, value) - set multiple bit switches to true/false
set_mask_match(var_id, mask1, mask2) - set variable to the mask
bit_switch?(var_id, bit)             - check if the bit switch is ON
mask_switch?(var_id, mask)           - check if the bit switches are ON
mask_match?(var_id, mask1, mask2)    - check if variable matches the mask exactly

Setting Bit Switches

You can set a variable directly using the control variables event command,
using the script call box to enter binary or hex values if is easier.

To set a specific bit switch, you can use the script call

set_bit_switch(var_id, bit, value)
---------------------------------------------------------------
set_bit_switch(2, 9, true) # Turn ON bit switch 9 in variable 2

Where
var_id is the ID of the variable you want to set
bit is the digit that you want to set
value is either true or false

Remember that the first digit is the one on the very right.

To perform batch bit switch setting, use the script call

set_mask_switch(var_id, mask, value)
---------------------------------------------------------------
set_mask_switch(3, 0b0101, true)

Where the mask is the bit mask you want to use. Note that in this case, a 1 in the mask means that the corresponding bit will have its value changed, so if your mask is 0b0101 with a value of false, then bit switches 1 and 3 will be set to false, while 2 and 4 will remain the same.

To set bits ON and OFF at the same time, use the script call

set_mask_match(var_id, mask1, mask2)
---------------------------------------------------------------
set_mask_match(3, 0b1100, 0b0010)

In this case, the first mask specifies which bits will be set to ON, while
the second mask specifies which bits will be set to OFF. The 1’s indicate
which bits will be checked, so in the example, bits 3 and 4 are ON, bit 2 is
OFF, and bit 1 is ignored.

Checking Bit Switches

To check whether a bit switch is ON, use the script call

bit_switch?(var_id, bit)
---------------------------------------------------------------
bit_switch?(3, 8) # check if bit switch 8 in variable 3 is ON

This will return true if the specified bit is ON, and false otherwise.

To perform batch checking using a bit mask, use the script call

mask_switch?(var_id, mask, value)
---------------------------------------------------------------
mask_switch?(2, 0b1100, true)  # check if bit switches 3, and 4 are ON
mask_switch?(2, 0b0011, false) # check if bit switches 1 and 2 are OFF

It will return true if the specified bit switches match the  mask for the given value. The 1 means we will check the corresponding bit, and a 0 means we will ignore the corresponding bit.

You can also check ON bits and OFF bits at the same time using

mask_match?(var_id, mask1, mask2)
---------------------------------------------------------------
mask_match?(4, 0b1100, 0b0010) # check if bits 3 and 4 are ON, and bit 2 is OFF

The first mask checks for ON bits, and the second mask checks for OFF bits.
The 1’s indicate which bits will be checked by that mask.

Named Bitmasks

This script allows you to assign bitmasks to constants stored in a look up table. You can then reference these constants throughout your events so that if you ever change the bitmasks, you don’t have to go through all your events to make sure that the specific bitmask has been updated correctly.

The bitmask look table is located in the script configuration. The keys are symbols, which represent the name of your bitmask, and the value associated with it is the bitmask itself.

In your events, instead of passing in a bitmask, you can instead pass in the name of your bitmask