mvbg

VM_ACTOR_SET_ANIM

VM_ACTOR_SET_ANIM is a GBVM instruction used to change the current animation being played by a specified actor.

Purpose: Actors in Game Boy games are often brought to life through animations (e.g., walking, running, attacking, idle). VM_ACTOR_SET_ANIM is essential for controlling an actor’s visual state and conveying its actions or emotions. It allows you to:

• Trigger specific actions: Start an attack animation when the player presses a button, or a jumping animation when they jump.
• Reflect state changes: Switch to an idle animation when an actor stops moving, or a damaged animation when they take a hit.
• Create dynamic scenes: Control the visual flow of cutscenes or scripted events by precisely setting actor animations.

When VM_ACTOR_SET_ANIM is called, the actor’s current animation is immediately replaced with the new one specified. The animation will then play according to its defined frames and speed (which can be adjusted with VM_ACTOR_SET_ANIM_TICK).

Syntax:

VM_ACTOR_SET_ANIM ACTOR, ANIM

• ACTOR: A variable that contains the actor number (ID) of the actor whose animation you want to change.
• ANIM: The animation number (an integer). This value typically corresponds to an index or identifier for a specific animation within the actor’s currently loaded animation set (which can be changed with VM_ACTOR_SET_ANIM_SET).

Usage Example: Player Character Walking Animation

Imagine your player character has different walking animations for each cardinal direction (Up, Down, Left, Right). When the player presses a direction button, you want to set the appropriate walking animation.

; In your player input handling script (part of the main game loop):

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

; Animation IDs (these would be defined in your game's animation data)
ANIM_PLAYER_WALK_UP:
  .R_INT8 0
ANIM_PLAYER_WALK_DOWN:
  .R_INT8 1
ANIM_PLAYER_WALK_LEFT:
  .R_INT8 2
ANIM_PLAYER_WALK_RIGHT:
  .R_INT8 3
ANIM_PLAYER_IDLE:
  .R_INT8 4

; Check player input
VM_INPUT_GET VAR_INPUT_STATE

; Check if Up button is pressed
VM_IF_CONST .EQ, VAR_INPUT_STATE, INPUT_UP, SET_WALK_UP_ANIM, 0
  VM_JUMP CHECK_DOWN

SET_WALK_UP_ANIM:
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_WALK_UP
  VM_JUMP END_ANIM_CHECK

CHECK_DOWN:
  VM_IF_CONST .EQ, VAR_INPUT_STATE, INPUT_DOWN, SET_WALK_DOWN_ANIM, 0
  VM_JUMP CHECK_LEFT

SET_WALK_DOWN_ANIM:
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_WALK_DOWN
  VM_JUMP END_ANIM_CHECK

CHECK_LEFT:
  VM_IF_CONST .EQ, VAR_INPUT_STATE, INPUT_LEFT, SET_WALK_LEFT_ANIM, 0
  VM_JUMP CHECK_RIGHT

SET_WALK_LEFT_ANIM:
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_WALK_LEFT
  VM_JUMP END_ANIM_CHECK

CHECK_RIGHT:
  VM_IF_CONST .EQ, VAR_INPUT_STATE, INPUT_RIGHT, SET_WALK_RIGHT_ANIM, 0
  VM_JUMP SET_IDLE_ANIM

SET_WALK_RIGHT_ANIM:
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_WALK_RIGHT
  VM_JUMP END_ANIM_CHECK

SET_IDLE_ANIM:
  ; If no directional input, set idle animation
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_IDLE

END_ANIM_CHECK:
  ; ... continue game loop ...

; Input constants (example values)
INPUT_UP:
  .R_INT8 1
INPUT_DOWN:
  .R_INT8 2
INPUT_LEFT:
  .R_INT8 4
INPUT_RIGHT:
  .R_INT8 8

In this example, VM_ACTOR_SET_ANIM is used to dynamically change the player character’s animation based on the detected input. If the player presses “Up,” the ANIM_PLAYER_WALK_UP animation is set, making the character visually move upwards. If no directional input is detected, the ANIM_PLAYER_IDLE animation is set.

Analogy to other programming languages/game engines: This is analogous to playing an animation clip or setting the current animation state for a character in a game engine:

• Unity: animator.Play("WalkUp"); or animator.SetTrigger("WalkUp");
• Godot: animation_player.play("walk_up");

It provides the core functionality for controlling an actor’s visual animations, making them responsive to game events and player actions.