mvbg

VM_PUSH_VALUE_IND

VM_PUSH_VALUE_IND is a GBVM instruction used to push the value of a variable onto the VM stack, where the target variable is identified indirectly by an index stored in another variable.

Purpose: This instruction is particularly useful for dynamic access to variables, especially when implementing array-like structures or when the specific variable to be accessed is determined at runtime. It allows you to:

• Dynamically access array elements: If you have a series of variables acting as an array (e.g., ITEM_0, ITEM_1, ITEM_2), and you want to push the value of ITEM_N where N is stored in another variable.
• Flexible data retrieval: When the data you need to operate on depends on a calculated or stored index, VM_PUSH_VALUE_IND provides the means to retrieve that data and place it on the stack for further processing.

Syntax:

VM_PUSH_VALUE_IND IDX

• IDX: The variable that contains the index (or offset) of the variable whose value you want to push onto the stack. The GBVM interprets this index relative to its internal global variable table.

Usage Example: Pushing an Item ID from an Inventory Slot

Consider an inventory system where VAR_INVENTORY_SLOT_0, VAR_INVENTORY_SLOT_1, etc., represent inventory slots, each holding an item ID. You have a variable VAR_SELECTED_SLOT that stores the index of the currently selected inventory slot. You want to push the item ID from the VAR_SELECTED_SLOT onto the stack to check its properties.

; In your script:

; Inventory slot variables (conceptual, assumed to be contiguous)
VAR_INVENTORY_SLOT_0:
  .R_INT8 0  ; Empty
VAR_INVENTORY_SLOT_1:
  .R_INT8 10 ; Sword ID
VAR_INVENTORY_SLOT_2:
  .R_INT8 25 ; Potion ID

; Variable to hold the currently selected slot index
VAR_SELECTED_SLOT:
  .R_INT8 1 ; Select slot 1 (Sword)

; Push the value of the variable pointed to by VAR_SELECTED_SLOT onto the stack
VM_PUSH_VALUE_IND VAR_SELECTED_SLOT

; At this point, the value '10' (Sword ID) is on top of the stack.
; You can now use this value in RPN or other operations.
VM_RPN
  .R_INT8 5 ; Push a constant for comparison
  .R_OPERATOR > ; Check if item ID > 5
  .R_INT8
VM_STOP

; The result of the comparison (TRUE/FALSE) is now on the stack.
; ... continue script based on the item ID ...

; Change selected slot to 2 (Potion)
VM_SET_INT8 VAR_SELECTED_SLOT, 2

; Push the value of the variable pointed to by VAR_SELECTED_SLOT onto the stack
VM_PUSH_VALUE_IND VAR_SELECTED_SLOT
; Now the value '25' (Potion ID) is on top of the stack.

In this example, VM_PUSH_VALUE_IND VAR_SELECTED_SLOT dynamically retrieves the value from either VAR_INVENTORY_SLOT_1 or VAR_INVENTORY_SLOT_2 based on the current value of VAR_SELECTED_SLOT, and places that item ID onto the stack. This allows for flexible and data-driven inventory management.

Analogy to other programming languages: This is analogous to accessing an element of an array using a variable as the index:

• C/C++: int item_id = inventory_array[selected_slot];
• Python: item_id = inventory_list[selected_slot]

It provides a way to get the content of a variable whose identity is itself stored in another variable, enabling powerful indirect addressing capabilities.