mvbg

VM_ACTOR_GET_ANIM_FRAME

VM_ACTOR_GET_ANIM_FRAME is a GBVM instruction used to retrieve the current animation frame of a specified actor.

Purpose: Actors in Game Boy games often have animations (e.g., walking, attacking, idle). These animations are composed of a sequence of frames. VM_ACTOR_GET_ANIM_FRAME allows your script to know which frame of the current animation an actor is currently displaying. This is essential for:

• Synchronizing events with animations: Triggering a sound effect, a particle effect, or a change in game state precisely when a specific animation frame is reached (e.g., a sword swing hitting its target).
• Conditional behavior based on animation: Changing an actor’s AI or interaction options depending on its current animation state.
• Debugging and monitoring: Observing an actor’s animation progress during development.

Syntax:

VM_ACTOR_GET_ANIM_FRAME ACTOR

• ACTOR: A pseudo-struct that contains two members:
  • ID: The actor number (ID) of the actor whose animation frame you want to retrieve.
  • FRAME: This is the target variable where the retrieved animation frame number will be stored. The instruction will write the current frame number into this variable.

Usage Example: Triggering a Sound Effect on a Specific Attack Frame

Imagine a player character’s attack animation. You want a “whoosh” sound effect to play exactly when the sword is at the peak of its swing (e.g., frame 3 of the attack animation).

; In your player attack script (part of the actor's update loop or a triggered event):

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

; Variable to store the current animation frame
VAR_CURRENT_ANIM_FRAME:
  .R_INT8 0

; Flag to ensure sound plays only once per attack animation
VAR_SOUND_PLAYED_THIS_ATTACK:
  .R_INT8 0

; ... code that initiates the attack animation (e.g., VM_ACTOR_SET_ANIM) ...

CHECK_ATTACK_FRAME:
  ; Get the current animation frame of the player actor
  VM_ACTOR_GET_ANIM_FRAME PLAYER_ACTOR_ID, VAR_CURRENT_ANIM_FRAME

  ; Check if it's frame 3 and the sound hasn't played yet
  VM_IF_CONST .EQ, VAR_CURRENT_ANIM_FRAME, 3, PLAY_SWOOSH_SOUND, 0
  VM_IF_CONST .EQ, VAR_SOUND_PLAYED_THIS_ATTACK, 0, PLAY_SWOOSH_SOUND, 0
  VM_JUMP END_FRAME_CHECK

PLAY_SWOOSH_SOUND:
  VM_SFX_PLAY SFX_SWOOSH ; Play the sound effect
  VM_SET_CONST VAR_SOUND_PLAYED_THIS_ATTACK, 1 ; Set flag to prevent re-playing

END_FRAME_CHECK:
  ; ... continue with other animation logic or return ...

; When the attack animation finishes, reset the flag:
; VM_SET_CONST VAR_SOUND_PLAYED_THIS_ATTACK, 0

SFX_SWOOSH:
  ; ... sound effect data ...

In this example, VM_ACTOR_GET_ANIM_FRAME PLAYER_ACTOR_ID, VAR_CURRENT_ANIM_FRAME retrieves the current frame number. The script then checks if it’s the desired frame (3) and if the sound has already been played for this attack. If both conditions are met, the SFX_SWOOSH is played.

Analogy to other programming languages/game engines: This is analogous to querying the current frame of an animation clip in a game engine:

• Unity: animator.GetCurrentAnimatorStateInfo(0).normalizedTime (can be used to derive frame)
• Godot: animation_player.get_current_animation_position() (can be used to derive frame)

It provides a way to synchronize game logic with the visual progression of an actor’s animation.