mvbg

VM_ACTOR_TERMINATE_UPDATE

VM_ACTOR_TERMINATE_UPDATE is a GBVM instruction used to stop the execution of an actor’s update script.

Purpose: Actors often have scripts that run continuously (e.g., for AI, animation, or movement) initiated by VM_ACTOR_BEGIN_UPDATE. However, there are many scenarios where you need to stop this continuous execution. VM_ACTOR_TERMINATE_UPDATE is essential for:

• Changing actor behavior: If an actor transitions from one state (e.g., patrolling) to another (e.g., attacking or idle), its previous update script might need to be stopped.
• Optimizing performance: Stopping update scripts for actors that are no longer active, off-screen, or have completed their purpose.
• Event-driven logic: Halting an actor’s continuous script when a specific event occurs (e.g., player interaction, death, reaching a destination).

When VM_ACTOR_TERMINATE_UPDATE is called, the GBVM will cease calling the associated update script for that actor in subsequent frames. The actor will then remain in its current state unless new commands are issued.

Syntax:

VM_ACTOR_TERMINATE_UPDATE ACTOR

• ACTOR: A variable that contains the actor number (ID) of the actor whose update script you want to terminate.

Usage Example: Stopping an NPC Patrol After Interaction

Imagine an NPC that patrols a specific area. When the player interacts with this NPC, you want it to stop patrolling and engage in dialogue. After the dialogue, the patrol script should not resume.

; In your NPC's update script (e.g., NPC_PATROL_SCRIPT):

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

; Assume VAR_NPC_INTERACTED is a flag (0 = no, 1 = yes)
VAR_NPC_INTERACTED:
  .R_INT8 0

NPC_PATROL_SCRIPT:
  ; Check if player has interacted with this NPC
  VM_IF_CONST .EQ, VAR_NPC_INTERACTED, 1, END_PATROL_SCRIPT, 0

  ; ... normal patrol logic (e.g., VM_ACTOR_MOVE_TO, VM_IDLE) ...

  VM_JUMP NPC_PATROL_SCRIPT ; Continue patrolling

END_PATROL_SCRIPT:
  ; Terminate this actor's update script
  VM_ACTOR_TERMINATE_UPDATE NPC_PATROL_GUARD
  VM_RET ; Return from the script (it won't be called again as an update script)

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

PLAYER_INTERACTS_WITH_NPC:
  ; Set flag to indicate interaction
  VM_SET_CONST VAR_NPC_INTERACTED, 1

  ; The NPC's patrol script will detect this flag and terminate itself.

  VM_LOAD_TEXT TEXT_NPC_DIALOGUE
  VM_DISPLAY_TEXT
  VM_INPUT_WAIT

  VM_RET

TEXT_NPC_DIALOGUE:
  .TEXT "Thank you for stopping me!"
  .TEXT_END

In this example, the NPC_PATROL_SCRIPT continuously checks VAR_NPC_INTERACTED. When the player interacts, this flag is set. In the next frame, the patrol script detects the flag, executes VM_ACTOR_TERMINATE_UPDATE NPC_PATROL_GUARD, and then returns. This effectively stops the NPC’s patrolling behavior permanently (or until a new update script is assigned).

Analogy to other programming languages/game engines: This is analogous to disabling or removing an update function or component from a game object:

• Unity: Disabling a MonoBehaviour script component (script.enabled = false;) or destroying it (Destroy(script);).
• Godot: Setting set_process(false) or set_physics_process(false) on a node, or removing it from the scene tree.

It provides a way to explicitly stop an actor’s continuous, frame-by-frame logic, allowing for transitions to new behaviors or states.