GBVM Operations

Core

VM_STOP

VM_STOP

Stops execution of context.

VM_PUSH_CONST

VM_PUSH_CONST VAL

Pushes immediate value to the top of the VM stack.

VAL: Immediate value to be pushed.

VM_POP

VM_POP N

Removes the top values from the VM stack.

N: Number of values to be removed from the stack.

VM_CALL

VM_CALL ADDR

Calls script by near address.

ADDR: Address of the script subroutine.

VM_RET

VM_RET

Returns from the near call.

VM_RET_N

VM_RET_N N

Returns from the near call and clears N arguments on stack.

N: Number of arguments to be removed from the stack.

VM_GET_FAR

VM_GET_FAR IDX, SIZE, BANK, ADDR

Gets byte or word by the far pointer into variable.

IDX: Target variable.
SIZE: Size of the object to be acquired:
.GET_BYTE - Get 8-bit value.
.GET_WORD - Get 16-bit value.
BANK: Bank number of the object
ADDR: Address of the object

VM_LOOP

VM_LOOP IDX, LABEL, N

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

IDX: Loop counter variable.
LABEL: Jump label for the next iteration.
N: Amount of values to be removed from stack on exit.

.CASE

.CASE VAL, LABEL

VM_SWITCH

VM_SWITCH IDX, SIZE, N

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, where VAL parameter is a value for testing and LABEL is a jump label.

IDX: Variable for compare.
SIZE: Amount of entries for test.
N: Amount of values to be cleaned from stack on exit.

VM_JUMP

VM_JUMP LABEL

Jumps to near address.

ARG0: Jump label.

VM_CALL_FAR

VM_CALL_FAR BANK, ADDR

Calls far routine (inter-bank call).

BANK: Bank number of the routine.
ADDR: Address of the routine.

VM_RET_FAR

VM_RET_FAR

Returns from the far call.

VM_RET_FAR_N

VM_RET_FAR_N N

Returns from the far call and removes N arguments from stack.

N: Number of arguments to be removed from stack.

VM_INVOKE

VM_INVOKE BANK, ADDR, N, PARAMS

Invokes C function until it returns true.

BANK: Bank number of the function.
ADDR: Address of the function, currently 2 functions are implemented:
_wait_frames - Wait for N vblank intervals.
_camera_shake - Shake camera N times.
N: Number of arguments to be removed from stack on return.
PARAMS: Points the first parameter to be passed into the C function.

VM_BEGINTHREAD

VM_BEGINTHREAD BANK, THREADPROC, HTHREAD, NARGS

Spawns a thread in a separate context.

BANK: Bank number of a thread function.
THREADPROC: Address of a thread function.
HTHREAD: Variable that receives the thread handle.
NARGS: Amount of values from the stack to be copied into the stack of the new context.

VM_IF

VM_IF CONDITION, IDXA, IDXB, LABEL, N

Compares two variables using for condition.

CONDITION: Condition for test:
.EQ - Variables are equal.
.LT - A is lower than B.
.LTE - A is lower or equal than B.
.GT - A is greater than B.
.GTE - A is greater or equal than B.
.NE - A is not equal to B.
IDXA: A variable.
IDXB: B variable.
LABEL: Jump label when result is TRUE.
N: Number of values to be removed from stack after evaluating the condition.

VM_PUSH_VALUE_IND

VM_PUSH_VALUE_IND IDX

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

IDX: Variable that contains the index of the variable to be pushed on stack.

VM_PUSH_VALUE

VM_PUSH_VALUE IDX

Pushes a value of the variable onto stack.

IDX: Variable to be pushed.

VM_RESERVE

VM_RESERVE N

Reserves or disposes amount of values on stack.

N: Positive value - amount of variables to be reserved on stack, negative value - amount of variables to be popped from stack.

VM_SET

VM_SET IDXA, IDXB

Assigns variable B to variable A.

IDXA: Variable A.
IDXB: Variable B.

VM_SET_CONST

VM_SET_CONST IDX, VAL

Assigns immediate value to the variable.

IDX: Target variable.
VAL: Source immediate value.

VM_RPN

VM_RPN

Reverse Polish Notation (RPN) calculator, returns result(s) on the VM stack.

.R_INT8

.R_INT8 ARG0

.R_INT16

.R_INT16 ARG0

.R_REF

.R_REF ARG0

.R_REF_IND

.R_REF_IND ARG0

.R_REF_SET

.R_REF_SET ARG0

.R_REF_SET_IND

.R_REF_SET_IND ARG0

.R_REF_MEM

.R_REF_MEM TYP, ADDR

.R_REF_MEM_SET

.R_REF_MEM_SET TYP, ADDR

.R_OPERATOR

.R_OPERATOR ARG0

.R_STOP

.R_STOP

VM_JOIN

VM_JOIN IDX

Joins a thread.

IDX: Thread handle for joining.

VM_TERMINATE

VM_TERMINATE IDX

Kills a thread.

IDX: Thread handle for killing.

VM_IDLE

VM_IDLE

Signals thread runner that context is in a waitable state.

VM_GET_TLOCAL

VM_GET_TLOCAL IDXA, IDXB

Gets thread local variable.

IDXA: Target variable.
IDXB: Thread local variable index.

VM_IF_CONST

VM_IF_CONST CONDITION, IDXA, B, LABEL, N

Compares a variable to an immediate value.

CONDITION: Condition for test:
.EQ - Variables are equal.
.LT - A is lower than B.
.LTE - A is lower or equal than B.
.GT - A is greater than B.
.GTE - A is greater or equal than B.
.NE - A is not equal to B.
IDXA: A variable.
B: Immediate value to be compared with.
LABEL: Jump label when result is TRUE.
N: Number of values to be removed from stack after evaluating the condition.

VM_GET_UINT8

VM_GET_UINT8 IDXA, ADDR

Gets unsigned int8 from WRAM.

IDXA: Target variable.
ADDR: Address of the unsigned 8-bit value in WRAM.

VM_GET_INT8

VM_GET_INT8 IDXA, ADDR

Gets signed int8 from WRAM.

IDXA: Target variable.
ADDR: Address of the signed 8-bit value in WRAM.

VM_GET_INT16

VM_GET_INT16 IDXA, ADDR

Gets signed int16 from WRAM.

IDXA: Target variable.
ADDR: Address of the signed 16-bit value in WRAM.

VM_SET_UINT8

VM_SET_UINT8 ADDR, IDXA

Sets unsigned int8 in WRAM from variable.

ADDR: Address of the unsigned 8-bit value in WRAM.
IDXA: Source variable.

VM_SET_INT8

VM_SET_INT8 ADDR, IDXA

Sets signed int8 in WRAM from variable.

ADDR: Address of the signed 8-bit value in WRAM.
IDXA: Source variable.

VM_SET_INT16

VM_SET_INT16 ADDR, IDXA

Sets signed int16 in WRAM from variable.

ADDR: Address of the signed 16-bit value in WRAM.
IDXA: Source variable.

VM_SET_CONST_INT8

VM_SET_CONST_INT8 ADDR, VAL

Sets signed int8 in WRAM to the immediate value.

ADDR: Address of the signed 8-bit value in WRAM.
VAL: Immediate value.

VM_SET_CONST_UINT8

VM_SET_CONST_UINT8 ADDR, VAL

Sets unsigned int8 in WRAM to the immediate value.

ADDR: Address of the unsigned 8-bit value in WRAM.
VAL: Immediate value.

VM_SET_CONST_INT16

VM_SET_CONST_INT16 ADDR, VAL

Sets signed int16 in WRAM to the immediate value.

ADDR: Address of the signed 16-bit value in WRAM.
VAL: Immediate value.

VM_INIT_RNG

VM_INIT_RNG IDX

Initializes RNG seed with the value from the variable.

IDX: Seed value.

VM_RANDOMIZE

VM_RANDOMIZE

Initializes RNG seed.

VM_RAND

VM_RAND IDX, MIN, LIMIT

Returns random value between MIN and MIN + LIMIT.

IDX: Target variable.
MIN: Minimal random value.
LIMIT: Range of the random values.

VM_LOCK

VM_LOCK

Disables switching of VM threads.

VM_UNLOCK

VM_UNLOCK

Enables switching of VM threads.

VM_RAISE

VM_RAISE CODE, SIZE

Raises an exception.

CODE: Exception code:
EXCEPTION_RESET - Resets the device.
EXCEPTION_CHANGE_SCENE - Changes to a new scene.
EXCEPTION_SAVE - Saves the state of the game.
EXCEPTION_LOAD - Loads the saved state of the game.
SIZE: Length of the parameters to be passed into the exception handler.

VM_SET_INDIRECT

VM_SET_INDIRECT IDXA, IDXB

Assigns variable that is addressed indirectly to the other variable.

IDXA: Variable that contains the index of the target variable.
IDXB: Source variable that contains the value to be assigned.

VM_GET_INDIRECT

VM_GET_INDIRECT IDXA, IDXB

Assigns a variable to the value of variable that is addressed indirectly.

IDXA: Target variable.
IDXB: Variable that contains the index of the source variable.

VM_TEST_TERMINATE

VM_TEST_TERMINATE FLAGS

Terminates unit-testing immediately.

FLAGS: Terminate flags:
.TEST_WAIT_VBL - Wait for VBlank before terminating.

VM_POLL_LOADED

VM_POLL_LOADED IDX

Checks that VM state was restored and resets the restore flag.

IDX: Target result variable.

VM_PUSH_REFERENCE

VM_PUSH_REFERENCE IDX

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

IDX: Index of the variable.

VM_CALL_NATIVE

VM_CALL_NATIVE BANK, PTR

Calls native code by the far pointer.

BANK: Bank number of the native routine.
PTR: Address of the native routine.

VM_MEMSET

VM_MEMSET DEST, VALUE, COUNT

Clears VM memory.

DEST: First variable to be cleared.
VALUE: Variable containing the value to be filled with.
COUNT: Number of variables to be filled.

VM_MEMCPY

VM_MEMCPY DEST, SOUR, COUNT

Copies VM memory.

DEST: First destination variable.
SOUR: First source variable.
COUNT: Number of variables to be copied.

Actor

VM_ACTOR_MOVE_TO

VM_ACTOR_MOVE_TO IDX

Moves actor to a new position.

IDX: 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:
.ACTOR_ATTR_H_FIRST - Move horizontal first.
.ACTOR_ATTR_CHECK_COLL - Respect collisions.
.ACTOR_ATTR_DIAGONAL - Allow diagonal movement

VM_ACTOR_MOVE_CANCEL

VM_ACTOR_MOVE_CANCEL ACTOR

Cancels movement of actor.

ACTOR: Variable that contains the actor number.

VM_ACTOR_ACTIVATE

VM_ACTOR_ACTIVATE ACTOR

Activates actor.

ACTOR: Variable that contains the actor number.

VM_ACTOR_SET_DIR

VM_ACTOR_SET_DIR ACTOR, DIR

Sets direction of actor.

ACTOR: Variable that contains the actor number.
DIR: One of these directions:
.DIR_DOWN - Actor faces down.
.DIR_RIGHT - Actor faces right.
.DIR_UP - Actor faces up.
.DIR_LEFT - Actor faces left.

VM_ACTOR_DEACTIVATE

VM_ACTOR_DEACTIVATE ACTOR

Deactivates actor.

ACTOR: Variable that contains the actor number.

VM_ACTOR_SET_ANIM

VM_ACTOR_SET_ANIM ACTOR, ANIM

Sets actor animation.

ACTOR: Variable that contains the actor number.
ANIM: Animation number.

VM_ACTOR_SET_POS

VM_ACTOR_SET_POS IDX

Sets actor position.

IDX: 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.

VM_ACTOR_EMOTE

VM_ACTOR_EMOTE ACTOR, AVATAR_BANK, AVATAR

Sets actor emotion.

ACTOR: Variable that contains the actor number.
AVATAR_BANK: Bank of the avatar image.
AVATAR: Address of the avatar image.

VM_ACTOR_SET_BOUNDS

VM_ACTOR_SET_BOUNDS ACTOR, LEFT, RIGHT, TOP, BOTTOM

Sets actor bounding box.

ACTOR: Variable that contains the actor number.
LEFT: Left boundary of the bounding box.
RIGHT: Right boundary of the bounding box.
TOP: Top boundary of the bounding box.
BOTTOM: Bottom boundary of the bounding box.

VM_ACTOR_SET_SPRITESHEET

VM_ACTOR_SET_SPRITESHEET ACTOR, SHEET_BANK, SHEET

Sets actor spritesheet.

ACTOR: Variable that contains the actor number.
SHEET_BANK: Bank of the sprite sheet.
SHEET: Address of the sprite sheet.

VM_ACTOR_SET_SPRITESHEET_BY_REF

VM_ACTOR_SET_SPRITESHEET_BY_REF ACTOR, FAR_PTR

Sets actor spritesheet using far pointer in variables.

ACTOR: Variable that contains the actor number
FAR_PTR: points to the pseudo-struct that contains the address of the sprite sheet:
BANK - Bank of the sprite sheet
DATA - Address of the sprite sheet

VM_ACTOR_REPLACE_TILE

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

Replaces tile in the actor spritesheet.

ACTOR: Variable that contains the actor number.
TARGET_TILE: Tile number for replacement.
TILEDATA_BANK: Bank of the tile data.
TILEDATA: Address of the tile data.
START: Start tile in the tile data array.
LEN: Amount of tiles to be replaced.

VM_ACTOR_GET_POS

VM_ACTOR_GET_POS IDX

Gets actor position.

IDX: points to the beginning of the pseudo-structure that contains these members:
ID - Actor number.
X - X-coordinate of the actor.
Y - Y-coordinate of the actor.

VM_ACTOR_GET_DIR

VM_ACTOR_GET_DIR IDX, DEST

Gets actor direction.

IDX: Variable that contains the actor number.
DEST: Target variable that receive the actor direction.

VM_ACTOR_GET_ANGLE

VM_ACTOR_GET_ANGLE IDX, DEST

Gets actor angle.

IDX: Variable that contains the actor number.
DEST: Target variable to receive the actor angle.

VM_ACTOR_SET_ANIM_TICK

VM_ACTOR_SET_ANIM_TICK ACTOR, TICK

Sets actor animation tick.

ACTOR: Variable that contains the actor number.
TICK: Animation tick.

VM_ACTOR_SET_MOVE_SPEED

VM_ACTOR_SET_MOVE_SPEED ACTOR, SPEED

Sets actor move speed.

ACTOR: Variable that contains the actor number.
SPEED: Actor move speed.

VM_ACTOR_SET_FLAGS

VM_ACTOR_SET_FLAGS ACTOR, FLAGS, MASK

Sets actor flags.

ACTOR: Variable that contains the actor number.
FLAGS: Bit values to be set or cleared:
.ACTOR_FLAG_PINNED - Pin/unpin the actor.
.ACTOR_FLAG_HIDDEN - Hide/show actor.
.ACTOR_FLAG_ANIM_NOLOOP - Disable animation loop.
.ACTOR_FLAG_COLLISION - Disable/enable collision.
.ACTOR_FLAG_PERSISTENT - Set persistent actor flag.
MASK: Bit mask of values to be set or cleared.

VM_ACTOR_SET_HIDDEN

VM_ACTOR_SET_HIDDEN ACTOR, HIDDEN

Hides or shows actor.

ACTOR: Variable that contains the actor number.
HIDDEN: .ACTOR_VISIBLE shows actor, .ACTOR_HIDDEN hides actor.

VM_ACTOR_SET_COLL_ENABLED

VM_ACTOR_SET_COLL_ENABLED ACTOR, ENABLED

Enables or disables actor collisions.

ACTOR: Variable that contains the actor number.
ENABLED: .ACTOR_COLLISION_DISABLED disables actor collision, .ACTOR_COLLISION_ENABLED enables actor collision.

VM_ACTOR_BEGIN_UPDATE

VM_ACTOR_BEGIN_UPDATE ACTOR

Begins actor update script.

ACTOR: Variable that contains the actor number.

VM_ACTOR_TERMINATE_UPDATE

VM_ACTOR_TERMINATE_UPDATE ACTOR

Terminates actor update script.

ACTOR: Variable that contains the actor number.

VM_ACTOR_SET_ANIM_FRAME

VM_ACTOR_SET_ANIM_FRAME ACTOR

Sets actor animation frame.

ACTOR: Pseudo-struct that contains these members:
ID - Actor number.
FRAME - Animation frame.

VM_ACTOR_GET_ANIM_FRAME

VM_ACTOR_GET_ANIM_FRAME ACTOR

Gets actor animation frame.

ACTOR: Pseudo-struct that contains these members:
ID - Actor number.
FRAME - Animation frame.

VM_ACTOR_SET_ANIM_SET

VM_ACTOR_SET_ANIM_SET ACTOR, OFFSET

Sets actor animation set.

ACTOR: Variable that contains the actor number.
OFFSET: Animation set number.

Camera

VM_CAMERA_MOVE_TO

VM_CAMERA_MOVE_TO IDX, SPEED, AFTER_LOCK

Moves the camera to a new position.

IDX: Start of the pseudo-structure which contains the new camera position:
X - X-coordinate of the camera position.
Y - Y-coordinate of the camera position.
SPEED: Speed of the camera movement.
AFTER_LOCK: Lock status of the camera after the movement:
.CAMERA_LOCK - Lock camera by X and Y.
.CAMERA_LOCK_X - Lock camera by X.
.CAMERA_LOCK_Y - Lock camera by Y.
.CAMERA_UNLOCK - Unlock camera.

VM_CAMERA_SET_POS

VM_CAMERA_SET_POS IDX

Sets the camera position.

IDX: Start of the pseudo-structure which contains the new camera position:
X - X-coordinate of the camera position.
Y - Y-coordinate of the camera position.

Color

.DMG_PAL

.DMG_PAL COL1, COL2, COL3, COL4

.CGB_PAL

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

VM_LOAD_PALETTE

VM_LOAD_PALETTE MASK, OPTIONS

Game Boy

VM_LOAD_TILESET

VM_LOAD_TILESET IDX, BANK, BKG

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

VM_SET_SPRITE_VISIBLE

VM_SET_SPRITE_VISIBLE MODE

Sets visibility of sprite layer. Has priority over VM_ACTOR_SET_HIDDEN.

MODE: Mode:
.SPRITES_SHOW - Show sprite layer.
.SPRITES_HIDE - Hide sprite layer.

VM_SHOW_SPRITES

VM_SHOW_SPRITES

Macro for SET_SPRITES_VISIBLE .SPRITES_SHOW.

VM_HIDE_SPRITES

VM_HIDE_SPRITES

Macro for SET_SPRITES_VISIBLE .SPRITES_HIDE.

VM_INPUT_WAIT

VM_INPUT_WAIT MASK

Waits to receive an input.

MASK: Input mask.

VM_INPUT_ATTACH

VM_INPUT_ATTACH MASK, SLOT

Attaches a script to an input.

MASK: Input mask.
SLOT: Slot containing script to attach.

VM_INPUT_GET

VM_INPUT_GET IDX, JOYID

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

IDX: Target variable that receives result.
JOYID: Joypad to get input from:
.JOY0 - Joypad 0.
.JOY1 - Joypad 1.
.JOY2 - Joypad 2.
.JOY3 - Joypad 3.

VM_CONTEXT_PREPARE

VM_CONTEXT_PREPARE SLOT, BANK, ADDR

Assigns a script to a slot for VM_INPUT_ATTACH.

SLOT: Slot to assign to.
BANK: Bank number of the script.
ADDR: Address of the script.

VM_OVERLAY_SET_MAP

VM_OVERLAY_SET_MAP IDX, X_IDX, Y_IDX, BANK, BKG

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

IDX: Tile ID where tilemap starts.
X_IDX: X position on the overlay.
Y_IDX: Y position on the overlay.
BANK: Bank number of tilemap.
BKG: Tilemap.

VM_GET_TILE_XY

VM_GET_TILE_XY TILE_IDX, X_IDX, Y_IDX

Gets the tile ID of background tile at a position.

TILE_IDX: Target variable that receives the tile ID.
X_IDX: X position of background tile.
Y_IDX: Y position of background tile.

VM_REPLACE_TILE

VM_REPLACE_TILE TARGET_TILE_IDX, TILEDATA_BANK, TILEDATA, START_IDX, LEN

Replaces one or more background tiles with background tiles from a tileset.

TARGET_TILE_IDX: Tile ID of starting old tile.
TILEDATA_BANK: Bank number of tileset containing new tiles.
TILEDATA: Tileset containing new tiles.
START_IDX: Tile ID of starting new tile.
LEN: Number of tiles to replace.

VM_POLL

VM_POLL IDX_EVENT, IDX_VALUE, MASK

Waits for an input event, music routine event or both.

IDX_EVENT: Target variable that receives event flag (either 1 for input or 2 for music routine).
IDX_VALUE: Target variable that receives the value of the event.
MASK: Which event(s) to wait for:
.POLL_EVENT_INPUT - Wait for input event.
.POLL_EVENT_MUSIC - Wait for music routine event.

VM_SET_SPRITE_MODE

VM_SET_SPRITE_MODE MODE

Sets sprite mode.

MODE: Sprite mode to set:
.MODE_8X8 - 88 sprites
.MODE_8X16 - 816 sprites

VM_REPLACE_TILE_XY

VM_REPLACE_TILE_XY X, Y, TILEDATA_BANK, TILEDATA, START_IDX

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

X: X position of old background tile.
Y: Y position of old background tile.
TILEDATA_BANK: Bank number of tileset containing new tile.
TILEDATA: Tileset containing new tile.
START_IDX: Tile ID of new tile.

VM_INPUT_DETACH

VM_INPUT_DETACH MASK

Removes an attached script from an input.

MASK: Input mask

GB Printer

VM_PRINTER_DETECT

VM_PRINTER_DETECT ERROR, DELAY

Detects printer.

ERROR: Target variable that receives the result of detection.
DELAY: Detection timeout.

VM_PRINT_OVERLAY

VM_PRINT_OVERLAY ERROR, START, HEIGHT, MARGIN

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

ERROR: Target variable that receives the result of printing.
START: Start line of the overlay window.
HEIGHT: Amount of lines to print.
MARGIN: Lines to feed after the printing is finished.

Load and Save

.SAVE_SLOT

.SAVE_SLOT SLOT

VM_SAVE_PEEK

VM_SAVE_PEEK RES, DEST, SOUR, COUNT, SLOT

Reads variables from a save slot.

RES: Result of the operation.
DEST: First destination variable to be read into.
SOUR: First source variable in the save slot.
COUNT: Number of variables to be read.
SLOT: Save slot number.

VM_SAVE_CLEAR

VM_SAVE_CLEAR SLOT

Erases data in save slot.

SLOT: Slot number.

Math

VM_SIN_SCALE

VM_SIN_SCALE IDX, IDX_ANGLE, SCALE

Returns result of sine function.

IDX: Sine scale (multiplies result) and also target variable that receives result.
IDX_ANGLE: Angle to pass into function. This value starts at 0 (pointing up) and increments 64 every 90 degrees clockwise.
SCALE: Accuracy between 0 and 7.

VM_COS_SCALE

VM_COS_SCALE IDX, IDX_ANGLE, SCALE

Returns result of cosine function.

IDX: Cosine scale (multiplies result) and also target variable that receives result.
IDX_ANGLE: Angle to pass into function. This value starts at 0 (pointing up) and increments 64 every 90 degrees clockwise.
SCALE: Accuracy between 0 and 7.

Music and Sound

VM_MUSIC_PLAY

VM_MUSIC_PLAY TRACK_BANK, TRACK, LOOP

Starts playing of music track.

BANK: Bank number of the track.
ADDR: Address of the track.
LOOP: Obsolete, has no effect.

VM_MUSIC_STOP

VM_MUSIC_STOP

Stops playing of music track.

VM_MUSIC_MUTE

VM_MUSIC_MUTE MASK

Mutes/unmutes music channels.

MASK: Mute Mask. The 4 lower bits 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_SOUND_MASTERVOL

VM_SOUND_MASTERVOL VOL

Sets master volume.

VOL: The volume value.

VM_MUSIC_ROUTINE

VM_MUSIC_ROUTINE ROUTINE, BANK, ADDR

Attaches script to music event.

ROUTINE: The routine ID. An integer between 0 and 3.
BANK: Bank number of the routine.
ADDR: Address of the routine.

VM_SFX_PLAY

VM_SFX_PLAY BANK, ADDR, MASK, PRIO

Plays a sound effect asset.

BANK: Bank number of the effect.
ADDR: Address of the effect.
MASK: Mute mask of the effect.
PRIO: 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_MUSIC_SETPOS

VM_MUSIC_SETPOS PATTERN, ROW

Sets playback position for the current song.

PATTERN: - The pattern to set the song position to.
ROW: - The row to set the song position to.

Projectiles

VM_PROJECTILE_LAUNCH

VM_PROJECTILE_LAUNCH TYPE, IDX

Launches an instance of a projectile loaded in a slot.

TYPE: Slot number of projectile to launch.
IDX: Points to the beginning of the pseudo-structure that contains these members:
pos.x - X position to launch from.
pos.y - Y position to launch from.
angle - Projectile angle or direction.
flags - Flags:
.PROJECTILE_STRONG - Do not destroy projectile on collision.
.PROJECTILE_ANIM_ONCE - Do not loop projectile animation.

VM_PROJECTILE_LOAD_TYPE

VM_PROJECTILE_LOAD_TYPE TYPE, BANK, ADDR

Loads projectile into a slot for VM_PROJECTILE_LAUNCH.

TYPE: Slot number to load into.
BANK: Bank number of projectile data to load.
ADDR: Projectile data to load.

RTC

VM_RTC_LATCH

VM_RTC_LATCH

Latches RTC value for access.

VM_RTC_GET

VM_RTC_GET IDX, WHAT

Reads RTC value.

IDX: Target variable.
WHAT: RTC value to be read:
.RTC_SECONDS - Seconds.
.RTC_MINUTES - Minutes.
.RTC_HOURS - Hours.
.RTC_DAYS - Days.

VM_RTC_SET

VM_RTC_SET IDX, WHAT

Writes RTC value.

IDX: Source variable.
WHAT: RTC value to be written:
.RTC_SECONDS - Seconds.
.RTC_MINUTES - Minutes.
.RTC_HOURS - Hours.
.RTC_DAYS - Days.

VM_RTC_START

VM_RTC_START START

Starts or stops RTC.

START: Start or stop flag:
.RTC_STOP - Stop RTC.
.RTC_START - Start RTC.

Rumble

VM_RUMBLE

VM_RUMBLE ENABLE

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

ENABLE: 1 - enable or 0 - disable.

Scenes

VM_SCENE_PUSH

VM_SCENE_PUSH

Pushes the current scene to the scene stack.

VM_SCENE_POP

VM_SCENE_POP

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

VM_SCENE_POP_ALL

VM_SCENE_POP_ALL

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

VM_SCENE_STACK_RESET

VM_SCENE_STACK_RESET

Removes all the scenes from the scene stack.

Screen Fade

VM_FADE

VM_FADE FLAGS

Fades screen in or out.

FLAGS: Options for screen fade:
.FADE_NONMODAL - Nonmodal fade.
.FADE_MODAL - Modal fade.
.FADE_OUT - Fade out.
.FADE_IN - Fade in.

VM_FADE_IN

VM_FADE_IN IS_MODAL

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

IS_MODAL:
0 - Nonmodal fade.
1 - Modal fade.

VM_FADE_OUT

VM_FADE_OUT IS_MODAL

Fades screen out. Macro for VM_FADE ^/(.FADE_OUT)/ or VM_FADE ^/(.FADE_OUT | .FADE_MODAL)/.

IS_MODAL:
0 - Nonmodal fade.
1 - Modal fade.

SGB

VM_SGB_TRANSFER

VM_SGB_TRANSFER

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

VM_SGB_TRANSFER  
.db ((0x04 &lt;&lt; 3) | 1), 1, 0x07, ((0x01 &lt;&lt; 4) | (0x02 &lt;&lt; 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.

SIO

VM_SIO_SET_MODE

VM_SIO_SET_MODE MODE

Sets SIO mode.

MODE: Mode:
.SIO_MODE_NONE - Close SIO session.
.SIO_MODE_MASTER - Host SIO session.
.SIO_MODE_SLAVE - Join SIO session.

VM_SIO_EXCHANGE

VM_SIO_EXCHANGE SOUR, DEST, SIZE

Exchanges data via SIO.

SOUR: Source variable to send data from.
DEST: Destination variable to receive data to.
SIZE: Packet size.

Text Sound

VM_SET_TEXT_SOUND

VM_SET_TEXT_SOUND BANK, ADDR, MASK

Sets the sound effect for the text output.

BANK: Bank number of the effect.
ADDR: Address of the effect.
MASK: Mute mask of the effect.

Timer

VM_TIMER_PREPARE

VM_TIMER_PREPARE TIMER, BANK, ADDR

Loads script into timer context.

VM_TIMER_SET

VM_TIMER_SET TIMER, INTERVAL

Starts a timer calling once every INTERVAL * 16 frames.

VM_TIMER_STOP

VM_TIMER_STOP TIMER

Stops a timer.

VM_TIMER_RESET

VM_TIMER_RESET TIMER

Resets a timer countdown to 0.

UI

VM_LOAD_TEXT

VM_LOAD_TEXT NARGS

Loads text in memory.

NARGS: Amount of arguments that are passed before the null-terminated string.

The text string is defined using the .asciz command:

VM_LOAD_TEXT   0  
.asciz "text to render"

Displaying variables:

The following format specifiers allow variables to be rendered 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 sequences that modify the behavior or appearance 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 Escapes the next character.
\006\mask Waits for input to continue to the next character.
\007\n Inverts the colors of the following characters. \007\002 enables inverted colors, \007\001 disables them.
\010\x Switches between left to right (x = 01) and right to left (x = 02) printing.
\011 Zero width symbol.
\n Next line.
\013\x Sets UI palette number to x.
\r Scrolls text one line up.

VM_DISPLAY_TEXT_EX

VM_DISPLAY_TEXT_EX OPTIONS, START_TILE

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

OPTIONS: Text rendering options:
.DISPLAY_DEFAULT - Default behavior.
.DISPLAY_PRESERVE_POS - Preserve text position.
START_TILE: Tile number within the text rendering area to be rendered from; use .TEXT_TILE_CONTINUE to proceed from the current position.

VM_DISPLAY_TEXT

VM_DISPLAY_TEXT

Renders text in the defined layer (obsolete).

VM_SWITCH_TEXT_LAYER

VM_SWITCH_TEXT_LAYER LAYER

Changes the LAYER where text will be rendered.

LAYER:
.TEXT_LAYER_BKG - Render text in the background layer.
.TEXT_LAYER_WIN - Render text in the overlay layer.

VM_OVERLAY_SETPOS

VM_OVERLAY_SETPOS X, Y

Sets position of the overlay window in tiles.

X: X-coordinate of the overlay window in tiles.
Y: Y-coordinate of the overlay window in tiles.

VM_OVERLAY_HIDE

VM_OVERLAY_HIDE

Hides the overlay window.

VM_OVERLAY_WAIT

VM_OVERLAY_WAIT IS_MODAL, WAIT_FLAGS

Waits for the completion of one or more UI operations.

IS_MODAL: Indicates whether the operation is modal: .UI_MODAL, or not: .UI_NONMODAL.
WAIT_FLAGS: Bit field, set of events to be waited for:
.UI_WAIT_NONE - No wait.
.UI_WAIT_WINDOW - Wait until the window moved to its final position.
.UI_WAIT_TEXT - Wait until all the text finished rendering.
.UI_WAIT_BTN_A - Wait until "A" is pressed.
.UI_WAIT_BTN_B - Wait until "B" is pressed.
.UI_WAIT_BTN_ANY - Wait until any button is pressed.

VM_OVERLAY_MOVE_TO

VM_OVERLAY_MOVE_TO X, Y, SPEED

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

X: X-coordinate of the new position.
Y: Y-coordinate of the new position.
SPEED: speed of the movement:
.OVERLAY_IN_SPEED - Default speed for appearing of the overlay.
.OVERLAY_OUT_SPEED - Default speed for disappearing of the overlay.
.OVERLAY_SPEED_INSTANT - Instant movement.

VM_OVERLAY_SHOW

VM_OVERLAY_SHOW X, Y, COLOR, OPTIONS

Shows the overlay window.

X: X-coordinate of the new position.
Y: Y-coordinate of the new position.
COLOR: Initial color of the overlay window:
.UI_COLOR_BLACK - Black overlay window.
.UI_COLOR_WHITE - White overlay window.
OPTIONS: Display options:
.UI_DRAW_FRAME - Draw overlay frame.
.UI_AUTO_SCROLL - Set automatic text scroll area; text will be scrolled up when printing more lines than the overlay height.

VM_OVERLAY_CLEAR

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

Clears a rectangular area of the overlay window.

X: X-coordinate in tiles of the upper left corner.
Y: Y-coordinate in tiles of the upper left corner.
W: Width in tiles of the rectangle area.
H: Height in tiles of the rectangle area.
COLOR: initial color of the overlay window:
.UI_COLOR_BLACK - Black overlay window.
.UI_COLOR_WHITE - White overlay window.
OPTIONS: Display options:
.UI_DRAW_FRAME - Draw overlay frame.
.UI_AUTO_SCROLL - Set automatic text scroll area; text will be scrolled up when printing more lines than the overlay height.

.MENUITEM

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

VM_CHOICE

VM_CHOICE IDX, OPTIONS, COUNT

Executes menu.

IDX: Variable that receives the result of the menu execution.
OPTIONS: Bit field, set of the possible menu options:
.UI_MENU_STANDARD - Default menu behavior.
.UI_MENU_LAST_0 - Last item returns result of 0
.UI_MENU_CANCEL_B - B button cancels the menu execution.
.UI_MENU_SET_START - If set IDX may contain the initial item index.
COUNT: Number of menu items.

Instruction must be followed by the COUNT of .MENUITEM definitions:
.MENUITEM X, Y, iL, iR, iU, iD
where:
X - X-coordinate of the cursor pointer in tiles.
Y - Y-coordinate of the cursor pointer in tiles.
iL - Menu item number where the cursor must move when you press LEFT.
iR - Menu item number where the cursor must move when you press RIGHT.
iU - Menu item number where the cursor must move when you press UP.
iD - Menu item number where the cursor must move when you press DOWN.

VM_SET_FONT

VM_SET_FONT FONT_INDEX

Sets active font.

FONT_INDEX: The index of the font to be activated.

VM_SET_PRINT_DIR

VM_SET_PRINT_DIR DIRECTION

Sets print direction.

DIRECTION: Direction of the text rendering:
.UI_PRINT_LEFTTORIGHT - Text is rendered from left to right (left justify).
.UI_PRINT_RIGHTTOLEFT - Text is rendered from right to left (right justify).

VM_OVERLAY_SET_SUBMAP_EX

VM_OVERLAY_SET_SUBMAP_EX PARAMS_IDX

Copies rectangular area of the background map onto the overlay window.

PARAMS_IDX: Points to the beginning of the pseudo-structure that contains these members:
x - X-coordinate within the overlay window in tiles.
y - Y-coordinate within the overlay window in tiles.
w - Width of the copied area in tiles.
h - Height of the copied area in tiles.
scene_x - X-Coordinate within the background map in tiles.
scene_y - Y-Coordinate within the background map in tiles.

VM_OVERLAY_SCROLL

VM_OVERLAY_SCROLL X, Y, W, H, COLOR

Scrolls a rectangular area of the overlay window.

X: X-coordinate of the upper left corner in tiles.
Y: Y-coordinate of the upper left corner in tiles.
W: Width of the area in tiles.
H: Height of the area in tiles.
COLOR: Color of the empty row of tiles that appear at the bottom of the scroll area.

VM_OVERLAY_SET_SCROLL

VM_OVERLAY_SET_SCROLL X, Y, W, H, COLOR

Defines the scroll area for the overlay. When the text overflows that area, it scrolls up by 1 row.

X: X-coordinate of the upper left corner in tiles.
Y: Y-coordinate of the upper left corner in tiles.
W: Width of the area in tiles.
H: Height of the area in tiles.
COLOR: Color of the empty row of tiles that appear at the bottom of the scroll area.

VM_OVERLAY_SET_SUBMAP

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

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

X: X-coordinate within the overlay window of the upper left corner in tiles.
Y: Y-coordinate within the overlay window of the upper left corner in tiles.
W: Width of the area in tiles.
H: Height of the area in tiles.
SX: X-coordinate within the level background map.
SY: Y-coordinate within the level background map.

GBVM Operations

Core​

VM_STOP​

VM_PUSH_CONST​

VM_POP​

VM_CALL​

VM_RET​

VM_RET_N​

VM_GET_FAR​

VM_LOOP​

.CASE​

VM_SWITCH​

VM_JUMP​

VM_CALL_FAR​

VM_RET_FAR​

VM_RET_FAR_N​

VM_INVOKE​

VM_BEGINTHREAD​

VM_IF​

VM_PUSH_VALUE_IND​

VM_PUSH_VALUE​

VM_RESERVE​

VM_SET​

VM_SET_CONST​

VM_RPN​

.R_INT8​

.R_INT16​

.R_REF​

.R_REF_IND​

.R_REF_SET​

.R_REF_SET_IND​

.R_REF_MEM​

.R_REF_MEM_SET​

.R_OPERATOR​

.R_STOP​

VM_JOIN​

VM_TERMINATE​

VM_IDLE​

VM_GET_TLOCAL​

VM_IF_CONST​

VM_GET_UINT8​

VM_GET_INT8​

VM_GET_INT16​

VM_SET_UINT8​

VM_SET_INT8​

VM_SET_INT16​

VM_SET_CONST_INT8​

VM_SET_CONST_UINT8​

VM_SET_CONST_INT16​

VM_INIT_RNG​

VM_RANDOMIZE​

VM_RAND​

VM_LOCK​

VM_UNLOCK​

VM_RAISE​

VM_SET_INDIRECT​

VM_GET_INDIRECT​

VM_TEST_TERMINATE​

VM_POLL_LOADED​

VM_PUSH_REFERENCE​

VM_CALL_NATIVE​

VM_MEMSET​

VM_MEMCPY​

Actor​

VM_ACTOR_MOVE_TO​

VM_ACTOR_MOVE_CANCEL​

VM_ACTOR_ACTIVATE​

VM_ACTOR_SET_DIR​

VM_ACTOR_DEACTIVATE​

VM_ACTOR_SET_ANIM​

VM_ACTOR_SET_POS​

VM_ACTOR_EMOTE​

VM_ACTOR_SET_BOUNDS​

VM_ACTOR_SET_SPRITESHEET​

VM_ACTOR_SET_SPRITESHEET_BY_REF​

VM_ACTOR_REPLACE_TILE​

VM_ACTOR_GET_POS​

VM_ACTOR_GET_DIR​

VM_ACTOR_GET_ANGLE​

VM_ACTOR_SET_ANIM_TICK​