mvbg

VM_ACTOR_BEGIN_UPDATE

VM_ACTOR_BEGIN_UPDATE is a GBVM instruction used to initiate a block of script code that will be executed as part of an actor’s update loop. This allows you to define custom behaviors that run continuously for a specific actor.

Purpose: In game development, many actor behaviors (like movement, animation, AI, or interaction checks) need to be updated every game frame or at regular intervals. VM_ACTOR_BEGIN_UPDATE marks the start of a script segment that will be repeatedly called for the specified actor. This is essential for:

Continuous actor behavior: Implementing AI routines that constantly check for player proximity, patrol paths, or react to environmental changes.
Per-actor logic: Defining unique update logic for individual actors without cluttering the main game loop.
Optimized processing: By associating update scripts directly with actors, the GBVM can efficiently manage which scripts need to run each frame.

When VM_ACTOR_BEGIN_UPDATE is called, the GBVM associates the subsequent script block with the specified actor. This block will then be executed whenever that actor’s update routine is processed by the game engine.

Syntax:

VM_ACTOR_BEGIN_UPDATE ACTOR

ACTOR: A variable that contains the actor number (ID) of the actor for which the update script is being defined.

Usage Example: Implementing a Simple Patrolling NPC

Imagine you have an NPC that you want to patrol back and forth between two points. You can define a script block that handles this movement and associate it with the NPC actor using VM_ACTOR_BEGIN_UPDATE.

; In your scene initialization or when the NPC is spawned:

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

; Define the update script for the patrolling NPC
NPC_PATROL_UPDATE_SCRIPT:
  ; Check current direction and move
  VM_ACTOR_GET_DIR NPC_PATROL_GUARD, VAR_NPC_DIR

  VM_IF_CONST .EQ, VAR_NPC_DIR, DIR_RIGHT, MOVE_LEFT_OR_WAIT, 0
    ; Currently moving right, check if reached right boundary
    VM_ACTOR_GET_POS NPC_PATROL_GUARD, VAR_NPC_X, VAR_NPC_Y
    VM_IF_CONST .GTE, VAR_NPC_X, 100, CHANGE_DIR_LEFT, 0
      VM_ACTOR_MOVE_TO NPC_PATROL_GUARD, 100, VAR_NPC_Y, 16 ; Continue moving right
      VM_JUMP END_PATROL_UPDATE

CHANGE_DIR_LEFT:
  VM_ACTOR_SET_DIR NPC_PATROL_GUARD, DIR_LEFT
  VM_ACTOR_MOVE_TO NPC_PATROL_GUARD, 20, VAR_NPC_Y, 16 ; Start moving left
  VM_JUMP END_PATROL_UPDATE

MOVE_LEFT_OR_WAIT:
  ; Currently moving left, check if reached left boundary
  VM_ACTOR_GET_POS NPC_PATROL_GUARD, VAR_NPC_X, VAR_NPC_Y
  VM_IF_CONST .LTE, VAR_NPC_X, 20, CHANGE_DIR_RIGHT, 0
    VM_ACTOR_MOVE_TO NPC_PATROL_GUARD, 20, VAR_NPC_Y, 16 ; Continue moving left
    VM_JUMP END_PATROL_UPDATE

CHANGE_DIR_RIGHT:
  VM_ACTOR_SET_DIR NPC_PATROL_GUARD, DIR_RIGHT
  VM_ACTOR_MOVE_TO NPC_PATROL_GUARD, 100, VAR_NPC_Y, 16 ; Start moving right

END_PATROL_UPDATE:
  VM_ACTOR_TERMINATE_UPDATE ; End the actor's update script for this frame

; Associate the update script with the NPC actor
VM_ACTOR_BEGIN_UPDATE NPC_PATROL_GUARD
  ; The script block for NPC_PATROL_UPDATE_SCRIPT will be executed here.
  ; The actual script code for NPC_PATROL_UPDATE_SCRIPT would follow this.
  ; In GB Studio, this is often handled by linking a script to an actor's update event.
  ; For direct GBVM, the script would be defined as a subroutine.
  VM_CALL NPC_PATROL_UPDATE_SCRIPT
VM_ACTOR_END_UPDATE ; (Conceptual, often implied by VM_ACTOR_TERMINATE_UPDATE)

; ... rest of your scene setup ...

In this conceptual example, VM_ACTOR_BEGIN_UPDATE NPC_PATROL_GUARD would signal that the following code (or a linked script) is the update logic for NPC_PATROL_GUARD. This script would then be called repeatedly, allowing the NPC to continuously check its position and change direction, creating a patrolling behavior.

Important Note: The actual implementation of VM_ACTOR_BEGIN_UPDATE and VM_ACTOR_TERMINATE_UPDATE (or similar) in GBVM often involves setting up a pointer within the actor’s data structure to the start of its update script. The game engine’s main loop then iterates through all active actors and calls their respective update scripts.

Analogy to other programming languages: This is analogous to defining an update() or tick() method for an object in a game engine (e.g., Unity’s MonoBehaviour.Update(), Godot’s _process() method). It’s a common pattern for implementing per-entity logic that needs to run every frame to simulate continuous behavior.