mvbg

VM_SAVE_CLEAR

VM_SAVE_CLEAR is a GBVM instruction used to erase all data within a specified save slot, effectively resetting it to an empty or default state.

Purpose: In games with save functionality, players often need the ability to delete old save files to free up space, restart a game from scratch, or simply manage their save data. VM_SAVE_CLEAR provides this functionality. It is essential for:

• Save data management: Allowing players to delete unwanted save files from within the game’s menu.
• New game initialization: Ensuring a truly fresh start by clearing a save slot before beginning a new game.
• Debugging/Testing: Quickly resetting save data during development.

When VM_SAVE_CLEAR is called, all game data associated with the specified SLOT is overwritten or marked as invalid, making it appear as if no game has been saved in that slot. This operation is typically irreversible.

Syntax:

VM_SAVE_CLEAR SLOT

• SLOT: The slot number (an integer) of the save slot to be cleared. This corresponds to the slot numbers defined using .SAVE_SLOT.

Usage Example: Implementing a “Delete Save” Option in a Menu

Imagine your game has a save/load menu where players can select a save slot and choose to delete it. You would use VM_SAVE_CLEAR when the player confirms the deletion.

; In your save/load menu script:

; Variable to hold the currently selected save slot
VAR_SELECTED_SAVE_SLOT:
  .R_INT8 0

; ... code for displaying save slots and handling player selection ...

PLAYER_SELECTS_DELETE_OPTION:
  ; Assume VAR_SELECTED_SAVE_SLOT holds the slot number to delete (e.g., 0, 1, or 2)

  VM_LOAD_TEXT TEXT_CONFIRM_DELETE
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT .INPUT_A ; Wait for A button to confirm deletion

  ; Clear the selected save slot
  VM_SAVE_CLEAR VAR_SELECTED_SAVE_SLOT

  VM_LOAD_TEXT TEXT_SAVE_DELETED
  VM_DISPLAY_TEXT
  VM_IDLE 60 ; Display message for a second

  ; Refresh the save slot display in the menu
  VM_CALL REFRESH_SAVE_MENU_DISPLAY

  VM_RET

TEXT_CONFIRM_DELETE:
  .TEXT "Delete this save? A=Yes B=No"
  .TEXT_END

TEXT_SAVE_DELETED:
  .TEXT "Save data deleted!"
  .TEXT_END

REFRESH_SAVE_MENU_DISPLAY:
  ; ... routine to re-read save slot status and update menu visuals ...
  VM_RET

In this example, after the player confirms their intention to delete a save, VM_SAVE_CLEAR VAR_SELECTED_SAVE_SLOT is called. This instruction erases the data in the chosen save slot. A confirmation message is then displayed, and the menu is refreshed to reflect the empty slot. This provides a clear and functional way for players to manage their game saves.

Analogy to Game Boy Development: This is a direct interface with the Game Boy’s save memory (typically battery-backed RAM or Flash memory). In modern programming, it’s analogous to deleting a file from disk, clearing a database entry, or resetting a user profile. It’s a destructive operation that removes persistent data, and as such, should usually be accompanied by a confirmation step to prevent accidental data loss.