mvbg

VM_SET_UINT8

VM_SET_UINT8 is a GBVM instruction used to assign an unsigned 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_UINT8 is essential for updating 8-bit variables (which can range from 0 to 255) 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 item counts, flags, or small coordinates based on gameplay events, where values are always non-negative.
• Storing calculation results: Saving the outcome of small arithmetic operations into a persistent WRAM variable.
• Transferring data: Moving an 8-bit unsigned value from a temporary variable or the stack into a designated WRAM location.

Syntax:

VM_SET_UINT8 ADDR, IDXA

• ADDR: The address (label) in WRAM where the 8-bit unsigned 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 Item Quantity

Imagine your player collects an item, and its quantity is stored in WRAM_ITEM_COUNT. After the player picks up another of the same item, you need to update this WRAM variable with the new quantity, which is stored in VAR_NEW_ITEM_QUANTITY.

; In your script, after an item is collected:

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

; Assume VAR_NEW_ITEM_QUANTITY holds the updated quantity (e.g., 3)
VAR_NEW_ITEM_QUANTITY:
  .R_INT8 3

; Set the item quantity in WRAM
VM_SET_UINT8 WRAM_ITEM_COUNT, VAR_NEW_ITEM_QUANTITY

; Now, WRAM_ITEM_COUNT contains the value 3.
; This value can then be used for inventory display or checks.

; Example of using the quantity later:
VM_GET_UINT8 VAR_CURRENT_ITEM_COUNT, WRAM_ITEM_COUNT
VM_IF_CONST .GT, VAR_CURRENT_ITEM_COUNT, 0, DISPLAY_ITEM_COUNT, 0
; ...

DISPLAY_ITEM_COUNT:
  VM_LOAD_TEXT_VAR VAR_CURRENT_ITEM_COUNT
  VM_DISPLAY_TEXT
  VM_RET

In this example, VM_SET_UINT8 WRAM_ITEM_COUNT, VAR_NEW_ITEM_QUANTITY takes the value from VAR_NEW_ITEM_QUANTITY and writes it into the WRAM_ITEM_COUNT memory location. This allows for dynamic updates to game data based on in-game events, particularly for non-negative quantities.

Analogy to other programming languages: This is analogous to assigning the value of one variable to another variable of an unsigned byte or unsigned char type in C/C++: uint8_t item_count = new_quantity_value;

Or, more specifically, writing a variable’s value to a memory address: *(uint8_t*)WRAM_ITEM_COUNT_ADDRESS = new_quantity_value;

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