mvbg

VM_SET_CONST_INT16

VM_SET_CONST_INT16 is a GBVM instruction used to set a signed 16-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_INT16 is essential for directly initializing or updating 16-bit variables (which can range from -32,768 to 32,767) in WRAM with a fixed numerical value. This is commonly used for:

Initializing game state: Setting initial scores, health, or coordinates when a game starts or a new level loads.
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.

Syntax:

VM_SET_CONST_INT16 ADDR, VAL

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

Usage Example: Initializing Player Health

Imagine your game starts with the player having 100 health points, and this value is stored in a WRAM variable WRAM_PLAYER_HEALTH. You would use VM_SET_CONST_INT16 to set this initial value.

; In your game initialization script:

; Assume WRAM_PLAYER_HEALTH is a label pointing to a 16-bit location in WRAM
; SECTION "WRAM Data", WRAM
; WRAM_PLAYER_HEALTH:
;   .WORD 0 ; Reserve 2 bytes for a 16-bit word

; Set the player's initial health to 100
VM_SET_CONST_INT16 WRAM_PLAYER_HEALTH, 100

; Now, the memory location WRAM_PLAYER_HEALTH contains the value 100.
; You can later retrieve this value using VM_GET_INT16 or modify it.

; Example of checking the health later:
VM_GET_INT16 VAR_CURRENT_HEALTH, WRAM_PLAYER_HEALTH
VM_IF_CONST .EQ, VAR_CURRENT_HEALTH, 100, HEALTH_FULL, 0
; ...

HEALTH_FULL:
  VM_LOAD_TEXT TEXT_HEALTH_FULL
  VM_DISPLAY_TEXT
  VM_RET

TEXT_HEALTH_FULL:
  .TEXT "Health is full!"
  .TEXT_END

In this example, VM_SET_CONST_INT16 WRAM_PLAYER_HEALTH, 100 directly writes the constant value 100 into the WRAM_PLAYER_HEALTH memory location. This is a straightforward way to assign fixed numerical data to your game’s dynamic variables.

Analogy to other programming languages: This is analogous to directly assigning a literal integer value to a variable in C/C++: int16_t playerHealth = 100;

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 number into a specific memory address.