mvbg

VM_GET_INT16

VM_GET_INT16 is a GBVM instruction used to retrieve a signed 16-bit integer value from a specific memory address within Work RAM (WRAM) and store it into a GBVM variable.

Purpose: WRAM is the Game Boy’s primary read/write memory, used for storing dynamic game data such as player statistics, inventory, game state flags, temporary calculation results, and more. VM_GET_INT16 is essential for reading these 16-bit values (which can range from -32,768 to 32,767) from WRAM into a variable that your GBVM script can then use for logic, calculations, or display.

This instruction is crucial for:

• Loading dynamic game state: Retrieving current player health, score, or coordinates.
• Accessing shared data: Reading values from memory locations that might be updated by other parts of the game engine or native code.
• Processing calculation results: Fetching the outcome of a previous operation stored in WRAM.

Syntax:

VM_GET_INT16 IDXA, ADDR

• IDXA: The target variable (a GBVM variable) where the retrieved 16-bit signed integer will be stored.
• ADDR: The address (label) in WRAM from which the 16-bit signed integer value will be read.

Usage Example: Reading Player Score

Imagine your game keeps track of the player’s score, which can go into the thousands, requiring a 16-bit integer. This score is continuously updated and stored in a WRAM location. You want to read this score to display it on the screen or check if the player has reached a certain threshold.

; In your GBVM script:

; Variable to store the retrieved player score
VAR_CURRENT_SCORE:
  .R_INT16 0 ; Initialize to 0

; Assume WRAM_PLAYER_SCORE is a label pointing to a 16-bit location in WRAM
; where the game engine or other scripts update the player's score.

; Read the 16-bit signed integer from WRAM_PLAYER_SCORE into VAR_CURRENT_SCORE
VM_GET_INT16 VAR_CURRENT_SCORE, WRAM_PLAYER_SCORE

; Now VAR_CURRENT_SCORE holds the current player's score.
; You can then use it for display:
VM_LOAD_TEXT_VAR VAR_CURRENT_SCORE ; Load score into text buffer
VM_DISPLAY_TEXT                   ; Display the score

; Or for game logic:
VM_IF_CONST VAR_CURRENT_SCORE >= 1000
  VM_CALL LEVEL_UP_ROUTINE
VM_ENDIF

; Example of how WRAM_PLAYER_SCORE might be defined (conceptual, in WRAM section)
; SECTION "WRAM Data", WRAM
; WRAM_PLAYER_SCORE:
;   .WORD 0 ; Reserve 2 bytes for a 16-bit word

In this example, VM_GET_INT16 fetches the current score from WRAM_PLAYER_SCORE and places it into VAR_CURRENT_SCORE, making it accessible for further GBVM operations like displaying text or conditional checks.

Analogy to other programming languages: This is directly analogous to reading a variable from a specific memory address in C/C++: int16_t currentScore = *(int16_t*)WRAM_PLAYER_SCORE_ADDRESS;

Or, more simply, accessing a global variable that is known to be a 16-bit integer: int currentScore = global_player_score;

It’s about retrieving a numerical value of a specific size from a designated memory location.