[BETA] GBVM Reference

GBVM.md

⚠️ WARNING ⚠️

This doc is pretty much a WIP and incomplete reference of all the GBVM commands.

Important notes:

• Not all of them are available in the latest version of GB Studio.
• https://github.com/chrismaltby/gbvm/tree/master/include/vm.i should still be considered the source of truth as this list might not be updated regularly.

GBVM COMMAND REFERENCE

CORE

VM_IF CONDITION, IDXA, IDXB, LABEL, N

Compares two variables or values on stack (IDXA and IDXB) using a CONDITION. If the comparision is true the execution will jump to LABEL, if false continue execution. Then, clear N arguments from stack.

CONDITION

  .EQ                = 1 - Equal 
  .LT                = 2 - Less Than
  .LTE               = 3 - Less Than or Equal
  .GT                = 4 - Greater Than
  .GTE               = 5 - Greather Than or Equal
  .NE                = 6 - Not Equal
  .AND               = 7 - Binary And
  .OR                = 8 - Binary Or

VM_IF_CONST CONDITION, IDXA, B, LABEL, N

Compares a variable or value on stack (IDXA) with a constant (B) using a CONDITION. If the comparision is true the execution will jump to LABEL, if false continue execution. Then, clear N arguments from stack.

CONDITION

  .EQ                = 1 - Equal 
  .LT                = 2 - Less Than
  .LTE               = 3 - Less Than or Equal
  .GT                = 4 - Greater Than
  .GTE               = 5 - Greather Than or Equal
  .NE                = 6 - Not Equal
  .AND               = 7 - Binary And
  .OR                = 8 - Binary Or

VM_SWITCH IDX, SIZE, N

Compares a variable or value on stack (IDX) with a set of values, and if equal jump to the specified label. Then, clear N arguments from stack.

SIZE sets the number of values to compare, and each of the values are defined with:

  .dw A, LABEL

Where A is the value and LABEL the label to jump to.

VM_JUMP ARG0

Jumps to near address.

VM_LOOP IDX, LABEL, NPOP

Loops by near address, counter is on stack, counter is removed on exit.

VM_LOOP_REL IDX, LABEL, NPOP

Loops by relative (one-byte) offset, counter is on stack, counter is removed on exit.

VM_CALL ARG0

Calls by near address.

VM_CALL_REL ARG0

Calls by relative (one-byte) offset.

VM_CALL_NATIVE BANK, PTR

Calls native code by far pointer.

VM_RET

Returns from relative or near call.

VM_RET_N ARG0

Returns from relative or near call and clear ARG0 arguments on stack.

VM_CALL_FAR BANK, ADDR

Calls far (inter-bank call).

VM_RET_FAR

Returns from far call.

VM_RET_FAR_N ARG0

Retursn from far call and clear ARG0 arguments on stack.

VM_INVOKE BANK, ADDR, ARG2, ARG3

Invokes BANK:ADDR C function until it returns true.

Valid functions are:

• _wait_frames
• _camera_shake

VM_STOP

Stops execution of context

VM_IDLE

Signals runner that context is in a waitable state

VM_LOCK

Locks VM

VM_UNLOCK

Unlocks VM

VM_BEGINTHREAD BANK, THREADPROC, HTHREAD, NARGS

Spawns a thread in a separate context

VM_JOIN IDX

Joins a thread

VM_TERMINATE IDX

Kills a thread

VM_RAISE CODE, SIZE

Raises an exception CODE.

Valid values for CODE are:

• EXCEPTION_RESET: Resets the device. Always called with SIZE equal to 0.
• EXCEPTION_CHANGE_SCENE: Changes to a new scene. See Scene for more details.
• EXCEPTION_SAVE: Saves the state of the game. See Save State for more details.
• EXCEPTION_LOAD: Loads the saved state of the game. See Save State for more details.

VM_TEST_TERMINATE FLAGS

Terminates unit-testing immediately

FLAGS

  .TEST_WAIT_VBL                 = 1

VM_POLL_LOADED IDX

Checks that VM state was restored and reset the restore flag

VM_POLL IDX_EVENT, IDX_VALUE, MASK

STACK

VM_PUSH_CONST VAL

Pushes immediate value VAL to the top of the VM stack.

VM_PUSH_VALUE IDX

Pushes a value on VM stack or a global onto VM stack

VM_PUSH_VALUE_IND ARG0

Pushes a value on VM stack or a global indirectly from an index in the variable on VM stack or in a global onto VM stack

VM_PUSH_REFERENCE IDX

Translates IDX into absolute index and pushes result to VM stack

VM_POP N

Removes the top N values from VM stack.

VM_RESERVE N

Similar to pop

VM_SET IDXA, IDXB

Assigns a value on VM stack or a global to a value on VM stack or a global

VM_SET_CONST IDX, VAL

Assigns a constant value VAL to a variable in the stack. A non-negative index IDX points to a global variable. A negative index points to the variable in the position relative to the top of the stack.

VM_SET_INDIRECT IDXA, IDXB

Assigns a value on VM stack or a global indirectly to a value on VM stack ar a global

VM_GET_INDIRECT IDXA, IDXB

Assigns a value on VM stack or a global to a value on VM stack ar a global indirectly

VM_GET_TLOCAL IDXA, IDXB

Gets thread local variable. Non-negative index of IDXB points to a thread local variable (parameters passed into thread).

VM_SET_UINT8 ADDR, IDXA

Sets unsigned int8 in WRAM. ADDR is an address of unsigned int8

VM_SET_CONST_UINT8 ADDR, V

Sets unsigned int8 in WRAM. ADDR is an address of int8

VM_GET_UINT8 IDXA, ADDR

Gets unsigned int8 from WRAM. ADDR is an address of unsigned int8

VM_SET_INT8 ADDR, IDXA

Sets int8 in WRAM. ADDR is an address of int8

VM_SET_CONST_INT8 ADDR, V

Sets int8 in WRAM. ADDR is an address of int8

VM_GET_INT8 IDXA, ADDR

Gets int8 from WRAM. ADDR is an address of int8

VM_SET_INT16 ADDR, IDXA

Sets int16 in WRAM. ADDR is an address of int16

VM_SET_CONST_INT16 ADDR, V

Sets int16 in WRAM. ADDR is an address of int16

VM_GET_INT16 IDXA, ADDR

Gets int16 from WRAM. ADDR is an address of int16

VM_MEMSET DEST, VALUE, COUNT

VM_MEMCPY DEST, SOUR, COUNT

SCENE

To load a new scene raise a EXCEPTION_CHANGE_SCENE exception using VM_RAISE.

The scene to load is defined using IMPORT_FAR_PTR_DATA followed by the scene symbol.

For example to load scene 10:

VM_RAISE  	EXCEPTION_CHANGE_SCENE, 3
  IMPORT_FAR_PTR_DATA _scene_10

VM_SCENE_PUSH

Pushes the current scene to the scene stack.

VM_SCENE_POP

Removes the last scene from the scene stack an loads it.

VM_SCENE_POP_ALL

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

VM_SCENE_STACK_RESET

Removes all the scenes from the scene stack.

ACTOR

VM_ACTOR_ACTIVATE ACTOR

VM_ACTOR_DEACTIVATE ACTOR

VM_ACTOR_SET_POS IDX

Actor struct:
    INT16 ID;
    INT16 X, Y;

VM_ACTOR_GET_POS IDX

Actor struct:
    INT16 ID;
    INT16 X, Y;

VM_ACTOR_MOVE_TO IDX

Actor struct:
    UBYTE ID;
    UBYTE _pad0; 
    INT16 X;
    INT16 Y;
    UBYTE ATTR; 

Actor Attributes
  .ACTOR_ATTR_H_FIRST     = 0x01
  .ACTOR_ATTR_CHECK_COLL  = 0x02
  .ACTOR_ATTR_DIAGONAL    = 0x04

VM_ACTOR_MOVE_CANCEL ACTOR

VM_ACTOR_SET_DIR ACTOR, DIR

DIR
  .DIR_DOWN               = 0
  .DIR_RIGHT              = 1
  .DIR_UP                 = 2
  .DIR_LEFT               = 3

VM_ACTOR_GET_DIR IDX, DEST

VM_ACTOR_GET_ANGLE IDX, DEST

VM_ACTOR_SET_MOVE_SPEED ACTOR, SPEED

VM_ACTOR_SET_COLL_ENABLED ACTOR, ENABLED

VM_ACTOR_SET_HIDDEN ACTOR, HIDDEN

VM_ACTOR_SET_SPRITESHEET ACTOR, SHEET_BANK, SHEET

VM_ACTOR_SET_SPRITESHEET_BY_REF ACTOR, FAR_PTR

VM_ACTOR_SET_ANIM ACTOR, ANIM

VM_ACTOR_SET_ANIM_FRAME ACTOR

Actor struct
  INT16 ID;
  INT16 FRAME;

VM_ACTOR_GET_ANIM_FRAME ACTOR

Actor struct
  INT16 ID;
  INT16 FRAME;

VM_ACTOR_SET_ANIM_TICK ACTOR, TICK

VM_ACTOR_SET_ANIM_SET ACTOR, OFFSET

VM_ACTOR_SET_BOUNDS ACTOR, LEFT, RIGHT, TOP, BOTTOM

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

VM_ACTOR_EMOTE ACTOR, AVATAR_BANK, AVATAR

VM_ACTOR_TERMINATE_UPDATE ACTOR

UI

• _text_draw_speed: Defines the global draw speed for text fields. The value range is 0 to 7. A value of0 will render the text as fast as possible. Any other value will be the number of frames between each character rendering.
• _text_in_speed: Defines the speed at which the dialogue window will exit the screen. The value ranges is 0 to 7. A value of 0 will make the dialogue to move at 2px per frame. Any other value will be number of pixels per frame.
• _text_out_speed: Defines the speed at which the dialogue window will exit the screen. The value ranges is 0 to 7. A value of 0 will make the dialogue to move at 2px per frame. Any other value will be number of pixels per frame.
• _text_ff_joypad: When set to 1 the dialogue text will be fast forwarded if any button is pressed.

Those fields can be set using VM_SET_CONST_INT8.

VM_LOAD_TEXT N

Loads a text in memory that contains N variables.

The text string is defined using the .asciz command:

VM_LOAD_TEXT   0
  .asciz "text to render"

Displaying variables:

The following format specifiers allow to render variables as part of the text:

• %d Render a variable value
• %Dn Render a variable value with n length
• %c Render a character based on the variable value

The variables need to be defined before the .asciz call using .dw followed by a list of N variables in the order they'll be rendered.

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

Escape Sequences:

The text string can contain escape sequence that modify the behavior or apparence of the text.

• \001\x Sets the text speed for the next characters in the current text. x is a value between 1 and 8 that represents the number of frames between the render of a character using 2^(x-2).
• \002\x Sets the text font
• \003\x\y Sets the position for the next character
• \004\x\y Sets the position for the next character relative to the last character
• \005\ TBD
• \006\mask Wait for input to continue to the next character.
• \007\n Inverts the colors of the following characters.
• \n Next line
• \r Scroll text one line up

VM_DISPLAY_TEXT

Renders the text in the defined layer (overlay, by default)

VM_SWITCH_TEXT_LAYER LAYER

Changes the layer where the text will be rendered.

LAYER

  .TEXT_LAYER_BKG         = 0 - Render text in the background layer
  .TEXT_LAYER_WIN         = 1 - Render text in the overlay layer

VM_OVERLAY_SHOW X, Y, COLOR, OPTIONS

COLOR

  .UI_COLOR_BLACK         = 0
  .UI_COLOR_WHITE         = 1

OPTIONS

  .UI_DRAW_FRAME          = 1
  .UI_AUTO_SCROLL         = 2

VM_OVERLAY_HIDE

VM_OVERLAY_SETPOS X, Y

VM_OVERLAY_MOVE_TO X, Y, SPEED

SPEED
  .OVERLAY_IN_SPEED        = -1
  .OVERLAY_OUT_SPEED       = -2
  .OVERLAY_SPEED_INSTANT   = -3

VM_OVERLAY_WAIT IS_MODAL, WAIT_FLAGS

IS_MODAL

  .UI_NONMODAL              = 0
  .UI_MODAL                 = 1

WAIT_FLAGS

  .UI_WAIT_NONE             =  0 - No wait
  .UI_WAIT_WINDOW           =  1 - Wait until the window moved to its final position
  .UI_WAIT_TEXT             =  2 - Wait until all the text finished rendering
  .UI_WAIT_BTN_A            =  4 - Wait until "A" is pressed
  .UI_WAIT_BTN_B            =  8 - Wait until "B" is pressed
  .UI_WAIT_BTN_ANY          = 16 - Wait until any button is pressed

VM_OVERLAY_CLEAR X, Y, W, H, COLOR, OPTIONS

COLOR
  .UI_COLOR_BLACK         = 0
  .UI_COLOR_WHITE         = 1

OPTIONS
  .UI_DRAW_FRAME          = 1
  .UI_AUTO_SCROLL         = 2

VM_LOAD_TILES ID, LEN, BANK, ADDR

ID
  .FRAME_TILE_ID          = 0xC0
  .CURSOR_TILE_ID         = 0xCB

LEN
  .FRAME_LENGTH           = 9
  .CURSOR_LENGTH          = 1

VM_SET_FONT FONT_INDEX

VM_SET_PRINT_DIR DIRECTION

DIRECTION
  .UI_PRINT_LEFTTORIGHT   = 0
  .UI_PRINT_RIGHTTOLEFT   = 1

VM_OVERLAY_SCROLL X, Y, W, H, COLOR

Scrolls the rectangle area defined by X, Y, W and H up by one row and fills the lower row with COLOR.

COLOR
  .UI_COLOR_BLACK         = 0
  .UI_COLOR_WHITE         = 1

VM_OVERLAY_SET_SCROLL X, Y, W, H, COLOR

Defines the scrollable area (in tiles, using X, Y, W and H) for the overlay. When the text overflows that area it'll scroll up by 1 row and fill the lower row with COLOR.

Using .UI_AUTO_SCROLL in VM_OVERLAY_SHOW sets the scrollable area to the whole overlay.

COLOR

  .UI_COLOR_BLACK         = 0
  .UI_COLOR_WHITE         = 1

VM_OVERLAY_SET_MAP IDX, X, Y, BANK, BKG

Renders a tileset from the background VRAM starting from a given tile IDX into the given X and Y

VM_OVERLAY_SET_SUBMAP X_IDX, Y_IDX, W, H, SX, SY

Copies a section of tiles from the scene background (in tiles, using SX, SY) to the given overlay coordinates (in tiles, using X_IDX, Y_IDX, W and H).

VM_CHOICE IDX, OPTIONS, COUNT

OPTIONS
  .UI_MENU_STANDARD       = 0
  .UI_MENU_LAST_0         = 1
  .UI_MENU_CANCEL_B       = 2

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

CAMERA

VM_CAMERA_MOVE_TO IDX, SPEED, AFTER_LOCK

Moves the camera to a position set in the stack at a given SPEED and configures the lock status of the camera.

AFTER_LOCK
  .CAMERA_LOCK             = 0b00000011
  .CAMERA_LOCK_X           = 0b00000001
  .CAMERA_LOCK_Y           = 0b00000010
  .CAMERA_UNLOCK           = 0b00000000

VM_CAMERA_SET_POS IDX

  .CAMERA_SHAKE_X          = 1
  .CAMERA_SHAKE_Y          = 2

SCREEN

VM_FADE FLAGS

FLAGS
  .FADE_NONMODAL          = 0x00
  .FADE_MODAL             = 0x01
  .FADE_OUT               = 0x00
  .FADE_IN                = 0x02

VM_FADE_IN IS_MODAL

IS_MODAL
  .FADE_NONMODAL          = 0x00
  .FADE_MODAL             = 0x01

VM_FADE_OUT IS_MODAL

IS_MODAL
  .FADE_NONMODAL          = 0x00
  .FADE_MODAL             = 0x01

INPUT

VM_INPUT_WAIT MASK

VM_CONTEXT_PREPARE SLOT, BANK, ADDR

VM_INPUT_ATTACH MASK, SLOT

 SLOT
  .OVERRIDE_DEFAULT       = 0x80

VM_INPUT_DETACH MASK

VM_INPUT_GET IDX, JOYID

JOYID
  .JOY0                   = 0
  .JOY1                   = 1
  .JOY2                   = 2
  .JOY3                   = 3

PROJECTILES

VM_PROJECTILE_LAUNCH TYPE, IDX

MATH

VM_RPN

OPERANDS
  .R_INT8 ARG0
  .R_INT16 ARG0
  .R_REF ARG0
  .R_REF_IND ARG0
  .R_REF_SET ARG0

  .R_OPERATOR ARG0

OPERATORS
  .ADD               = '+'
  .SUB               = '-'
  .MUL               = '*'
  .DIV               = '/'
  .MOD               = '%'
  .B_AND             = '&'
  .B_OR              = '|'
  .B_XOR             = '^'
  .B_NOT             = '~' 
  .ABS               = '@'
  .MIN               = 'm'
  .MAX               = 'M'
  .ISQRT             = 'Q'
  .EQ                = 1
  .LT                = 2
  .LTE               = 3
  .GT                = 4
  .GTE               = 5
  .NE                = 6
  .AND               = 7
  .OR                = 8
  .NOT               = 9

  .R_STOP

VM_RANDOMIZE

Initializes RNG seed

VM_RAND IDX, MIN, LIMIT

Returns random value between MIN and MIN + LIMIT

VM_SIN_SCALE IDX, IDX_ANGLE, SCALE

VM_COS_SCALE IDX, IDX_ANGLE, SCALE

TIMER

VM_TIMER_PREPARE TIMER, BANK, ADDR

Load script into timer context

VM_TIMER_SET TIMER, INTERVAL

Start a timer calling once every INTERVAL * 16 frames

VM_TIMER_STOP TIMER

Stops a timer.

VM_TIMER_RESET TIMER

Resets a timer countdown to 0.

MUSIC

VM_MUSIC_PLAY TRACK_BANK, TRACK, LOOP

Starts playing a music track.

LOOP

  .MUSIC_NO_LOOP  = 0
  .MUSIC_LOOP     = 1

VM_MUSIC_STOP

Stops any music track currently playing.

VM_SOUND_MASTERVOL VOL

Sets master volume to VOL

VM_MUSIC_MUTE MASK

Mutes/unmutes channels using MASK. The 4 lower bits of the mask represent the 4 audio channels.

Mask	Channel 1	Channel 2	Channel 3	Channel 4
0b0000	Muted	Muted	Muted	Muted
0b0001	Muted	Muted	Muted	Not Muted
0b0010	Muted	Muted	Not Muted	Muted
0b0011	Muted	Muted	Not Muted	Not Muted
0b0100	Muted	Not Muted	Muted	Muted
0b0101	Muted	Not Muted	Muted	Not Muted
0b0110	Muted	Not Muted	Not Muted	Muted
0b0111	Muted	Not Muted	Not Muted	Not Muted
0b1000	Not Muted	Muted	Muted	Muted
0b1001	Not Muted	Muted	Muted	Not Muted
0b1010	Not Muted	Muted	Not Muted	Muted
0b1011	Not Muted	Muted	Not Muted	Not Muted
0b1100	Not Muted	Not Muted	Muted	Muted
0b1101	Not Muted	Not Muted	Muted	Not Muted
0b1110	Not Muted	Not Muted	Not Muted	Muted
0b1111	Not Muted	Not Muted	Not Muted	Not Muted

VM_MUSIC_SETPOS PATTERN, ROW

Sets music playback position

VM_SFX_PLAY BANK, ADDR, MASK, PRIO

Play a sound effect asset

VM_SET_TEXT_SOUND BANK, ADDR, MASK

Set sound effect asset for text

VM_MUSIC_ROUTINE ROUTINE, BANK, ADDR

Attach script to music event

SAVE STATE

To save or load the state of the game an EXCEPTION_SAVE or EXCEPTION_LOAD exception should be raised using VM_RAISE.

There's three save slots (0, 1 and 2) available to save. .SAVE_SLOT n is used to set which one will be used.

For example, to save on slot 0:

VM_RAISE  	EXCEPTION_SAVE, 1
  .SAVE_SLOT 0

And to load from slot 0:

VM_RAISE  	EXCEPTION_LOAD, 1
  .SAVE_SLOT 0

VM_SAVE_PEEK RES, DEST, SOUR, COUNT, SLOT

Reads COUNT variables from save slot SLOT into variable DEST and puts the result of the operation into RES.

VM_SAVE_CLEAR SLOT

Erases data in save slot SLOT.

SPRITES

VM_SET_SPRITE_VISIBLE MODE

MODE
  .SPRITES_SHOW           = 0
  .SPRITES_HIDE           = 1

VM_SHOW_SPRITES

VM_HIDE_SPRITES

VM_SET_SPRITE_MODE MODE

MODE
  .MODE_8X8               = 0
  .MODE_8X16              = 1

BACKGROUND

VM_GET_TILE_XY TILE_IDX, X_IDX, Y_IDX

VM_REPLACE_TILE TARGET_TILE_IDX, TILEDATA_BANK, TILEDATA, START_IDX, LEN

VM_REPLACE_TILE_XY X, Y, TILEDATA_BANK, TILEDATA, START_IDX

VM_LOAD_TILESET IDX, BANK, BKG

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

COLOR

VM_LOAD_PALETTE MASK, OPTIONS

OPTIONS

    .PALETTE_COMMIT          = 1
    .PALETTE_BKG             = 2
    .PALETTE_SPRITE          = 4

    .DMG_PAL COL1, COL2, COL3, COL4

    .CGB_PAL R1,G1,B1 R2,G2,B2 R3,G3,B3 R4,G4,B4

SIO

VM_SIO_SET_MODE MODE

MODE
  .SIO_MODE_NONE          = 0
  .SIO_MODE_MASTER        = 1
  .SIO_MODE_SLAVE         = 2

VM_SIO_EXCHANGE SOUR, DEST, SIZE

RTC

VM_RTC_LATCH

Latch RTC value for access

VM_RTC_GET IDX, WHAT

Read RTC value from a variable.

WHAT
  .RTC_SECONDS             = 0x00
  .RTC_MINUTES             = 0x01
  .RTC_HOURS               = 0x02
  .RTC_DAYS                = 0x03

VM_RTC_SET IDX, WHAT

Write RTC value into a variable.

WHAT
  .RTC_SECONDS             = 0x00
  .RTC_MINUTES             = 0x01
  .RTC_HOURS               = 0x02
  .RTC_DAYS                = 0x03

VM_RTC_START START

Start or stop RTC

START
  .RTC_STOP                = 0
  .RTC_START               = 1

SGB

VM_SGB_TRANSFER

Transfers SGB packet(s). Data of variable length is placed after this instruction, for example:

VM_SGB_TRANSFER   
    .db ((0x04 << 3) | 1), 1, 0x07, ((0x01 << 4) | (0x02 << 2) | 0x03), 5,5, 10,10,  0, 0, 0, 0, 0, 0, 0, 0 ; ATTR_BLK packet

SGB packet size is a multiple of 16 bytes and encoded in the packet itself, see SGB developer manual.

RUMBLE

VM_RUMBLE ENABLE

Enables or disables rumble on a cart that has that function.