mvbg

VM_SAVE_PEEK

VM_SAVE_PEEK is a GBVM instruction used to read a block of variables from a specified save slot without fully loading the entire game state.

Purpose: In games with save functionality, it’s often useful to display information about a save file (e.g., player name, current level, play time) on a load game screen without actually loading the entire game. VM_SAVE_PEEK allows you to “peek” into a save slot and retrieve specific pieces of data. It is essential for:

Displaying save file summaries: Showing details about each save slot in a load game menu, helping the player choose which save to load.
Checking save file integrity: Verifying if a save slot contains valid data before attempting a full load.
Conditional game logic: Making decisions based on data within a save file without committing to loading it (e.g., enabling a “Continue” option only if a save exists).

When VM_SAVE_PEEK is called, it copies COUNT number of variables from the specified SLOT (starting from SOUR within that slot’s data structure) into the DEST variables in your game’s active memory. It also provides a RES (result) indicating success or failure.

Syntax:

VM_SAVE_PEEK RES, DEST, SOUR, COUNT, SLOT

RES: A target variable that will receive the result of the operation:
- 0: Data read successfully.
- Non-zero value: An error occurred (e.g., save slot empty, corrupted data).
DEST: The first destination variable (a GBVM variable) in your game’s active memory where the read data will be stored. This is the starting point for the copied data.
SOUR: The first source variable (a GBVM variable) within the save slot’s data structure from where the data will be read. This is typically a label pointing to a specific variable within your .SAVE_SLOT definition.
COUNT: The number of variables to be read. This specifies how many contiguous variables, starting from SOUR in the save slot, will be copied to DEST.
SLOT: The save slot number (an integer) from which to read the data. This corresponds to the slot numbers defined using .SAVE_SLOT.

Usage Example: Displaying Player Level on Load Game Screen

Imagine your save data includes the player’s current level (VAR_PLAYER_LEVEL_SAVE). You want to display this level next to each save slot in your load game menu.

; In your save data definition (e.g., save_data.s):

SAVE_DATA_SLOT_0:
  .SAVE_SLOT 0
  VAR_PLAYER_LEVEL_SAVE_0:
    .R_INT8 0 ; Player Level for Slot 0
  VAR_PLAYER_NAME_SAVE_0:
    .TEXT "EMPTY"
    .TEXT_END
  ; ... other save data variables ...

; In your load game menu script:

; Variables to store peeked data
VAR_PEEK_RESULT:
  .R_INT8 0
VAR_PEEKED_PLAYER_LEVEL:
  .R_INT8 0

; Loop through each save slot to display its info
DISPLAY_SAVE_SLOT_INFO:
  ; Assume VAR_CURRENT_SLOT_NUM holds the current slot number (0, 1, 2...)

  ; Attempt to peek the player level from the current slot
  VM_SAVE_PEEK VAR_PEEK_RESULT, VAR_PEEKED_PLAYER_LEVEL, VAR_PLAYER_LEVEL_SAVE_0, 1, VAR_CURRENT_SLOT_NUM
  ; RES: VAR_PEEK_RESULT
  ; DEST: VAR_PEEKED_PLAYER_LEVEL (where the level will be stored)
  ; SOUR: VAR_PLAYER_LEVEL_SAVE_0 (the *label* of the level variable within the save slot's structure)
  ; COUNT: 1 (read only one variable)
  ; SLOT: VAR_CURRENT_SLOT_NUM (which save slot to peek)

  ; Check if peek was successful
  VM_IF_CONST .EQ, VAR_PEEK_RESULT, 0, PEEK_SUCCESS, 0
    ; If not successful (e.g., slot is empty), display "Empty"
    VM_LOAD_TEXT TEXT_SLOT_EMPTY
    VM_DISPLAY_TEXT
    VM_JUMP NEXT_SLOT

PEEK_SUCCESS:
  ; Display the peeked player level
  VM_LOAD_TEXT TEXT_SLOT_LEVEL_PREFIX
  VM_DISPLAY_TEXT
  VM_LOAD_TEXT_VAR VAR_PEEKED_PLAYER_LEVEL
  VM_DISPLAY_TEXT

NEXT_SLOT:
  ; ... logic to move to next slot or end loop ...
  VM_RET

TEXT_SLOT_EMPTY:
  .TEXT "Empty Slot"
  .TEXT_END

TEXT_SLOT_LEVEL_PREFIX:
  .TEXT "Level: "
  .TEXT_END

In this example, VM_SAVE_PEEK is used to read the VAR_PLAYER_LEVEL_SAVE_0 variable from the currently iterated save slot into VAR_PEEKED_PLAYER_LEVEL. If the peek is successful, the player’s level is displayed. If not, “Empty Slot” is shown. This allows the game to present a summary of each save file to the player without fully loading them.

Important Note on SOUR: The SOUR parameter (VAR_PLAYER_LEVEL_SAVE_0 in the example) refers to the label of the variable within the save slot’s data structure, not its value. The GBVM uses this label to calculate the offset within the save slot’s data to read from.

Analogy to Game Boy Development: This is a direct interface with the Game Boy’s save memory. In modern programming, it’s analogous to reading metadata or specific fields from a file header or a database record without loading the entire file or record into memory. It’s a way to efficiently inspect persistent data to provide information or make decisions without incurring the overhead of a full load operation.