mvbg

VM_IF

VM_IF is a GBVM instruction used for conditional branching based on the comparison of two variables. It allows your script to make decisions and execute different blocks of code depending on whether a specific condition between two dynamic values is met.

Purpose: While VM_IF_CONST compares a variable to a fixed value, VM_IF is used when both sides of the comparison are dynamic variables. This is essential for:

• Dynamic game logic: Comparing player stats to enemy stats, checking if two actors are at the same coordinates, or comparing the values of two different game flags.
• Complex decision-making: Implementing branching narratives or gameplay paths that depend on multiple changing factors.
• Inter-variable relationships: Evaluating relationships between different game elements that are represented by variables.

Syntax:

VM_IF CONDITION, IDXA, IDXB, 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 first variable whose value will be compared.
• IDXB: The second variable whose value will be compared 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 is used within an RPN context or after pushing values onto the stack.

Usage Example: Player vs. Enemy Attack Comparison

Imagine a simple combat system where the outcome of an attack depends on comparing the player’s attack stat (VAR_PLAYER_ATTACK) with an enemy’s defense stat (VAR_ENEMY_DEFENSE). If the player’s attack is greater than the enemy’s defense, the attack hits.

; In your combat script:

; Assume VAR_PLAYER_ATTACK and VAR_ENEMY_DEFENSE are 8-bit integer variables
VAR_PLAYER_ATTACK:
  .R_INT8 10
VAR_ENEMY_DEFENSE:
  .R_INT8 8

; ... code that might modify these variables ...

; Check if player attack is greater than enemy defense
VM_IF .GT, VAR_PLAYER_ATTACK, VAR_ENEMY_DEFENSE, ATTACK_HITS, 0
; If VAR_PLAYER_ATTACK > VAR_ENEMY_DEFENSE, jump to ATTACK_HITS.
; N is 0 as we are not removing anything from the stack in this context.

; If the condition is FALSE (attack did not hit), execute this block:
ATTACK_MISSES:
  VM_LOAD_TEXT TEXT_ATTACK_MISS
  VM_DISPLAY_TEXT
  VM_JUMP END_COMBAT_TURN ; Skip the hit logic

; If the condition is TRUE (attack hits), execute this block:
ATTACK_HITS:
  VM_LOAD_TEXT TEXT_ATTACK_HIT
  VM_DISPLAY_TEXT
  ; ... calculate damage, apply to enemy health, etc. ...

END_COMBAT_TURN:
  ; ... continue combat turn logic ...

TEXT_ATTACK_MISS:
  .TEXT "Your attack missed!"
  .TEXT_END

TEXT_ATTACK_HIT:
  .TEXT "You hit the enemy!"
  .TEXT_END

In this example, VM_IF compares the values of VAR_PLAYER_ATTACK and VAR_ENEMY_DEFENSE. Based on the result, the script either jumps to ATTACK_HITS or proceeds to ATTACK_MISSES. This allows for dynamic and interactive combat outcomes.

Analogy to other programming languages: This instruction is directly analogous to an if statement comparing two variables in most programming languages:

• C/C++: if (playerAttack > enemyDefense) { handleHit(); } else { handleMiss(); }
• Python: if player_attack > enemy_defense: handle_hit() else: handle_miss()

It provides the fundamental capability to control program flow based on comparisons between dynamic data.