Variables & Memory

Variable System Overview

All game variables in GB Studio are INT16 (signed 16-bit integers), with a range of -32768 to 32767. They are stored in the GBVM heap and referenced by index (0–767). Variables are the primary mechanism for tracking game state, scores, flags, positions, and any other mutable data.

• Type: INT16 (signed 16-bit)
• Range: -32768 to 32767
• Storage: GBVM heap memory
• Addressing: by index (0–767)
• Used for: game state, scores, flags, positions, counters

GBVM Memory Layout

The GBVM virtual machine manages three key memory regions: the shared heap, per-context stacks, and the instruction budget.

Heap Organization

The heap is a flat array of 768 INT16 slots. Global game variables occupy the lower indices; system and temporary storage use higher indices.

Index 0-N:       Global game variables (defined in project)
Index N+1...:    System variables, temporary storage
Total:           768 slots × 2 bytes = 1536 bytes

Stack Memory

Each of the 16 script contexts has its own 64-word stack, used for local variables, function arguments, and RPN calculations.

• Stack grows downward (negative offsets from stack pointer)
• Local variables are allocated via VM_PUSH_CONST or _declareLocal
• Must be cleaned up with VM_POP before script exit

Function Argument Offsets

Variable References

In Event Scripts (.gbsres JSON)

Variables are referenced by their ID (UUID or index) in event JSON files.

// Direct variable reference
{"type": "variable", "value": "12"}

// In expressions — $ID$ syntax references variable by index
{"type": "expression", "value": "$12$ + 1"}

// Multiple variables in one expression
{"type": "expression", "value": "$07$ >= 6"}

In GBVM Assembly

GBVM instructions use VAR_* defines to reference variables by name.

VM_SET_CONST  VAR_MY_VARIABLE, 42    ; Set variable to constant
VM_GET_INT8   VAR_RESULT, _my_c_var  ; Read C variable into GBVM variable
VM_SET_INT8   _my_c_var, VAR_SOURCE  ; Write GBVM variable to C variable

In Event Plugin JavaScript

Event plugins use the helpers API to work with variables.

// Reading a variable field from the event input
const varAlias = helpers.getVariableAlias(input.myVariable);

// Setting a variable from a script value
helpers.variableSetToScriptValue(varAlias, input.myValue);

// Using in RPN calculations
helpers._rpn()
  .ref(varAlias)        // Push variable value
  .int16(10)            // Push constant
  .operator(".ADD")     // Add top two values
  .refSet(varAlias)     // Pop and store result
  .stop();

GBVM Variable Commands

Core GBVM instructions for reading, writing, and manipulating variables.

Usage Examples

; Set a variable to 100
VM_SET_CONST    VAR_SCORE, 100

; Copy one variable to another
VM_SET          VAR_BACKUP, VAR_SCORE

; Read a C byte variable into GBVM
VM_GET_INT8     .LOCAL_RESULT, _game_over

; Write GBVM variable to C memory
VM_SET_INT8     _elevator_done, VAR_STATUS

; Stack operations for RPN
VM_PUSH_CONST   0           ; Push initial value
VM_PUSH_VALUE   VAR_SCORE   ; Push variable value
VM_POP          2           ; Clean up stack

Constants and Defines

Common GBVM Constants

Direction Constants

Actor State Constants

Math Utilities

Angle System (math.h)

GB Studio uses a 256-unit angle system where the full circle spans 0–255. Trigonometric functions are provided as BANKED lookup tables returning INT8 values.

• Full circle: 256 units (0–255)
• SIN(angle) / COS(angle) — BANKED functions
• Return type: INT8 (range -128 to 127)

Angle Constants

SIN/COS Reference Table

Fixed-Point Math

GB Studio uses fixed-point arithmetic to simulate fractional values on integer hardware. The primary format is 12.5 (12 integer bits, 5 fractional bits).

Some plugins use 8.8 fixed-point (8 integer bits, 8 fractional bits) for smoother interpolation, particularly in camera shake and easing calculations.

Random Numbers

UINT8 r = rand();  // 0-255 pseudo-random

// For range [min, max]:
UINT8 val = min + (rand() % (max - min + 1));

Interrupt System

The Game Boy provides several hardware interrupts. GB Studio primarily uses VBlank and LCD (STAT) interrupts.

Available Interrupts

VBlank ISR

The VBlank interrupt fires once per frame during the vertical blanking period. This is the only safe time to write to VRAM, OAM, and palette registers.

void VBL_isr(void) NONBANKED {
    if ((WY_REG = win_pos_y) < MENU_CLOSED_Y)
        SHOW_WIN;
    else
        HIDE_WIN;

    if (hide_sprites) HIDE_SPRITES;
    else SHOW_SPRITES;

    scroll_shadow_update();
}

LCD ISR

LCD interrupts are triggered at configurable scanlines via the LYC (Line Y Compare) register. GB Studio provides three built-in LCD ISRs:

ISR Management

// Remove all standard LCD ISRs
remove_LCD_ISRs();

// Install a custom ISR
CRITICAL {
    add_LCD(my_custom_LCD_isr);
}

// Remove a specific ISR
remove_LCD(my_custom_LCD_isr);

The LYC sync value used by GB Studio is 150, which falls within the VBlank period and is safe for register changes.

Common Patterns

Using Variables as Flags

; Set a flag
VM_SET_CONST  VAR_MY_FLAG, 1

; Check flag (branch if not equal to 0)
VM_IF_CONST   .NE, VAR_MY_FLAG, 0, label_true, 0

Reading Engine Fields into Variables

Engine fields are global C variables exposed to the GBVM script system. They can be read into game variables or written from script values.

// From event JSON:
// EVENT_ENGINE_FIELD_STORE — reads a C variable into a game variable
// EVENT_ENGINE_FIELD_SET — writes a value to a C variable

Bridging C and GBVM Variables

// In C code: read a GBVM variable
INT16 val = *(script_memory + VAR_MY_VARIABLE);

// In GBVM: read a C variable
VM_GET_INT8   VAR_RESULT, _my_c_byte_var
VM_GET_INT16  VAR_RESULT, _my_c_word_var

// In GBVM: write to a C variable
VM_SET_INT8   _my_c_byte_var, VAR_SOURCE
VM_SET_INT16  _my_c_word_var, VAR_SOURCE

RPN Stack Calculations

; Calculate: result = (score * 2) + bonus
VM_RPN
  .R_REF  VAR_SCORE
  .R_INT16 2
  .R_OPERATOR .MUL
  .R_REF  VAR_BONUS
  .R_OPERATOR .ADD
  .R_REF_SET VAR_RESULT
  .R_STOP