mvbg

VM_POLL_LOADED

VM_POLL_LOADED is a GBVM instruction used to check if the VM’s state has been restored (e.g., after loading a save game) and to reset the internal restore flag.

Purpose: In games, the ability to save and load progress is crucial. When a game state is loaded, the GBVM needs a mechanism to confirm that all necessary data has been re-initialized and that the system is ready to resume gameplay. VM_POLL_LOADED serves this purpose:

• Confirmation of state restoration: It allows your script to determine if a load operation has just completed.
• Resetting the flag: After confirming the load, it clears an internal flag, preventing the same “loaded” state from being detected repeatedly.
• Triggering post-load logic: It can be used to trigger specific routines that should only run immediately after a game state has been loaded (e.g., re-enabling UI elements, re-positioning actors, playing a “game loaded” sound).

Syntax:

VM_POLL_LOADED IDX

• IDX: The target result variable. This variable will be set to a non-zero value (e.g., 1) if the VM state was just restored, and 0 otherwise. After the check, the internal restore flag is reset.

Usage Example: Handling Game Load Events

Imagine your game has a main loop, and you want to perform certain actions only when a game has just been loaded from a save file. This might include displaying a confirmation message or re-initializing certain dynamic elements that aren’t directly part of the saved state.

; In your main game loop or a dedicated game state manager:

; Variable to store the result of the poll
VAR_GAME_LOADED_FLAG:
  .R_INT8 0 ; Initialize to 0

GAME_MAIN_LOOP:
  ; ... regular game loop logic (input, updates, rendering) ...

  ; Check if the game state was just loaded
  VM_POLL_LOADED VAR_GAME_LOADED_FLAG

  VM_IF_CONST .NE, VAR_GAME_LOADED_FLAG, 0, HANDLE_GAME_LOADED, 0
  ; If VAR_GAME_LOADED_FLAG is not 0 (i.e., it was just loaded), jump to HANDLE_GAME_LOADED

  ; ... continue normal game loop if not loaded ...

  VM_JUMP GAME_MAIN_LOOP

; --- Routine to handle post-load events ---
HANDLE_GAME_LOADED:
  VM_LOAD_TEXT TEXT_GAME_LOADED
  VM_DISPLAY_TEXT
  VM_IDLE 60 ; Display message for a second
  VM_OVERLAY_HIDE ; Hide any loading overlays
  ; ... other post-load initialization (e.g., re-enabling player control) ...

  VM_JUMP GAME_MAIN_LOOP ; Return to the main loop

TEXT_GAME_LOADED:
  .TEXT "Game Loaded!"
  .TEXT_END

In this example, VM_POLL_LOADED is called periodically. If a save game has just been loaded, VAR_GAME_LOADED_FLAG will be set to 1, triggering a jump to HANDLE_GAME_LOADED. This routine displays a message and performs any necessary post-load setup. Crucially, VM_POLL_LOADED also resets the internal flag, so HANDLE_GAME_LOADED is only triggered once per load operation.

Analogy to other programming languages: This is similar to checking a boolean flag or an event trigger in a game engine or application framework. For example, in a Unity game, you might have an OnSceneLoaded event that fires once after a new scene is loaded. VM_POLL_LOADED provides a similar one-shot notification mechanism for the GBVM’s state restoration.