mvbg

VM_RAISE

VM_RAISE is a GBVM instruction used to trigger a system-level event or “exception”, allowing your script to initiate core game engine functionalities like changing scenes, saving, or loading the game.

Purpose: Unlike typical function calls that return control to the caller, VM_RAISE signals a significant event to the GBVM’s underlying system. This is how you tell the game engine to perform actions that fundamentally alter the game’s state or flow, such as:

• Scene Transitions: Moving from one game area to another (e.g., from a town to a dungeon).
• Game State Management: Initiating a save or load operation for the player’s progress.
• System Reset: Returning the game to its initial state.

When VM_RAISE is executed, the GBVM typically stops the current script’s execution and hands control over to a dedicated exception handler that processes the requested system event.

Syntax:

VM_RAISE CODE, SIZE

• CODE: The exception code that specifies the type of system event to trigger. Common codes include:
  • EXCEPTION_RESET: Resets the entire Game Boy device or game.
  • EXCEPTION_CHANGE_SCENE: Initiates a scene change. Additional parameters (like the scene ID) are typically passed on the stack.
  • EXCEPTION_SAVE: Triggers the game’s save routine.
  • EXCEPTION_LOAD: Triggers the game’s load routine.
• SIZE: The length (in bytes or number of variables) of any parameters that need to be passed to the exception handler. These parameters must be pushed onto the stack before VM_RAISE is called.

Usage Example: Changing Game Scenes

Imagine your player character walks onto an exit tile, and you want to transition them to a new game scene (e.g., from the TOWN scene to the FOREST scene). You would use VM_RAISE with EXCEPTION_CHANGE_SCENE.

; In your script, when the player enters an exit zone:

; Assume SCENE_FOREST_ID is a constant representing the ID of the Forest scene
SCENE_FOREST_ID:
  .R_INT8 1 ; Example: Forest scene ID is 1

; Push the scene ID onto the stack as a parameter for the exception handler
VM_PUSH_CONST SCENE_FOREST_ID

; Raise the EXCEPTION_CHANGE_SCENE event
VM_RAISE EXCEPTION_CHANGE_SCENE, 1
; EXCEPTION_CHANGE_SCENE: The type of event.
; 1: The size of the parameter (1 value, the scene ID) on the stack.

; Any code after VM_RAISE will typically not be executed as control is transferred.

; --- Conceptual Exception Handler (handled by the GBVM engine) ---
; When EXCEPTION_CHANGE_SCENE is raised, the engine's internal handler would:
; 1. Pop the scene ID (1) from the stack.
; 2. Load the assets for the Forest scene.
; 3. Initialize the new scene.
; 4. Start execution of the new scene's script.

In this example, VM_PUSH_CONST SCENE_FOREST_ID places the target scene’s identifier onto the stack. VM_RAISE EXCEPTION_CHANGE_SCENE, 1 then signals to the GBVM that a scene change is requested, and the parameter on the stack should be used to determine which scene to load. The current script’s execution effectively ends as the game transitions.

Analogy to other programming languages: This is analogous to throwing an exception in languages like Java or Python, or making a system call in a low-level operating system. You are not just calling a function; you are triggering a higher-level, often non-local, change in the program’s state or execution environment. It’s a way to break out of the normal flow to handle significant events.