mvbg

VM_ACTOR_GET_ANGLE

VM_ACTOR_GET_ANGLE is a GBVM instruction used to retrieve the current angle or orientation of a specified actor and store it into a GBVM variable.

Purpose: In games, actors often have an orientation or facing direction, especially in 2D top-down or isometric views. This angle can be crucial for:

AI behavior: An enemy AI might need to know its current angle to turn towards a target or patrol along a specific arc.
Projectile aiming: When an actor fires a projectile, the projectile’s initial trajectory might depend on the actor’s current angle.
Visual representation: While VM_ACTOR_GET_DIR gets cardinal directions, VM_ACTOR_GET_ANGLE might provide a more granular rotational value, useful for more complex sprite rotations or visual effects.
Collision detection: Determining if an actor is facing a particular object or area.

The angle value returned is typically an integer representing a specific range (e.g., 0-255 for a full circle, or 0-3 for cardinal directions if the engine maps angles to directions).

Syntax:

VM_ACTOR_GET_ANGLE IDX, DEST

IDX: A variable that contains the actor number (ID) of the actor whose angle you want to retrieve.
DEST: The target variable (a GBVM variable) where the retrieved actor angle will be stored.

Usage Example: Making an Enemy Turn Towards the Player

Imagine an enemy that, when alerted, needs to turn to face the player before attacking. You can get the enemy’s current angle and the player’s position to calculate the required turn.

; In your enemy AI script, when the enemy is alerted:

; Assume ENEMY_ACTOR_ID is the actor ID for the enemy
ENEMY_ACTOR_ID:
  .R_INT8 30 ; Example Actor ID

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

; Variables to store positions and angle
VAR_ENEMY_X:
  .R_INT16 0
VAR_ENEMY_Y:
  .R_INT16 0
VAR_PLAYER_X:
  .R_INT16 0
VAR_PLAYER_Y:
  .R_INT16 0
VAR_ENEMY_ANGLE:
  .R_INT8 0 ; Assuming angle is 8-bit
VAR_TARGET_ANGLE:
  .R_INT8 0

; Get enemy's current position and angle
VM_ACTOR_GET_POS ENEMY_ACTOR_ID, VAR_ENEMY_X, VAR_ENEMY_Y
VM_ACTOR_GET_ANGLE ENEMY_ACTOR_ID, VAR_ENEMY_ANGLE

; Get player's current position
VM_ACTOR_GET_POS PLAYER_ACTOR_ID, VAR_PLAYER_X, VAR_PLAYER_Y

; Calculate the angle from enemy to player
; This would typically involve a native C function or a complex RPN calculation
; For simplicity, let's assume a hypothetical VM_CALC_ANGLE_TO_TARGET function exists
; VM_CALC_ANGLE_TO_TARGET VAR_ENEMY_X, VAR_ENEMY_Y, VAR_PLAYER_X, VAR_PLAYER_Y, VAR_TARGET_ANGLE

; For a simpler example, let's just set a target angle directly for demonstration
; If player is to the right, set angle to 0 (right)
VM_IF_CONST .GT, VAR_PLAYER_X, VAR_ENEMY_X, SET_ANGLE_RIGHT, 0
  ; If player is to the left, set angle to 2 (left)
  VM_SET_CONST VAR_TARGET_ANGLE, 2
  VM_JUMP APPLY_ANGLE

SET_ANGLE_RIGHT:
  VM_SET_CONST VAR_TARGET_ANGLE, 0

APPLY_ANGLE:
  ; Set the enemy's direction/angle to face the player
  VM_ACTOR_SET_DIR ENEMY_ACTOR_ID, VAR_TARGET_ANGLE ; Assuming SET_DIR can take an angle
  ; Or, if there's a VM_ACTOR_SET_ANGLE:
  ; VM_ACTOR_SET_ANGLE ENEMY_ACTOR_ID, VAR_TARGET_ANGLE

  VM_IDLE 30 ; Wait for a short moment for the turn animation

  ; ... proceed with attack or other AI ...

In this example, VM_ACTOR_GET_ANGLE ENEMY_ACTOR_ID, VAR_ENEMY_ANGLE retrieves the enemy’s current orientation. This value can then be used in conjunction with player position to calculate a VAR_TARGET_ANGLE, which is then applied to the enemy using VM_ACTOR_SET_DIR (or a hypothetical VM_ACTOR_SET_ANGLE). This allows for dynamic and responsive AI behavior.

Analogy to other programming languages: This is analogous to getting the rotation or orientation property of a game object in a 2D game engine:

Unity (2D): float zRotation = transform.rotation.eulerAngles.z;
Godot (2D): float rotation_radians = get_rotation();

It provides access to an actor’s rotational state, which is fundamental for many game mechanics involving direction and aiming.