mvbg

VM_ACTOR_GET_DIR

VM_ACTOR_GET_DIR is a GBVM instruction used to retrieve the current facing direction of a specified actor and store it into a GBVM variable.

Purpose: Actors in Game Boy games often have a cardinal direction (Up, Down, Left, Right) that determines their sprite orientation, movement behavior, or interaction logic. VM_ACTOR_GET_DIR allows your script to know which way an actor is currently facing. This is essential for:

AI behavior: An enemy AI might need to know its current direction to continue patrolling, or to turn and face the player before attacking.
Player interaction: Determining if the player is facing a specific object or NPC to initiate dialogue or an action.
Animation control: Selecting the correct animation (e.g., walking up, walking down) based on the actor’s direction.
Collision detection: Checking if an actor is moving towards a wall or another object in a specific direction.

The direction value returned is typically an integer representing one of the cardinal directions (e.g., 0=Up, 1=Down, 2=Left, 3=Right, though specific values may vary by engine configuration).

Syntax:

VM_ACTOR_GET_DIR IDX, DEST

IDX: A variable that contains the actor number (ID) of the actor whose direction you want to retrieve.
DEST: The target variable (a GBVM variable) where the retrieved actor direction will be stored.

Usage Example: Making an NPC Face the Player

Imagine an NPC that, when the player approaches, turns to face the player. You can get the player’s position and the NPC’s position to determine the required direction.

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

; 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 and direction
VAR_NPC_X:
  .R_INT16 0
VAR_NPC_Y:
  .R_INT16 0
VAR_PLAYER_X:
  .R_INT16 0
VAR_PLAYER_Y:
  .R_INT16 0
VAR_NPC_CURRENT_DIR:
  .R_INT8 0
VAR_TARGET_DIR:
  .R_INT8 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

; Determine target direction based on relative positions
; (Simplified logic for demonstration)
VM_IF_CONST .GT, VAR_PLAYER_Y, VAR_NPC_Y, SET_DIR_DOWN, 0
  VM_IF_CONST .LT, VAR_PLAYER_Y, VAR_NPC_Y, SET_DIR_UP, 0
  VM_IF_CONST .GT, VAR_PLAYER_X, VAR_NPC_X, SET_DIR_RIGHT, 0
  VM_IF_CONST .LT, VAR_PLAYER_X, VAR_NPC_X, SET_DIR_LEFT, 0
  VM_JUMP END_DIR_CHECK ; If same position, no change

SET_DIR_DOWN:
  VM_SET_CONST VAR_TARGET_DIR, DIR_DOWN
  VM_JUMP APPLY_DIR

SET_DIR_UP:
  VM_SET_CONST VAR_TARGET_DIR, DIR_UP
  VM_JUMP APPLY_DIR

SET_DIR_RIGHT:
  VM_SET_CONST VAR_TARGET_DIR, DIR_RIGHT
  VM_JUMP APPLY_DIR

SET_DIR_LEFT:
  VM_SET_CONST VAR_TARGET_DIR, DIR_LEFT

APPLY_DIR:
  ; Get current NPC direction
  VM_ACTOR_GET_DIR NPC_VILLAGER_ID, VAR_NPC_CURRENT_DIR

  ; Only change direction if it's different from target
  VM_IF_CONST .NE, VAR_NPC_CURRENT_DIR, VAR_TARGET_DIR, CHANGE_NPC_DIR, 0
  VM_JUMP END_DIR_CHECK

CHANGE_NPC_DIR:
  VM_ACTOR_SET_DIR NPC_VILLAGER_ID, VAR_TARGET_DIR

END_DIR_CHECK:
  ; ... continue NPC script ...

; Direction constants (example values)
DIR_UP:
  .R_INT8 0
DIR_DOWN:
  .R_INT8 1
DIR_LEFT:
  .R_INT8 2
DIR_RIGHT:
  .R_INT8 3

In this example, VM_ACTOR_GET_DIR NPC_VILLAGER_ID, VAR_NPC_CURRENT_DIR retrieves the NPC’s current facing direction. This is then compared with a VAR_TARGET_DIR (calculated based on player position) to decide if the NPC needs to turn. If a change is needed, VM_ACTOR_SET_DIR is used to update the NPC’s direction.

Analogy to other programming languages/game engines: This is analogous to getting the facing direction or orientation property of a character in a 2D game:

Unity (2D): Checking transform.localScale.x for sprite flipping, or a custom direction variable.
Godot (2D): Accessing a direction property of a KinematicBody2D or similar node.

It provides access to an actor’s cardinal orientation, which is fundamental for many game mechanics involving movement, interaction, and visual representation.