mvbg

VM_GET_UINT8

VM_GET_UINT8 is a GBVM instruction used to retrieve an unsigned 8-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. VM_GET_UINT8 is essential for reading these 8-bit values (which can range from 0 to 255) from WRAM into a variable that your GBVM script can then use for logic, calculations, or display. This is particularly useful for values that are always non-negative, such as quantities, flags, or small coordinates, saving memory compared to using 16-bit integers.

This instruction is crucial for:

Loading dynamic game state: Retrieving current item counts, collected power-ups, or map tile IDs.
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_UINT8 IDXA, ADDR

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

Usage Example: Reading Item Count

Imagine your game keeps track of how many keys the player has collected, which will always be a non-negative number. This count is stored in an 8-bit WRAM location. You want to read this count to check if the player has enough keys to open a door.

; In your GBVM script:

; Variable to store the retrieved key count
VAR_KEY_COUNT:
  .R_INT8 0 ; Initialize to 0

; Assume WRAM_PLAYER_KEYS is a label pointing to an 8-bit location in WRAM
; where the game engine or other scripts update the player's key count.

; Read the 8-bit unsigned integer from WRAM_PLAYER_KEYS into VAR_KEY_COUNT
VM_GET_UINT8 VAR_KEY_COUNT, WRAM_PLAYER_KEYS

; Now VAR_KEY_COUNT holds the current number of keys.
; You can then use it for conditional logic:
VM_IF_CONST VAR_KEY_COUNT >= 3 ; If player has 3 or more keys
  VM_CALL OPEN_DOOR_ROUTINE
VM_ENDIF

; Example of how WRAM_PLAYER_KEYS might be defined (conceptual, in WRAM section)
; SECTION "WRAM Data", WRAM
; WRAM_PLAYER_KEYS:
;   .BYTE 0 ; Reserve 1 byte for an 8-bit byte

In this example, VM_GET_UINT8 fetches the current key count from WRAM_PLAYER_KEYS and places it into VAR_KEY_COUNT, making it accessible for further GBVM operations like conditional checks.

Analogy to other programming languages: This is directly analogous to reading an unsigned byte or unsigned char type variable from a specific memory address in C/C++: uint8_t currentKeys = *(uint8_t*)WRAM_PLAYER_KEYS_ADDRESS;

Or, more simply, accessing a global variable that is known to be an unsigned 8-bit integer: unsigned int currentKeys = global_player_keys;

It’s about retrieving a non-negative numerical value of a specific, smaller size from a designated memory location.