mvbg

VM_IF_CONST

VM_IF_CONST is a GBVM instruction used for conditional branching based on the comparison of a variable with a constant value. It allows your script to make decisions and execute different blocks of code depending on whether a specific condition is met.

Purpose: Conditional logic is fundamental to any interactive program or game. VM_IF_CONST is essential for:

• Controlling game flow: Deciding whether to open a door, trigger an event, or advance to the next stage based on player stats, item counts, or game flags.
• Implementing choices: Responding differently to player input or choices.
• Validating conditions: Checking if a variable has reached a certain threshold or if a specific state is active.

Syntax:

VM_IF_CONST CONDITION, IDXA, B, LABEL, N

• CONDITION: Specifies the type of comparison to perform. Common conditions include:
  • .EQ (Equal to)
  • .LT (Less than)
  • .LTE (Less than or equal to)
  • .GT (Greater than)
  • .GTE (Greater than or equal to)
  • .NE (Not equal to)
• IDXA: The variable whose value will be compared.
• B: The immediate constant value to compare against IDXA.
• LABEL: The label (address) to jump to if the CONDITION evaluates to TRUE.
• N: The number of values to be removed from the stack after evaluating the condition. This is important for stack management, especially if VM_IF_CONST is used within an RPN context or after pushing values onto the stack.

Usage Example: Checking Player Health for Game Over

Imagine your game has a VAR_PLAYER_HEALTH variable. You want to check if the player’s health has dropped to 0 or below, triggering a GAME_OVER_SCREEN routine.

; In your main game loop or damage routine:

; Assume VAR_PLAYER_HEALTH is a 16-bit integer variable
VAR_PLAYER_HEALTH:
  .R_INT16 100 ; Initial health

; ... code that might reduce player health ...

; Check if player health is less than or equal to 0
VM_IF_CONST .LTE, VAR_PLAYER_HEALTH, 0, GAME_OVER_SCREEN, 0
; If VAR_PLAYER_HEALTH <= 0, jump to GAME_OVER_SCREEN.
; N is 0 as we are not removing anything from the stack in this context.

; ... continue normal game loop if player is still alive ...

; --- Game Over Routine ---
GAME_OVER_SCREEN:
  VM_FADE_OUT 1 ; Fade screen to black
  VM_LOAD_TEXT GAME_OVER_TEXT
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT ; Wait for player to press a button
  VM_SCENE_POP_ALL ; Return to title screen or main menu
  VM_STOP

GAME_OVER_TEXT:
  .TEXT "GAME OVER"
  .TEXT_END

In this example, VM_IF_CONST continuously checks the VAR_PLAYER_HEALTH. If it drops to 0 or below, the script immediately jumps to the GAME_OVER_SCREEN label, bypassing any further normal game loop logic. The N parameter is set to 0 because this VM_IF_CONST is not operating on values pushed onto the stack by preceding instructions that need to be cleaned up.

Analogy to other programming languages: This instruction is directly analogous to an if statement with a constant comparison in most programming languages:

• C/C++: if (playerHealth <= 0) { goToGameOverScreen(); }
• Python: if player_health <= 0: game_over_screen()

It provides the fundamental capability to control program flow based on simple, direct comparisons.