mvbg

VM_ACTOR_SET_DIR

VM_ACTOR_SET_DIR is a GBVM instruction used to explicitly set the current facing direction of a specified actor.

Purpose: An actor’s direction is crucial for its visual representation and interaction logic in many Game Boy games. VM_ACTOR_SET_DIR is essential for:

• Visual accuracy: Ensuring the actor’s sprite is oriented correctly (e.g., a character facing the direction they are moving).
• AI behavior: Directing NPCs to face specific points, other characters, or the player.
• Interaction cues: Indicating which way an actor is looking, which can be important for dialogue triggers or line-of-sight mechanics.
• Animation synchronization: Often, changing direction also implies a change in animation (e.g., switching from a “walk right” animation to a “walk up” animation).

When VM_ACTOR_SET_DIR is called, the actor’s internal direction state is updated, and its sprite will typically change to reflect this new orientation. This instruction does not cause movement; it only changes the actor’s facing.

Syntax:

VM_ACTOR_SET_DIR ACTOR, DIR

• ACTOR: A variable that contains the actor number (ID) of the actor whose direction you want to set.
• DIR: A constant representing the desired cardinal direction. Common constants include:
  • .DIR_DOWN: Actor faces downwards.
  • .DIR_RIGHT: Actor faces rightwards.
  • .DIR_UP: Actor faces upwards.
  • .DIR_LEFT: Actor faces leftwards.

Usage Example: Making an NPC Face the Player After Interaction

Imagine an NPC that is initially facing a certain way. When the player interacts with them, you want the NPC to turn and face the player before starting a conversation.

; In your NPC's interaction script (triggered when player interacts):

; 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
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: prioritize vertical alignment, then horizontal)
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 START_DIALOGUE ; If same position, no direction change needed

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:
  ; Set the NPC's direction to face the player
  VM_ACTOR_SET_DIR NPC_VILLAGER_ID, VAR_TARGET_DIR

  VM_IDLE 10 ; Short pause to show the turn animation

START_DIALOGUE:
  VM_LOAD_TEXT TEXT_NPC_DIALOGUE
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT

  VM_RET

TEXT_NPC_DIALOGUE:
  .TEXT "Hello, traveler! How can I help you?"
  .TEXT_END

; Direction constants (example values, these would be defined globally)
.DIR_UP:
  .R_INT8 0
.DIR_DOWN:
  .R_INT8 1
.DIR_LEFT:
  .R_INT8 2
.DIR_RIGHT:
  .R_INT8 3

In this example, after the player interacts with the NPC, the script calculates the relative position of the player and sets VAR_TARGET_DIR accordingly. VM_ACTOR_SET_DIR NPC_VILLAGER_ID, VAR_TARGET_DIR then forces the NPC to turn and face the player before the dialogue begins, making the interaction feel more natural and responsive.

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

• Unity (2D): Setting transform.localScale.x to flip a sprite, or explicitly setting a direction variable that controls sprite animation.
• Godot (2D): Setting a direction property of a KinematicBody2D or similar node, which then updates the sprite’s flip_h property or animation state.

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