mvbg

VM_PUSH_VALUE

VM_PUSH_VALUE is a GBVM instruction used to push the current value of a specified variable onto the top of the VM stack.

Purpose: This instruction is a direct way to get the content of a variable onto the stack for immediate use in calculations, comparisons, or as an argument to another instruction. It is essential for:

• Using variable contents in RPN: When you need the actual numerical value of a variable within a VM_RPN block.
• Passing variable values as arguments: Providing the current state of a variable as an input to a subroutine or a C function invoked via VM_INVOKE.
• Temporary storage for operations: Placing a variable’s value on the stack for a short period while performing operations that consume stack values.

Unlike VM_PUSH_REFERENCE which pushes the address of a variable, VM_PUSH_VALUE pushes the data stored within the variable.

Syntax:

VM_PUSH_VALUE IDX

• IDX: The variable whose current value will be pushed onto the stack.

Usage Example: Calculating Total Score from Multiple Variables

Imagine your game tracks different types of scores (e.g., VAR_ENEMY_SCORE, VAR_COLLECTIBLE_SCORE). You want to calculate the total score and display it.

; In your script:

; Score variables
VAR_ENEMY_SCORE:
  .R_INT16 150
VAR_COLLECTIBLE_SCORE:
  .R_INT16 75
VAR_TOTAL_SCORE:
  .R_INT16 0 ; Variable to store the total

; Push the values of the score variables onto the stack
VM_PUSH_VALUE VAR_ENEMY_SCORE     ; Stack: [150]
VM_PUSH_VALUE VAR_COLLECTIBLE_SCORE ; Stack: [150, 75]

; Perform the addition using RPN
VM_RPN
  .R_OPERATOR + ; Add the two values (75 and 150) currently on the stack
  .R_INT16      ; Specify the result as a 16-bit integer
VM_STOP

; The result (225) is now on top of the stack.
; Store the result into VAR_TOTAL_SCORE
VM_SET_INT16 VAR_TOTAL_SCORE, 0 ; The 0 is a placeholder, value taken from stack

; Display the total score
VM_LOAD_TEXT_VAR VAR_TOTAL_SCORE
VM_DISPLAY_TEXT

; ... continue script ...

In this example:

1. VM_PUSH_VALUE VAR_ENEMY_SCORE places the value 150 onto the stack.
2. VM_PUSH_VALUE VAR_COLLECTIBLE_SCORE places the value 75 on top of 150.
3. The VM_RPN block then uses these values to calculate the sum.
4. VM_SET_INT16 VAR_TOTAL_SCORE, 0 takes the calculated sum (225) from the stack and stores it into VAR_TOTAL_SCORE.

Analogy to other programming languages: This is analogous to simply using a variable in an expression, where its current value is retrieved:

• C/C++: int totalScore = enemyScore + collectibleScore;
• Python: total_score = enemy_score + collectible_score

It’s the most common way to access and utilize the dynamic data stored in your GBVM variables within your scripts.