mvbg

VM_ACTOR_MOVE_TO

VM_ACTOR_MOVE_TO is a GBVM instruction used to move a specified actor to a new X and Y coordinate within the game world.

Purpose: This instruction is fundamental for controlling the movement of characters, objects, and other entities in your game. It allows you to define a target destination for an actor, and the game engine will handle the pathfinding and animation to get the actor to that location. VM_ACTOR_MOVE_TO is essential for:

Character movement: Guiding players or NPCs along predefined paths or to specific points of interest.
Object animation: Moving platforms, doors, or other interactive elements.
AI navigation: Directing enemies or allies to patrol areas, chase targets, or retreat.
Cutscenes and scripted events: Orchestrating character movements during narrative sequences.

When VM_ACTOR_MOVE_TO is called, the actor will begin moving towards the specified X and Y coordinates. The movement typically continues until the actor reaches the destination or its movement is interrupted by VM_ACTOR_MOVE_CANCEL or another movement command.

Syntax:

VM_ACTOR_MOVE_TO ACTOR_ID, X, Y, ATTR

ACTOR_ID: A variable that contains the actor number (ID) of the actor to be moved.
X: The new X-coordinate (horizontal position) the actor should move to.
Y: The new Y-coordinate (vertical position) the actor should move to.
ATTR: A bit flag that controls various aspects of the movement. Common attributes include:
- .ACTOR_ATTR_H_FIRST: Prioritizes horizontal movement before vertical movement.
- .ACTOR_ATTR_CHECK_COLL: Enables collision detection during movement, preventing the actor from moving through solid objects.
- .ACTOR_ATTR_DIAGONAL: Allows the actor to move diagonally (if the engine supports it).

Usage Example: NPC Patrolling Between Two Points

Imagine an NPC that patrols back and forth between two specific points on the map. You can use VM_ACTOR_MOVE_TO to define these patrol points.

; In your NPC's update script or a dedicated patrol script:

; Assume NPC_PATROL_GUARD is the actor ID for the patrolling NPC
NPC_PATROL_GUARD:
  .R_INT8 12 ; Example Actor ID

; Define patrol points
PATROL_POINT_A_X:
  .R_INT16 32
PATROL_POINT_A_Y:
  .R_INT16 48
PATROL_POINT_B_X:
  .R_INT16 128
PATROL_POINT_B_Y:
  .R_INT16 48

; Variable to track current patrol state
VAR_PATROL_STATE:
  .R_INT8 0 ; 0 = moving to A, 1 = moving to B

NPC_PATROL_LOOP:
  VM_IF_CONST .EQ, VAR_PATROL_STATE, 0, MOVE_TO_B, 0

  ; Currently moving to B, check if arrived
  VM_ACTOR_GET_POS NPC_PATROL_GUARD, VAR_CURRENT_X, VAR_CURRENT_Y
  VM_IF_CONST .EQ, VAR_CURRENT_X, PATROL_POINT_B_X, ARRIVED_AT_B, 0
  VM_IF_CONST .EQ, VAR_CURRENT_Y, PATROL_POINT_B_Y, ARRIVED_AT_B, 0

  ; Continue moving to B
  VM_ACTOR_MOVE_TO NPC_PATROL_GUARD, PATROL_POINT_B_X, PATROL_POINT_B_Y, .ACTOR_ATTR_CHECK_COLL
  VM_JUMP END_PATROL_LOOP

ARRIVED_AT_B:
  VM_SET_CONST VAR_PATROL_STATE, 0 ; Change state to move to A next
  VM_IDLE 60 ; Pause at point B for a moment
  VM_JUMP NPC_PATROL_LOOP

MOVE_TO_B:
  ; Currently moving to A, check if arrived
  VM_ACTOR_GET_POS NPC_PATROL_GUARD, VAR_CURRENT_X, VAR_CURRENT_Y
  VM_IF_CONST .EQ, VAR_CURRENT_X, PATROL_POINT_A_X, ARRIVED_AT_A, 0
  VM_IF_CONST .EQ, VAR_CURRENT_Y, PATROL_POINT_A_Y, ARRIVED_AT_A, 0

  ; Continue moving to A
  VM_ACTOR_MOVE_TO NPC_PATROL_GUARD, PATROL_POINT_A_X, PATROL_POINT_A_Y, .ACTOR_ATTR_CHECK_COLL
  VM_JUMP END_PATROL_LOOP

ARRIVED_AT_A:
  VM_SET_CONST VAR_PATROL_STATE, 1 ; Change state to move to B next
  VM_IDLE 60 ; Pause at point A for a moment
  VM_JUMP NPC_PATROL_LOOP

END_PATROL_LOOP:
  VM_IDLE 1 ; Yield control for one frame
  VM_JUMP NPC_PATROL_LOOP

In this example, the NPC continuously moves between PATROL_POINT_A and PATROL_POINT_B using VM_ACTOR_MOVE_TO. The .ACTOR_ATTR_CHECK_COLL flag ensures the NPC respects collisions with other objects in its path. The VM_IDLE commands create brief pauses at each patrol point, making the movement more natural.

Analogy to other programming languages/game engines: This is analogous to setting a destination for a character in a game engine’s navigation system:

Unity: navMeshAgent.SetDestination(targetPosition);
Godot: move_and_slide(velocity); where velocity is calculated to move towards a target.
Older 2D engines: Often involved simple pathfinding algorithms or direct pixel-by-pixel movement towards a target coordinate.

It provides a high-level way to command an actor to move to a specific location, abstracting away the low-level details of movement animation and pathfinding.