mvbg

VM_ACTOR_SET_POS

VM_ACTOR_SET_POS is a GBVM instruction used to immediately set the X and Y coordinates of a specified actor to a new position in the game world.

Purpose: This instruction allows for instant repositioning of actors without any animation or movement over time. It is essential for:

• Teleportation: Instantly moving a player or NPC to a new location (e.g., after using a warp, falling into a pit, or entering a new area).
• Spawning: Placing newly created or activated actors at their initial positions in a scene.
• Snap-to-grid behavior: Aligning actors precisely to a grid system.
• Correcting positions: Adjusting an actor’s position if it gets stuck or misaligned.
• Cutscenes and scripted events: Precisely placing characters for a dramatic effect or scene setup.

When VM_ACTOR_SET_POS is called, the actor’s position is updated instantly, and it will be rendered at the new coordinates in the very next frame.

Syntax:

VM_ACTOR_SET_POS ACTOR_ID, X, Y

• ACTOR_ID: A variable that contains the actor number (ID) of the actor whose position you want to set.
• X: The new X-coordinate (horizontal position) where the actor should be placed.
• Y: The new Y-coordinate (vertical position) where the actor should be placed.

Usage Example: Teleporting Player to a New Area

Imagine your player character steps on a warp tile, and you want to instantly move them to a new, predefined location on the map.

; In your script, when the player steps on a warp tile:

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

; Define the warp destination coordinates
WARP_DEST_X:
  .R_INT16 160 ; Example X-coordinate
WARP_DEST_Y:
  .R_INT16 128 ; Example Y-coordinate

; ... code for warp tile detection ...

PLAYER_ON_WARP_TILE:
  ; Instantly set the player's position to the warp destination
  VM_ACTOR_SET_POS PLAYER_ACTOR_ID, WARP_DEST_X, WARP_DEST_Y

  VM_LOAD_TEXT TEXT_WARPED
  VM_DISPLAY_TEXT
  VM_IDLE 60 ; Display message for a second

  ; You might also change the camera position here if it's a large warp
  ; VM_CAMERA_SET_POS WARP_DEST_X, WARP_DEST_Y

  VM_RET

TEXT_WARPED:
  .TEXT "You warped to a new area!"
  .TEXT_END

In this example, VM_ACTOR_SET_POS PLAYER_ACTOR_ID, WARP_DEST_X, WARP_DEST_Y instantly moves the player character to the coordinates defined by WARP_DEST_X and WARP_DEST_Y. This provides immediate feedback for the player and is suitable for teleportation or spawning mechanics.

Analogy to other programming languages/game engines: This is analogous to directly setting the position property of a game object or sprite:

• Unity: transform.position = new Vector3(x, y, z);
• Godot: position = Vector2(x, y);
• HTML/CSS: Setting left and top CSS properties for an absolutely positioned element.

It provides direct, instantaneous control over an actor’s spatial location in the game world.