GB Studio

https://www.gbstudio.dev/docs/
Admin
GB Studio is a drag and drop game creator for making Game Boy games with visual scripting,...
Tokens:50,775
Snippets:908
Trust Score:9.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install GB Studio on Fedora/RPM

Source: https://www.gbstudio.dev/docs/installation

Commands to install necessary packages, install the GB Studio .rpm package, and launch the application on RPM-based Linux distributions.

```bash
sudo yum install libXScrnSaver make lsb
sudo rpm --ignoreos -i gb-studio-1.0.0.x86_64.rpm
gb-studio
```

--------------------------------

### Install GB Studio on Ubuntu/Debian

Source: https://www.gbstudio.dev/docs/installation

Commands to update package lists, install build essentials, install the GB Studio .deb package, and launch the application on Debian-based Linux distributions.

```bash
sudo apt-get update
sudo apt-get install build-essential
sudo dpkg -i gb-studio_1.0.0_amd64.deb
gb-studio
```

--------------------------------

### Install macOS Command Line Tools

Source: https://www.gbstudio.dev/docs/build

On macOS, if you encounter issues building or running your game, you may need to install Apple's Command Line Tools. Open Terminal and run this command.

```bash
xcode-select --install
```

--------------------------------

### GBVM Script Example

Source: https://www.gbstudio.dev/docs/scripting/gbvm

This script demonstrates loading a tileset and setting a map using GBVM commands. It pushes constants for coordinates and tile data, then loads the tileset and configures the map.

```gbvm
VM_PUSH_CONST 0 ; Y coord
VM_PUSH_CONST 0 ; X coord
VM_PUSH_CONST 128
VM_LOAD_TILESET .ARG0, ___bank_bg_cave, _bg_cave
VM_OVERLAY_SET_MAP .ARG0, .ARG1, .ARG2, ___bank_bg_cave, _bg_cave
VM_POP 3
```

--------------------------------

### VM_DISPLAY_TEXT_EX

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Renders text in the defined layer (overlay by default) with specified options and starting tile.

```APIDOC
## VM_DISPLAY_TEXT_EX

### Description
Renders text in the defined layer (overlay by default).

### Method
VM_DISPLAY_TEXT_EX

### Parameters
- **OPTIONS** (enum) - Text rendering options: `.DISPLAY_DEFAULT`, `.DISPLAY_PRESERVE_POS`.
- **START_TILE** (number) - Tile number within the text rendering area to be rendered from; use `.TEXT_TILE_CONTINUE` to proceed from the current position.
```

--------------------------------

### VM_MUSIC_PLAY

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Starts playing a music track. Parameters include the track bank, track address, and a loop flag (which is obsolete).

```APIDOC
## VM_MUSIC_PLAY

### Description
Starts playing of music track.

### Parameters
* **TRACK_BANK** (integer) - Bank number of the track.
* **TRACK** (integer) - Address of the track.
* **LOOP** (boolean) - Obsolete, has no effect.
```

--------------------------------

### GBDK Compile Error Example

Source: https://www.gbstudio.dev/docs/extending-gbstudio/engine-eject

This example shows a typical GBDK compile error message indicating an undefined identifier and array/pointer issues on a specific line.

```text
Compiling: src/core/actor.c
src/core/actor.c:77: error 20: Undefined identifier 'emote_offsets'
src/core/actor.c:77: error 22: Array or pointer required for '[]' operation
src/core/actor.c:77: error 47: indirections to different types assignment
```

--------------------------------

### Display Text with Options

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Renders text using extended options, allowing control over display behavior and starting tile position. Use .TEXT_TILE_CONTINUE to resume from the current position.

```assembly
VM_DISPLAY_TEXT_EX OPTIONS, START_TILE  

```

--------------------------------

### VM_TIMER_SET

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Starts a timer that calls once every `INTERVAL` * 16 frames in the GBVM.

```APIDOC
## VM_TIMER_SET

### Description
Starts a timer calling once every `INTERVAL` * 16 frames.

### Parameters
#### Path Parameters
- **TIMER** (int) - Timer identifier.
- **INTERVAL** (int) - The interval in frames (multiplied by 16).
```

--------------------------------

### VM_RTC_START

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Starts or stops the Real-Time Clock (RTC) in the GBVM.

```APIDOC
## VM_RTC_START

### Description
Starts or stops RTC.

### Parameters
#### Path Parameters
- **START** (enum) - Start or stop flag:
  - `.RTC_STOP` - Stop RTC.
  - `.RTC_START` - Start RTC.
```

--------------------------------

### Play Music Track

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Starts playing a music track from a specified bank and address. The loop parameter is obsolete.

```gbvm
VM_MUSIC_PLAY TRACK_BANK, TRACK, LOOP
```

--------------------------------

### Set Timer Interval

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Starts a timer that will trigger a script execution at a specified interval.

```gbvm
VM_TIMER_SET TIMER, INTERVAL  

```

--------------------------------

### Print Overlay Window

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Prints a specified number of rows from the overlay window, with control over starting line and margin.

```gbvm
VM_PRINT_OVERLAY ERROR, START, HEIGHT, MARGIN
```

--------------------------------

### Thread Start

Source: https://www.gbstudio.dev/docs/scripting/script-glossary/miscellaneous

Runs a script in a separate thread.

```APIDOC
## Thread Start

### Description
Run a script in another thread.

### Parameters
- **Thread Handle** (Variable) - Required - The variable where the thread handle will be stored for later control.
```

--------------------------------

### Start Actor's "On Update" Script

Source: https://www.gbstudio.dev/docs/scripting/script-glossary/actor

Starts an actor's OnUpdate script if it is not currently running.

```APIDOC
## Start Actor's "On Update" Script

### Description
Start an actors OnUpdate script if it is not currently running. If the actor is currently offscreen its script may become deactivated causing the script to stop running again, to prevent this set the 'Keep Running While Offscreen' setting for the actor's OnUpdate script.

### Parameters
#### Path Parameters
- **Actor** (Actor) - Required - The actor you want to update.
```

--------------------------------

### Load Tileset

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads a new tileset into the background VRAM. Specify the starting tile ID (IDX), the bank number, and the background identifier (BKG).

```gbvm
VM_LOAD_TILESET IDX, BANK, BKG  

```

--------------------------------

### Example: Volume Persistence in ModPlug Tracker

Source: https://www.gbstudio.dev/docs/assets/music/music-gbt

Demonstrates how volume effects persist in ModPlug Tracker. The E-5 note is not heard because C00 persists, overriding the default full volume. To make the note audible, the volume must be reset with another Cxx effect.

```tracker
|C-502...C40|
|...........|
|...........|
|...........|
|........C00|
|...........|
|E-502......|
```

```tracker
|C-502...C40|
|...........|
|...........|
|...........|
|........C00|
|...........|
|E-502...C40|
```

--------------------------------

### Replace Background Tiles

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Replaces a sequence of background tiles with new tiles from a specified tileset. Parameters include the starting target tile ID, the bank of the new tiles, the tileset data, the starting index of the new tiles, and the number of tiles to replace.

```gbvm
VM_REPLACE_TILE TARGET_TILE_IDX, TILEDATA_BANK, TILEDATA, START_IDX, LEN  

```

--------------------------------

### VM_PRINT_OVERLAY

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Prints a specified number of rows from the overlay window. Parameters include an ERROR variable for the result, the starting line, the height of the area to print, and a margin for feeding lines after printing.

```APIDOC
## VM_PRINT_OVERLAY

### Description
Prints up to HEIGHT rows of the overlay window (must be multiple of 2).

### Parameters
* **ERROR** (variable) - Target variable that receives the result of printing.
* **START** (integer) - Start line of the overlay window.
* **HEIGHT** (integer) - Amount of lines to print.
* **MARGIN** (integer) - Lines to feed after the printing is finished.
```

--------------------------------

### VM_REPLACE_TILE_XY

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Replaces a single background tile at a specified X and Y position with a new tile from a tileset. Parameters include the tile's position, the bank and tileset containing the new tile, and the starting index of the new tile.

```APIDOC
## VM_REPLACE_TILE_XY

### Description
Replaces a single background tile at a position with a background tile from a tileset.

### Parameters
* **X** (integer) - X position of old background tile.
* **Y** (integer) - Y position of old background tile.
* **TILEDATA_BANK** (integer) - Bank number of tileset containing new tile.
* **TILEDATA** (integer) - Tileset containing new tile.
* **START_IDX** (integer) - Tile ID of new tile.
```

--------------------------------

### Set Overlay Map

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Copies a tilemap to the overlay layer at a specified position. Parameters include the starting tile ID (IDX), X and Y coordinates on the overlay, the tilemap's bank, and the tilemap data (BKG).

```gbvm
VM_OVERLAY_SET_MAP IDX, X_IDX, Y_IDX, BANK, BKG  

```

--------------------------------

### VM_TIMER_PREPARE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads a script into the timer context in the GBVM.

```APIDOC
## VM_TIMER_PREPARE

### Description
Loads script into timer context.

### Parameters
#### Path Parameters
- **TIMER** (int) - Timer identifier.
- **BANK** (int) - Bank number of the script.
- **ADDR** (int) - Address of the script.
```

--------------------------------

### VM_GET_FAR: Get Data by Far Pointer

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Retrieves a byte or word from memory using a far pointer into a variable. Supports getting bytes or words, specifying bank and address.

```gbvm
VM_GET_FAR IDX, SIZE, BANK, ADDR  

```

--------------------------------

### Load Text Ex (Stack Parameters)

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads text into memory using parameters from the VM stack. Expects the bank and address of the format string and arguments.

```assembly
VM_LOAD_TEXT_EX N  

```

--------------------------------

### Prepare Timer Script

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads a script into the context of a specified timer.

```gbvm
VM_TIMER_PREPARE TIMER, BANK, ADDR  

```

--------------------------------

### VM_CHOICE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Executes a menu and returns the selected item index.

```APIDOC
## VM_CHOICE

### Description
Executes a menu and stores the result in a variable.

### Parameters
* **IDX** (variable) - Variable that receives the result of the menu execution.
* **OPTIONS** (bitfield) - Set of possible menu options. Possible values: `.UI_MENU_STANDARD`, `.UI_MENU_LAST_0`, `.UI_MENU_CANCEL_B`, `.UI_MENU_SET_START`.
* **COUNT** (number) - The number of menu items.
```

--------------------------------

### Stop Timer

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Stops a previously started timer.

```gbvm
VM_TIMER_STOP TIMER  

```

--------------------------------

### Run GB Studio with GPU Sandbox Disabled

Source: https://www.gbstudio.dev/docs/installation

If you experience graphical glitches or startup failures on Linux, try running GB Studio with the GPU sandbox disabled.

```bash
gb-studio --disable-gpu-sandbox
```

--------------------------------

### VM_CONTEXT_PREPARE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Assigns a script to a specific slot, typically for use with VM_INPUT_ATTACH.

```APIDOC
## VM_CONTEXT_PREPARE

### Description
Assigns a script to a slot for VM_INPUT_ATTACH.

### Parameters
#### Path Parameters
- **SLOT** (slot) - Required - The slot to assign the script to.
- **BANK** (number) - Required - The bank number of the script.
- **ADDR** (address) - Required - The memory address of the script.
```

--------------------------------

### Get Actor Angle

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Retrieves the current angle of an actor and stores it in a destination variable.

```gbvm
VM_ACTOR_GET_ANGLE IDX, DEST  

```

--------------------------------

### Begin Actor Update Script

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Initiates the execution of an actor's update script.

```gbvm
VM_ACTOR_BEGIN_UPDATE ACTOR  

```

--------------------------------

### VM_LOAD_PALETTE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads a palette into the system.

```APIDOC
## VM_LOAD_PALETTE

### Description
Loads a palette into the system.

### Parameters
#### Path Parameters
- **MASK** (mask) - Required
- **OPTIONS** (options) - Required
```

--------------------------------

### Control RTC Start/Stop

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Starts or stops the Real-Time Clock (RTC) based on the provided flag.

```gbvm
VM_RTC_START START  

```

--------------------------------

### VM_ACTOR_MOVE_TO_INIT

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Initialises moving actor to a new position. Handles calculating relative offsets, snapping and tile collision checks.

```APIDOC
## VM_ACTOR_MOVE_TO_INIT

### Description
Initialises moving actor to a new position. Handles calculating relative offsets, snapping and tile collision checks.

### Parameters
#### Path Parameters
- **IDX** (structure) - Required - Points to the beginning of the pseudo-structure that contains these members:
  `ID` - Actor number.
  `X` - New X-coordinate of the actor.
  `Y` - New Y-coordinate of the actor.
- **ATTR** (bit flags) - Required - Bit flags:
  `.ACTOR_ATTR_H_FIRST` - Move horizontal first.
  `.ACTOR_ATTR_CHECK_COLL` - Respect collisions.
  `.ACTOR_ATTR_DIAGONAL` - Allow diagonal movement
```

--------------------------------

### Get Actor Direction

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Retrieves the current facing direction of an actor and stores it in a destination variable.

```gbvm
VM_ACTOR_GET_DIR IDX, DEST  

```

--------------------------------

### Implement Scene Initialization Function

Source: https://www.gbstudio.dev/docs/extending-gbstudio/plugins

Define the `_init` function for your custom scene type. This function is called once when the scene is loaded. Prefix global variables with your scene key to avoid naming collisions.

```c
void SCENEKEY_init(void) BANKED { }
```

--------------------------------

### Arpeggio Effect

Source: https://www.gbstudio.dev/docs/assets/music/music-gbt

Rapidly cycles between three notes. 'x' and 'y' define the number of semitones above the starting note.

```tracker
0xy
```

--------------------------------

### VM_BEGINTHREAD: Spawn Thread

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Spawns a new thread in a separate context. BANK is the thread function's bank, THREADPROC is its address, HTHREAD receives the handle, and NARGS is the number of stack values to copy.

```gbvm
VM_BEGINTHREAD BANK, THREADPROC, HTHREAD, NARGS  

```

--------------------------------

### VM_BEGINTHREAD

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Spawns a thread in a separate context.

```APIDOC
## VM_BEGINTHREAD BANK, THREADPROC, HTHREAD, NARGS

### Description
Spawns a thread in a separate context.

### Parameters
#### Path Parameters
- **BANK** (Bank Number) - Required - The bank number of the thread function.
- **THREADPROC** (Address) - Required - The address of the thread function.
- **HTHREAD** (Variable Index) - Required - The variable that receives the thread handle.
- **NARGS** (Number) - Required - The amount of values from the stack to be copied into the stack of the new context.

### Method
VM_BEGINTHREAD
```

--------------------------------

### Load and Display Text with Variables

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads text with variable placeholders and then displays it. Variables are defined using .dw before the .asciz call and referenced using format specifiers like %d.

```assembly
VM_LOAD_TEXT   3    
.dw VAR_0, VAR_1, VAR_1    
.asciz "Var 0 is %d, Var 1 is %d, Var 2 is %d"    

```

--------------------------------

### Link: Host

Source: https://www.gbstudio.dev/docs/scripting/script-glossary/miscellaneous

Creates a new link session as player 1, allowing another player to join.

```APIDOC
## Link: Host

### Description
Creates a new link session as player 1. This allows player 2 to use the `Link: Join` event to join the session.
```

--------------------------------

### Inline Native Code Execution

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Operations for executing inline native code within the VM. VM_ASM starts the execution, and VM_ENDASM terminates it.

```assembly
VM_ASM  

```

```assembly
VM_ENDASM  

```

--------------------------------

### VM_PUSH_REFERENCE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Translates IDX into absolute index and pushes result to VM stack.

```APIDOC
## VM_PUSH_REFERENCE

### Description
Translates IDX into absolute index and pushes result to VM stack.

### Parameters
#### Path Parameters
- **IDX** (variable) - Required - Index of the variable.
```

--------------------------------

### Get Actor Position

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Retrieves the current position of an actor. The IDX parameter points to a structure where the actor ID, X, and Y coordinates will be stored.

```gbvm
VM_ACTOR_GET_POS IDX  

```

--------------------------------

### VM_OVERLAY_SHOW

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Shows the overlay window at a specified position with given color and options.

```APIDOC
## VM_OVERLAY_SHOW

### Description
Shows the overlay window.

### Method
VM_OVERLAY_SHOW

### Parameters
- **X** (number) - X-coordinate of the new position.
- **Y** (number) - Y-coordinate of the new position.
- **COLOR** (enum) - Initial color of the overlay window: `.UI_COLOR_BLACK`, `.UI_COLOR_WHITE`.
- **OPTIONS** (bitfield) - Display options: `.UI_DRAW_FRAME`, `.UI_AUTO_SCROLL`.
```

--------------------------------

### Thread Local Variable Operations

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Operations for getting thread local variables. Specify the target variable and the thread local variable index.

```assembly
VM_GET_TLOCAL IDXA, IDXB  

```

--------------------------------

### Prepare VM Context

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Assigns a script to a specific slot, typically used in conjunction with VM_INPUT_ATTACH. Requires the target SLOT, script BANK, and script ADDR.

```gbvm
VM_CONTEXT_PREPARE SLOT, BANK, ADDR  

```

--------------------------------

### Clear VM Memory

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Clears a specified number of VM memory variables starting from a destination address. The VALUE parameter determines the fill value.

```gbvm
VM_MEMSET DEST, VALUE, COUNT  

```

--------------------------------

### VM_INPUT_GET

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Retrieves input state from a specified joypad.

```APIDOC
## VM_INPUT_GET

### Description
Gets input from joypad. Up to 4 joypads are supported when using SGB.

### Parameters
#### Path Parameters
- **IDX** (variable) - Required - Target variable that receives the input result.
- **JOYID** (enum) - Required - Joypad to get input from:
  - `.JOY0` - Joypad 0.
  - `.JOY1` - Joypad 1.
  - `.JOY2` - Joypad 2.
  - `.JOY3` - Joypad 3.
```

--------------------------------

### Get Background Tile at Position

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Retrieves the tile ID of a background tile at specific X and Y coordinates. The TILE_IDX variable will store the resulting tile ID.

```gbvm
VM_GET_TILE_XY TILE_IDX, X_IDX, Y_IDX  

```

--------------------------------

### Execute Menu Choice

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Executes a menu and stores the selected item index. Supports various options like cancel button and initial item selection.

```gbvm
VM_CHOICE IDX, OPTIONS, COUNT  
```

--------------------------------

### Get Actor Animation Frame

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Retrieves the current animation frame of a specified actor. The ACTOR parameter is a pseudo-struct that will be populated with the actor's ID and frame.

```gbvm
VM_ACTOR_GET_ANIM_FRAME ACTOR  

```

--------------------------------

### Show Overlay Window

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Shows the overlay window at a specified position (X, Y) with a given color and options. Options include drawing a frame or enabling auto-scrolling.

```assembly
VM_OVERLAY_SHOW X, Y, COLOR, OPTIONS  

```

--------------------------------

### Get Joypad Input

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Reads input from a specified joypad. Supports up to four joypads when using SGB. The IDX variable stores the result, and JOYID selects the joypad.

```gbvm
VM_INPUT_GET IDX, JOYID  

```

--------------------------------

### VM_ASM

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Executes inline native code.

```APIDOC
## VM_ASM

### Description
Executes the inline native code

### Method
VM_ASM
```

--------------------------------

### VM_LOAD_TILESET

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads a new tileset into the background VRAM.

```APIDOC
## VM_LOAD_TILESET

### Description
Loads a new tileset into the background VRAM tiles starting at a given tile id (`IDX`).

### Parameters
#### Path Parameters
- **IDX** (tile id) - Required - Tile ID where the tileset starts.
- **BANK** (number) - Required - Bank number of the tileset.
- **BKG** (tileset) - Required - The tileset data.
```

--------------------------------

### Replace Actor Tile

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Replaces a specific tile within an actor's spritesheet. Requires the actor number, target tile, tile data bank and address, and the start tile and length of data to replace.

```gbvm
VM_ACTOR_REPLACE_TILE ACTOR, TARGET_TILE, TILEDATA_BANK, TILEDATA, START, LEN  

```

--------------------------------

### VM_LOAD_TEXT_EX

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads text in memory using parameters from the VM stack.

```APIDOC
## VM_LOAD_TEXT_EX

### Description
Loads text in memory similar to VM_LOAD_TEXT but expects parameters on the VM stack, then pops N parameters.

### Method
VM_LOAD_TEXT_EX

### Parameters
- **N** (number) - Number of parameters to pop from the stack.
- **.ARG0** (number) - Bank of the format string and the arguments array.
- **.ARG1** (number) - Address of the format string.
Format string parameters start from .ARG2 (varargs).
```

--------------------------------

### Volume Envelope and Fade Effect

Source: https://www.gbstudio.dev/docs/assets/music/music-gbt

Sets the note's starting volume and applies a volume fade envelope. The fade direction and speed are controlled by 'e'. Use '9ve' after 'Cxx' to override the 'Cxx' volume while retaining the fade effect.

```tracker
9ve
```

--------------------------------

### VM_OVERLAY_MOVE_TO

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Triggers animated movement of the overlay window to a new position.

```APIDOC
## VM_OVERLAY_MOVE_TO

### Description
Triggers animated movement of the overlay window to a new position.

### Method
VM_OVERLAY_MOVE_TO

### Parameters
- **X** (number) - X-coordinate of the new position.
- **Y** (number) - Y-coordinate of the new position.
- **SPEED** (enum) - Speed of the movement: `.OVERLAY_IN_SPEED`, `.OVERLAY_OUT_SPEED`, `.OVERLAY_SPEED_INSTANT`.
```

--------------------------------

### Pop All Scenes

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Clears the entire scene stack and loads the very first scene pushed.

```gbvm
VM_SCENE_POP_ALL  

```

--------------------------------

### VM_MUSIC_ROUTINE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Attaches a script routine to a music event. Parameters include the routine ID, bank number, and address of the routine.

```APIDOC
## VM_MUSIC_ROUTINE

### Description
Attaches script to music event.

### Parameters
* **ROUTINE** (integer) - The routine ID. An integer between 0 and 3.
* **BANK** (integer) - Bank number of the routine.
* **ADDR** (integer) - Address of the routine.
```

--------------------------------

### VM_RAISE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Raises an exception with a specified code and parameter size.

```APIDOC
## VM_RAISE

### Description
Raises an exception.

### Method
VM_RAISE

### Parameters
#### Path Parameters
- **CODE** (code) - Required - Exception code: `EXCEPTION_RESET`, `EXCEPTION_CHANGE_SCENE`, `EXCEPTION_SAVE`, `EXCEPTION_LOAD`.
- **SIZE** (number) - Required - Length of the parameters to be passed into the exception handler.
```

--------------------------------

### Initialize Actor Movement

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Initializes an actor's movement to a new position, handling relative offsets, snapping, and tile collision checks. Use this for complex movement scenarios.

```gbvm
VM_ACTOR_MOVE_TO_INIT IDX, ATTR  

```

--------------------------------

### Load Palette

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads a palette into the system. Requires a MASK and OPTIONS parameter to specify which palette to load and how.

```gbvm
VM_LOAD_PALETTE MASK, OPTIONS  

```

--------------------------------

### VM_ACTOR_ACTIVATE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Activates actor.

```APIDOC
## VM_ACTOR_ACTIVATE

### Description
Activates actor.

### Parameters
#### Path Parameters
- **ACTOR** (variable) - Required - Variable that contains the actor number.
```

--------------------------------

### Speed Table: Fxx Values and BPM

Source: https://www.gbstudio.dev/docs/assets/music/music-gbt

Converts Fxx values from .mod trackers to BPM in both .mod trackers and in-game, assuming the -speed flag is not set.

```text
F01 1| 750 BPM| 900 BPM
```

```text
F02 1| 375 BPM| 450 BPM
```

```text
F03 1| 250 BPM| 300 BPM
```

```text
F04 1| 187.5 BPM| 225 BPM
```

```text
F05| 150 BPM| 150 BPM
```

```text
F06| 125 BPM| 128.57 BPM
```

```text
F07| 107.14 BPM| 112.50 BPM
```

```text
F08| 93.75 BPM| 100 BPM
```

```text
F09| 83.33 BPM| 90 BPM
```

```text
F0A| 75 BPM| 81.82 BPM
```

--------------------------------

### Link: Join

Source: https://www.gbstudio.dev/docs/scripting/script-glossary/miscellaneous

Joins an active link session as player 2.

```APIDOC
## Link: Join

### Description
Join an active link session as player 2. The session must first be created by another player using the `Link: Host` event. This event must be executed before any data transfer.
```

--------------------------------

### VM_PROJECTILE_LAUNCH

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Launches an instance of a projectile in the GBVM.

```APIDOC
## VM_PROJECTILE_LAUNCH

### Description
Launches an instance of a projectile loaded in a slot.

### Parameters
#### Path Parameters
- **TYPE** (int) - Slot number of projectile to launch.
- **IDX** (struct) - Points to the beginning of the pseudo-structure that contains these members:
  - `pos.x` (int) - X position to launch from.
  - `pos.y` (int) - Y position to launch from.
  - `angle` (int) - Projectile angle or direction.
```

--------------------------------

### VM_PUSH_CONST

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Pushes an immediate value onto the top of the VM stack.

```APIDOC
## VM_PUSH_CONST VAL

### Description
Pushes immediate value to the top of the VM stack.

### Parameters
#### Path Parameters
- **VAL** (Immediate value) - Required - The immediate value to be pushed onto the stack.

### Method
VM_PUSH_CONST
```

--------------------------------

### VM_JOIN

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Joins a thread, waiting for it to complete its execution.

```APIDOC
## VM_JOIN

### Description
Joins a thread.

### Method
VM_JOIN

### Parameters
#### Path Parameters
- **IDX** (handle) - Required - Thread handle for joining.
```

--------------------------------

### VM_PUSH_CONST: Push Immediate Value

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Pushes an immediate value onto the top of the VM stack. VAL is the value to be pushed.

```gbvm
VM_PUSH_CONST VAL  

```

--------------------------------

### VM_SWITCH

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Compares a variable against a set of values (defined with .CASE) and jumps to the matching label.

```APIDOC
## VM_SWITCH IDX, SIZE, N

### Description
Compares variable with a set of values, and if equal, jumps to the specified label. Values for testing may be defined with the .CASE macro.

### Parameters
#### Path Parameters
- **IDX** (Variable Index) - Required - The variable to compare.
- **SIZE** (Size) - Required - The amount of entries for the test.
- **N** (Number) - Required - The amount of values to be cleaned from the stack on exit.

### Method
VM_SWITCH
```

--------------------------------

### VM_INPUT_WAIT

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Waits for a specific input event or music routine event.

```APIDOC
## VM_INPUT_WAIT

### Description
Waits to receive an input.

### Parameters
#### Path Parameters
- **MASK** (mask) - Required - Input mask specifying which event(s) to wait for:
  - `.POLL_EVENT_INPUT` - Wait for input event.
  - `.POLL_EVENT_MUSIC` - Wait for music routine event.
```

--------------------------------

### VM_SHOW_SPRITES

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

A macro to show the sprite layer.

```APIDOC
## VM_SHOW_SPRITES

### Description
Macro for SET_SPRITES_VISIBLE .SPRITES_SHOW.

### Method
Macro
```

--------------------------------

### VM_SCENE_POP_ALL

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Removes all scenes from the scene stack and loads the first one in the GBVM.

```APIDOC
## VM_SCENE_POP_ALL

### Description
Removes all scenes from the scene stack and loads the first one.
```

--------------------------------

### Define Menu Item

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Defines a menu item with navigation parameters for cursor movement.

```gbvm
.MENUITEM X, Y, iL, iR, iU, iD  
```

--------------------------------

### VM_SET_PRINT_DIR

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Sets the direction for text rendering.

```APIDOC
## VM_SET_PRINT_DIR

### Description
Sets the direction for text rendering.

### Parameters
* **DIRECTION** (enum) - The direction of text rendering. Possible values: `.UI_PRINT_LEFTTORIGHT`, `.UI_PRINT_RIGHTTOLEFT`.
```

--------------------------------

### Push Current Scene

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Saves the current scene onto the scene stack, allowing for later return.

```gbvm
VM_SCENE_PUSH  

```

--------------------------------

### VM_OVERLAY_SET_SUBMAP_EX

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Copies a rectangular area of the background map onto the overlay window using a parameter structure.

```APIDOC
## VM_OVERLAY_SET_SUBMAP_EX

### Description
Copies a rectangular area of the background map onto the overlay window.

### Parameters
* **PARAMS_IDX** (index) - Points to the beginning of a pseudo-structure containing copy parameters:
  * `x` (number) - X-coordinate within the overlay window in tiles.
  * `y` (number) - Y-coordinate within the overlay window in tiles.
  * `w` (number) - Width of the copied area in tiles.
  * `h` (number) - Height of the copied area in tiles.
  * `scene_x` (number) - X-coordinate within the background map in tiles.
  * `scene_y` (number) - Y-coordinate within the background map in tiles.
```

--------------------------------

### VM_SCENE_PUSH

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Pushes the current scene onto the scene stack in the GBVM.

```APIDOC
## VM_SCENE_PUSH

### Description
Pushes the current scene to the scene stack.
```

--------------------------------

### VM_SWITCH: Conditional Jump with Cases

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Compares a variable against a set of values defined with .CASE and jumps to the corresponding label if a match is found. N specifies values to clean from the stack on exit.

```gbvm
VM_SWITCH IDX, SIZE, N  

```

--------------------------------

### VM_RET_FAR_N: Return from Far Call and Clear Args

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Returns from a far call and removes a specified number of arguments from the stack. N is the number of arguments to clear.

```gbvm
VM_RET_FAR_N N  

```

--------------------------------

### VM_FADE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Fades the screen in or out in the GBVM.

```APIDOC
## VM_FADE

### Description
Fades screen in or out.

### Parameters
#### Path Parameters
- **FLAGS** (enum) - Options for screen fade:
  - `.FADE_NONMODAL` - Nonmodal fade.
  - `.FADE_MODAL` - Modal fade.
  - `.FADE_OUT` - Fade out.
  - `.FADE_IN` - Fade in.
```

--------------------------------

### VM_SFX_PLAY

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Plays a sound effect asset. Parameters include the bank and address of the effect, a mute mask, and the priority of the sound effect.

```APIDOC
## VM_SFX_PLAY

### Description
Plays a sound effect asset.

### Parameters
* **BANK** (integer) - Bank number of the effect.
* **ADDR** (integer) - Address of the effect.
* **MASK** (integer) - Mute mask of the effect, same as in VM_MUSIC_MUTE.
* **PRIO** (integer) - Priority of the sound effect. Effects with higher priority will cancel the ones with less priority:
  * `.SFX_PRIORITY_MINIMAL` - Minmium priority for playback.
  * `.SFX_PRIORITY_NORMAL` - Normal priority for playback.
  * `.SFX_PRIORITY_HIGH` - High priority for playback.
```

--------------------------------

### VM_RANDOMIZE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Initializes the Random Number Generator (RNG) seed.

```APIDOC
## VM_RANDOMIZE

### Description
Initializes RNG seed.

### Method
VM_RANDOMIZE
```

--------------------------------

### VM_RET

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Returns from the current near call.

```APIDOC
## VM_RET

### Description
Returns from the near call.

### Method
VM_RET
```

--------------------------------

### VM_SET_CONST: Assign Immediate Value

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Assigns an immediate value to a target variable. IDX is the target variable and VAL is the source immediate value.

```gbvm
VM_SET_CONST IDX, VAL  

```

--------------------------------

### VM_RPN: Reverse Polish Notation Calculator

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Initiates a Reverse Polish Notation (RPN) calculation, returning the result(s) on the VM stack. This operation is used for complex arithmetic expressions.

```gbvm
VM_RPN  

```

--------------------------------

### VM_RET: Return from Call

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Returns from the current near call. Use this to exit a subroutine.

```gbvm
VM_RET  

```

--------------------------------

### VM_JUMP

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Jumps to a specified near address.

```APIDOC
## VM_JUMP LABEL

### Description
Jumps to near address.

### Parameters
#### Path Parameters
- **ARG0** (Jump Label) - Required - The label to jump to.

### Method
VM_JUMP
```

--------------------------------

### VM_SET_TEXT_SOUND

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Sets the sound effect for text output in the GBVM.

```APIDOC
## VM_SET_TEXT_SOUND

### Description
Sets the sound effect for the text output.

### Parameters
#### Path Parameters
- **BANK** (int) - Bank number of the effect.
- **ADDR** (int) - Address of the effect.
- **MASK** (int) - Mute mask of the effect.
```

--------------------------------

### VM_OVERLAY_SET_SUBMAP

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Copies a rectangular area of tiles from the scene background to the overlay window.

```APIDOC
## VM_OVERLAY_SET_SUBMAP

### Description
Copies a rectangular area of tiles from the scene background to the overlay window.

### Parameters
* **X** (number) - X-coordinate within the overlay window of the upper left corner in tiles.
* **Y** (number) - Y-coordinate within the overlay window of the upper left corner in tiles.
* **W** (number) - Width of the area in tiles.
* **H** (number) - Height of the area in tiles.
* **SX** (number) - X-coordinate within the level background map in tiles.
* **SY** (number) - Y-coordinate within the level background map in tiles.
```

--------------------------------

### VM_MEMCPY

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Copies VM memory.

```APIDOC
## VM_MEMCPY

### Description
Copies VM memory.

### Parameters
#### Path Parameters
- **DEST** (variable) - Required - First destination variable.
- **SOUR** (variable) - Required - First source variable.
- **COUNT** (number) - Required - Number of variables to be copied.
```

--------------------------------

### VM_SCENE_POP

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Removes the last scene from the scene stack and loads it in the GBVM.

```APIDOC
## VM_SCENE_POP

### Description
Removes the last scene from the scene stack and loads it.
```

--------------------------------

### VM_ACTOR_BEGIN_UPDATE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Initiates the update script for a specific actor.

```APIDOC
## VM_ACTOR_BEGIN_UPDATE

### Description
Begins the actor update script.

### Parameters
* **ACTOR** (number) - The actor number for which to begin the update script.
```

--------------------------------

### VM_CALL_NATIVE

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Calls native code by the far pointer.

```APIDOC
## VM_CALL_NATIVE

### Description
Calls native code by the far pointer.

### Parameters
#### Path Parameters
- **BANK** (number) - Required - Bank number of the native routine.
- **PTR** (address) - Required - Address of the native routine.
```

--------------------------------

### VM_FADE_IN

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Fades the screen in, with options for modal or non-modal fade in the GBVM.

```APIDOC
## VM_FADE_IN

### Description
Fades screen in. Macro for VM_FADE ^/(.FADE_IN)/ or VM_FADE ^/(.FADE_IN | .FADE_MODAL)/.

### Parameters
#### Path Parameters
- **IS_MODAL** (int) - Determines fade type:
  - `0` - Nonmodal fade.
  - `1` - Modal fade.
```

--------------------------------

### VM_LOAD_TEXT

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads text into memory for display in the GBVM.

```APIDOC
## VM_LOAD_TEXT

### Description
Loads text in memory.

### Parameters
#### Path Parameters
- **NARGS** (int) - Amount of arguments that are passed before the null-terminated string.

### Example
```
VM_LOAD_TEXT   0    
.asciz "text to render"    
```
```

--------------------------------

### VM_IF

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Compares two variables based on a condition and jumps to a label if the condition is true.

```APIDOC
## VM_IF CONDITION, IDXA, IDXB, LABEL, N

### Description
Compares two variables using for condition.

### Parameters
#### Path Parameters
- **CONDITION** (Condition Type) - Required - The condition for the test (e.g., `.EQ`, `.LT`, `.LTE`, `.GT`, `.GTE`, `.NE`).
- **IDXA** (Variable Index) - Required - The index of the first variable (A).
- **IDXB** (Variable Index) - Required - The index of the second variable (B).
- **LABEL** (Jump Label) - Required - The jump label when the result is TRUE.
- **N** (Number) - Required - The number of values to be removed from the stack after evaluating the condition.

### Method
VM_IF
```

--------------------------------

### Attach Music Routine

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Attaches a script routine to a music event, specifying the routine ID, bank, and address.

```gbvm
VM_MUSIC_ROUTINE ROUTINE, BANK, ADDR
```

--------------------------------

### VM_LOOP

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loops execution while a variable is not zero, jumping to a specified label.

```APIDOC
## VM_LOOP IDX, LABEL, N

### Description
Loops while variable is not zero, by the near address.

### Parameters
#### Path Parameters
- **IDX** (Variable Index) - Required - The loop counter variable index.
- **LABEL** (Jump Label) - Required - The jump label for the next iteration.
- **N** (Number) - Required - The amount of values to be removed from the stack on exit.

### Method
VM_LOOP
```

--------------------------------

### VM_INVOKE: Invoke C Function

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Invokes a C function until it returns true. Supports functions like _wait_frames and _camera_shake. N is the number of arguments to remove on return, and PARAMS points to the first parameter.

```gbvm
VM_INVOKE BANK, ADDR, N, PARAMS  

```

--------------------------------

### Switch Text Layer

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Changes the layer where text will be rendered. Supports background (.TEXT_LAYER_BKG) and overlay (.TEXT_LAYER_WIN) layers.

```assembly
VM_SWITCH_TEXT_LAYER LAYER  

```

--------------------------------

### VM_LOOP: Loop Execution

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loops execution while a variable is not zero, jumping to a specified label. N specifies values to remove from the stack on exit.

```gbvm
VM_LOOP IDX, LABEL, N  

```

--------------------------------

### VM_MUSIC_SETPOS

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Sets the playback position for the current song in the GBVM.

```APIDOC
## VM_MUSIC_SETPOS

### Description
Sets playback position for the current song.

### Parameters
#### Path Parameters
- **PATTERN** (int) - The pattern to set the song position to.
- **ROW** (int) - The row to set the song position to.
```

--------------------------------

### VM_OVERLAY_SET_MAP

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Copies a tilemap to the overlay at a specified position.

```APIDOC
## VM_OVERLAY_SET_MAP

### Description
Copies a tilemap starting at a given tile ID (`IDX`) to the overlay at a position.

### Parameters
#### Path Parameters
- **IDX** (tile ID) - Required - The starting tile ID for the tilemap.
- **X_IDX** (position) - Required - The X position on the overlay.
- **Y_IDX** (position) - Required - The Y position on the overlay.
- **BANK** (number) - Required - The bank number of the tilemap.
- **BKG** (tilemap) - Required - The tilemap data.
```

--------------------------------

### Copy Scene Submap to Overlay

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Copies a rectangular tile area from the scene background to the overlay window.

```gbvm
VM_OVERLAY_SET_SUBMAP X, Y, W, H, SX, SY  
```

--------------------------------

### VM_PUSH_VALUE: Push Variable Value

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Pushes the value of a specified variable onto the VM stack. IDX is the variable to push.

```gbvm
VM_PUSH_VALUE IDX  

```

--------------------------------

### Load Text Data

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Loads text data into memory, preparing it for display. The text string is defined using the .asciz command.

```gbvm
VM_LOAD_TEXT NARGS  

```

```gbvm
VM_LOAD_TEXT   0    
.asciz "text to render"    

```

--------------------------------

### VM_CALL: Call Script Subroutine

Source: https://www.gbstudio.dev/docs/scripting/gbvm/gbvm-operations

Calls a script subroutine located at a near address. ADDR is the address of the subroutine.

```gbvm
VM_CALL ADDR  

```
Tokens:
Raw