mvbg

VM_ACTOR_GET_POS

VM_ACTOR_GET_POS is a GBVM instruction used to retrieve the current X and Y coordinates of a specified actor and store them into designated GBVM variables.

Purpose: An actor’s position is fundamental to almost all game logic. VM_ACTOR_GET_POS is essential for:

• Collision detection: Determining if two actors are overlapping or near each other.
• AI behavior: Allowing NPCs to navigate, patrol, or chase the player based on their own and other actors’ positions.
• Interaction checks: Identifying if the player is within range to interact with an object or another character.
• Camera tracking: Ensuring the camera follows the player or other important entities.
• UI updates: Displaying an actor’s coordinates for debugging or in-game information.

This instruction provides the precise location of an actor within the game world, enabling dynamic and responsive gameplay.

Syntax:

VM_ACTOR_GET_POS ACTOR_ID, VAR_X, VAR_Y

• ACTOR_ID: A variable that contains the actor number (ID) of the actor whose position you want to retrieve.
• VAR_X: The target variable (a GBVM variable) where the retrieved X-coordinate of the actor will be stored.
• VAR_Y: The target variable (a GBVM variable) where the retrieved Y-coordinate of the actor will be stored.

Usage Example: Checking if Player is Near an NPC

Imagine you have an NPC that only initiates dialogue when the player is within a certain proximity. You can use VM_ACTOR_GET_POS to get both the player’s and the NPC’s coordinates and then calculate the distance.

; In your NPC's interaction script or update loop:

; Assume NPC_VILLAGER_ID is the actor ID for the villager
NPC_VILLAGER_ID:
  .R_INT8 20 ; Example Actor ID

; Assume PLAYER_ACTOR_ID is the actor ID for the player
PLAYER_ACTOR_ID:
  .R_INT8 0 ; Example Actor ID

; Variables to store positions
VAR_NPC_X:
  .R_INT16 0
VAR_NPC_Y:
  .R_INT16 0
VAR_PLAYER_X:
  .R_INT16 0
VAR_PLAYER_Y:
  .R_INT16 0

; Get NPC's current position
VM_ACTOR_GET_POS NPC_VILLAGER_ID, VAR_NPC_X, VAR_NPC_Y

; Get player's current position
VM_ACTOR_GET_POS PLAYER_ACTOR_ID, VAR_PLAYER_X, VAR_PLAYER_Y

; Calculate absolute difference in X coordinates
VM_RPN
  .R_REF_MEM .R_INT16, VAR_PLAYER_X
  .R_REF_MEM .R_INT16, VAR_NPC_X
  .R_OPERATOR -
  .R_OPERATOR ABS ; Absolute value (hypothetical operator)
  .R_INT16
VM_STOP
VM_SET_INT16 VAR_DIFF_X, 0 ; Store result in VAR_DIFF_X

; Calculate absolute difference in Y coordinates
VM_RPN
  .R_REF_MEM .R_INT16, VAR_PLAYER_Y
  .R_REF_MEM .R_INT16, VAR_NPC_Y
  .R_OPERATOR -
  .R_OPERATOR ABS ; Absolute value (hypothetical operator)
  .R_INT16
VM_STOP
VM_SET_INT16 VAR_DIFF_Y, 0 ; Store result in VAR_DIFF_Y

; Check if both differences are within a certain range (e.g., 24 pixels)
VM_IF_CONST .LTE, VAR_DIFF_X, 24, CHECK_Y_DIFF, 0
  VM_JUMP NOT_NEAR_NPC

CHECK_Y_DIFF:
  VM_IF_CONST .LTE, VAR_DIFF_Y, 24, PLAYER_NEAR_NPC, 0
  VM_JUMP NOT_NEAR_NPC

PLAYER_NEAR_NPC:
  VM_LOAD_TEXT TEXT_NPC_GREETING
  VM_DISPLAY_TEXT
  VM_JUMP END_NPC_INTERACTION

NOT_NEAR_NPC:
  ; ... player is not near NPC, do nothing or other logic ...

END_NPC_INTERACTION:
  ; ... continue script ...

TEXT_NPC_GREETING:
  .TEXT "Hello there, traveler!"
  .TEXT_END

In this example, VM_ACTOR_GET_POS is used twice to retrieve the coordinates of both the NPC and the player. These coordinates are then used in RPN blocks to calculate the absolute differences in X and Y. Finally, VM_IF_CONST checks if these differences are small enough to consider the player “near” the NPC, triggering a dialogue.

Analogy to other programming languages/game engines: This is analogous to getting the position property of a game object or sprite in a 2D game engine:

• Unity (2D): Vector3 playerPos = playerTransform.position;
• Godot (2D): Vector2 player_pos = $Player.position;

It provides direct access to an actor’s spatial data, which is fundamental for implementing movement, interactions, and spatial awareness in your game.