mvbg

VM_SET_CONST_UINT8

VM_SET_CONST_UINT8 is a GBVM instruction used to set an unsigned 8-bit integer value at a specific memory address within Work RAM (WRAM) to an immediate (constant) value.

Purpose: WRAM is the Game Boy’s primary read/write memory, used for storing dynamic game data. VM_SET_CONST_UINT8 is essential for directly initializing or updating 8-bit variables (which can range from 0 to 255) in WRAM with a fixed non-negative numerical value. This is commonly used for:

Initializing game state: Setting initial counts of items, flags, or small coordinates when a game starts or a new event occurs.
Resetting variables: Returning a variable to a default constant value after an event.
Setting fixed parameters: Storing configuration values that are known at compile time into WRAM for runtime access, especially for values that fit within the unsigned 8-bit range.

Syntax:

VM_SET_CONST_UINT8 ADDR, VAL

ADDR: The address (label) in WRAM where the 8-bit unsigned integer value will be stored.
VAL: The immediate constant value (a literal non-negative number) that will be written to the specified WRAM address.

Usage Example: Setting Initial Item Quantity

Imagine your player starts with 5 potions. This quantity is stored in a WRAM variable WRAM_POTION_COUNT. You would use VM_SET_CONST_UINT8 to set this initial value.

; In your game initialization script:

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

; Set the player's initial potion count to 5
VM_SET_CONST_UINT8 WRAM_POTION_COUNT, 5

; Now, the memory location WRAM_POTION_COUNT contains the value 5.
; You can later retrieve this value using VM_GET_UINT8 or modify it.

; Example of checking the potion count later:
VM_GET_UINT8 VAR_CURRENT_POTIONS, WRAM_POTION_COUNT
VM_IF_CONST .GT, VAR_CURRENT_POTIONS, 0, USE_POTION, 0
; ...

USE_POTION:
  VM_LOAD_TEXT TEXT_USED_POTION
  VM_DISPLAY_TEXT
  ; ... logic to decrement potion count ...
  VM_RET

TEXT_USED_POTION:
  .TEXT "Used a potion!"
  .TEXT_END

In this example, VM_SET_CONST_UINT8 WRAM_POTION_COUNT, 5 directly writes the constant value 5 into the WRAM_POTION_COUNT memory location. This is a straightforward way to assign fixed non-negative numerical data to your game’s dynamic variables, especially for quantities or flags.

Analogy to other programming languages: This is analogous to directly assigning a literal unsigned integer value to a variable of a byte or unsigned char type in C/C++: uint8_t potionCount = 5;

Or, in assembly language, using a MOV or LD instruction with an immediate value to store data in a memory location. It’s the most direct way to put a known, fixed, small non-negative number into a specific memory address.