mvbg

VM_ACTOR_MOVE_CANCEL

VM_ACTOR_MOVE_CANCEL is a GBVM instruction used to immediately stop any ongoing movement of a specified actor.

Purpose: Actors in Game Boy games often move autonomously (e.g., patrolling NPCs, moving platforms) or in response to script commands (VM_ACTOR_MOVE_TO). There are situations where you need to interrupt this movement prematurely. VM_ACTOR_MOVE_CANCEL is essential for:

• Player interaction: If a player interacts with a moving NPC, you might want the NPC to stop immediately to engage in dialogue.
• Collision response: Stopping an actor’s movement if it collides with an obstacle or another actor.
• Dynamic behavior changes: Changing an actor’s state from moving to idle, attacking, or fleeing, requiring an immediate halt to its current movement.
• Event triggers: Halting all movement when a specific game event occurs (e.g., a cutscene starts, time freezes).

When VM_ACTOR_MOVE_CANCEL is executed, the actor’s movement script is interrupted, and its position becomes fixed at its current coordinates. Any pending VM_ACTOR_MOVE_TO commands for that actor will be aborted.

Syntax:

VM_ACTOR_MOVE_CANCEL ACTOR

• ACTOR: A variable that contains the actor number (ID) of the actor whose movement you want to cancel.

Usage Example: Stopping a Patrolling NPC for Dialogue

Imagine you have an NPC patrolling a path using VM_ACTOR_MOVE_TO commands. When the player interacts with this NPC, you want it to stop moving immediately and face the player to begin a conversation.

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

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

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

; ... code for player interaction detection ...

PLAYER_INTERACTS_WITH_NPC:
  ; Immediately stop the NPC's current movement
  VM_ACTOR_MOVE_CANCEL NPC_PATROL_GUARD

  ; Make the NPC face the player
  ; (This would involve getting player/NPC positions and setting direction)
  VM_ACTOR_GET_POS NPC_PATROL_GUARD, VAR_NPC_X, VAR_NPC_Y
  VM_ACTOR_GET_POS PLAYER_ACTOR_ID, VAR_PLAYER_X, VAR_PLAYER_Y
  ; ... logic to determine target direction (e.g., VM_ACTOR_SET_DIR) ...

  VM_LOAD_TEXT TEXT_NPC_DIALOGUE
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT

  ; After dialogue, you might resume patrol or other behavior
  ; VM_CALL RESUME_NPC_PATROL

  VM_RET

TEXT_NPC_DIALOGUE:
  .TEXT "Greetings, traveler!"
  .TEXT_END

In this example, VM_ACTOR_MOVE_CANCEL NPC_PATROL_GUARD is called as soon as the player interacts with the NPC. This ensures that the NPC stops mid-patrol, allowing for a smooth transition into dialogue without the NPC continuing to move or slide. After the dialogue, you would typically re-initiate the NPC’s movement or other behaviors.

Analogy to other programming languages/game engines: This is analogous to stopping a character’s movement or animation in a game engine:

• Unity: navMeshAgent.Stop(); or rigidbody.velocity = Vector3.zero;
• Godot: move_and_slide() returning Vector2.ZERO or setting velocity = Vector2.ZERO;

It provides a way to abruptly halt an actor’s motion, which is crucial for responsive and event-driven gameplay.