mvbg

VM_SET_CONST_INT8

VM_SET_CONST_INT8 is a GBVM instruction used to set a signed 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_INT8 is essential for directly initializing or updating 8-bit variables (which can range from -128 to 127) in WRAM with a fixed numerical value. This is commonly used for:

Initializing game state: Setting initial flags, counters, 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 8-bit range.

Syntax:

VM_SET_CONST_INT8 ADDR, VAL

ADDR: The address (label) in WRAM where the 8-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: Setting a Game State Flag

Imagine you have a game state flag WRAM_GAME_STATE_FLAG that indicates whether a tutorial has been completed (e.g., 0 for incomplete, 1 for complete). When the player finishes the tutorial, you would use VM_SET_CONST_INT8 to update this flag.

; In your tutorial completion script:

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

; When the tutorial is finished:
VM_SET_CONST_INT8 WRAM_GAME_STATE_FLAG, 1

; Now, the memory location WRAM_GAME_STATE_FLAG contains the value 1.
; You can later check this flag to prevent the tutorial from replaying.

; Example of checking the flag later:
VM_GET_INT8 VAR_TUTORIAL_COMPLETE, WRAM_GAME_STATE_FLAG
VM_IF_CONST .EQ, VAR_TUTORIAL_COMPLETE, 1, SKIP_TUTORIAL, 0
; ...

SKIP_TUTORIAL:
  VM_LOAD_TEXT TEXT_TUTORIAL_DONE
  VM_DISPLAY_TEXT
  VM_RET

TEXT_TUTORIAL_DONE:
  .TEXT "Tutorial already completed!"
  .TEXT_END

In this example, VM_SET_CONST_INT8 WRAM_GAME_STATE_FLAG, 1 directly writes the constant value 1 into the WRAM_GAME_STATE_FLAG memory location. This is a straightforward way to assign fixed numerical data to your game’s dynamic variables, especially for flags or small counters.

Analogy to other programming languages: This is analogous to directly assigning a literal integer value to a variable of a byte or char type in C/C++: int8_t tutorialComplete = 1;

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