mvbg

VM_SET_INT8

VM_SET_INT8 is a GBVM instruction used to assign a signed 8-bit integer value from a GBVM variable to a specific memory address within Work RAM (WRAM).

Purpose: WRAM is the Game Boy’s primary read/write memory, used for storing dynamic game data. VM_SET_INT8 is essential for updating 8-bit variables (which can range from -128 to 127) in WRAM with values that might have been calculated, retrieved from other sources, or modified during script execution. This is commonly used for:

• Updating dynamic game state: Modifying character direction, item counts, or status effects based on gameplay events.
• Storing calculation results: Saving the outcome of small arithmetic operations into a persistent WRAM variable.
• Transferring data: Moving an 8-bit value from a temporary variable or the stack into a designated WRAM location.

Syntax:

VM_SET_INT8 ADDR, IDXA

• ADDR: The address (label) in WRAM where the 8-bit signed integer value will be stored.
• IDXA: The source variable (a GBVM variable) whose current value will be written to the specified WRAM address.

Usage Example: Updating Player Direction

Imagine your player’s current facing direction is stored in WRAM_PLAYER_DIR. After the player moves or changes direction, you need to update this WRAM variable with the new direction, which is stored in VAR_NEW_DIRECTION.

; In your script, after player input or movement:

; Assume WRAM_PLAYER_DIR is a label pointing to an 8-bit location in WRAM
; SECTION "WRAM Data", WRAM
; WRAM_PLAYER_DIR:
;   .BYTE 0 ; Reserve 1 byte for an 8-bit byte (initially 0 for Up)

; Assume VAR_NEW_DIRECTION holds the new direction (e.g., 1 for Down)
VAR_NEW_DIRECTION:
  .R_INT8 1

; Set the player's direction in WRAM
VM_SET_INT8 WRAM_PLAYER_DIR, VAR_NEW_DIRECTION

; Now, WRAM_PLAYER_DIR contains the value 1 (Down).
; This value can then be used by the rendering engine to update the player's sprite.

; Example of using the direction later:
VM_GET_INT8 VAR_CURRENT_DIR, WRAM_PLAYER_DIR
VM_IF_CONST .EQ, VAR_CURRENT_DIR, 1, PLAYER_FACING_DOWN, 0
; ...

PLAYER_FACING_DOWN:
  VM_ACTOR_SET_ANIM PLAYER_ACTOR, ANIM_PLAYER_WALK_DOWN
  VM_RET

In this example, VM_SET_INT8 WRAM_PLAYER_DIR, VAR_NEW_DIRECTION takes the value from VAR_NEW_DIRECTION and writes it into the WRAM_PLAYER_DIR memory location. This allows for dynamic updates to game data based on in-game events, particularly for smaller, frequently changing values.

Analogy to other programming languages: This is analogous to assigning the value of one variable to another variable of a byte or char type in C/C++: int8_t player_direction = new_direction_value;

Or, more specifically, writing a variable’s value to a memory address: *(int8_t*)WRAM_PLAYER_DIR_ADDRESS = new_direction_value;

It’s about taking a dynamic value from a variable and storing it into a specific 8-bit memory location.