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 withSIZEequal to0.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 is0to7. A value of0will 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 is0to7. A value of0will make the dialogue to move at2pxper 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 is0to7. A value of0will make the dialogue to move at2pxper frame. Any other value will be number of pixels per frame._text_ff_joypad: When set to1the 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:
%dRender a variable value%DnRender a variable value withnlength%cRender 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\xSets the text speed for the next characters in the current text.xis a value between1and8that represents the number of frames between the render of a character using2^(x-2).\002\xSets the text font\003\x\ySets the position for the next character\004\x\ySets the position for the next character relative to the last character\005\TBD\006\maskWait for input to continue to the next character.\007\nInverts the colors of the following characters.\nNext line\rScroll 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.