mvbg

VM_RET

VM_RET is a GBVM instruction used to return from a near call (a subroutine within the same memory bank).

Purpose: When a VM_CALL instruction is executed, the GBVM saves the return address on the stack and then jumps to the specified subroutine. VM_RET is the corresponding instruction that signals the end of that subroutine’s execution. It performs the following actions:

• Pops return address: It retrieves the saved return address from the stack.
• Transfers control: It then transfers execution back to the instruction immediately following the VM_CALL that initiated the jump.

This instruction is crucial for maintaining proper program flow within your GBVM scripts, allowing you to organize your code into modular and reusable subroutines.

Syntax:

VM_RET

VM_RET takes no arguments. It implicitly uses the return address stored on the stack by the preceding VM_CALL.

Usage Example: Simple Dialogue Display Function

Let’s consider a simple function DISPLAY_MESSAGE that takes a text variable and displays it on screen. After displaying the message, it should return control to the calling script.

; In your main script:

; Call the message display function
VM_CALL DISPLAY_MESSAGE

; After DISPLAY_MESSAGE returns, execution continues here.
; ... rest of main script logic ...

; --- Subroutine Definition ---
DISPLAY_MESSAGE:
  ; Assume VAR_CURRENT_MESSAGE is a variable holding the text to display
  VM_LOAD_TEXT VAR_CURRENT_MESSAGE
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT ; Wait for player input to dismiss message

  VM_RET ; Return from the subroutine

In this example, VM_CALL DISPLAY_MESSAGE transfers control to the DISPLAY_MESSAGE subroutine. After the message is displayed and player input is awaited, VM_RET is executed. This causes the GBVM to pop the return address from the stack and resume execution in the main script at the instruction immediately following the VM_CALL.

Important Note on Stack Cleanup: If the VM_CALL passed any arguments on the stack, you should use VM_RET_N instead of VM_RET to ensure those arguments are properly removed from the stack. VM_RET only handles the return address, not any passed arguments.

Analogy to other programming languages: This is directly analogous to a return; statement in a function in most programming languages (e.g., C/C++, Python, JavaScript) when the function does not return a value. It signifies the end of the function’s execution and transfers control back to the caller.