mvbg

VM_ACTOR_SET_ANIM_FRAME

VM_ACTOR_SET_ANIM_FRAME is a GBVM instruction used to directly set the current animation frame of a specified actor.

Purpose: While actors often have animations that play automatically, there are situations where you need precise control over which frame of an animation is displayed. VM_ACTOR_SET_ANIM_FRAME is essential for:

• Pausing animations: Holding an actor on a specific frame (e.g., a character frozen in mid-air).
• Skipping to a specific frame: Jumping directly to a particular point in an animation (e.g., for a quick reaction or a special effect).
• Synchronizing animations: Ensuring multiple actors or effects are perfectly aligned on a specific animation frame.
• Debugging: Manually setting an animation frame to test specific visual states.

This instruction overrides the automatic animation playback for the specified actor, allowing for granular control over its visual state.

Syntax:

VM_ACTOR_SET_ANIM_FRAME ACTOR_ID, FRAME_NUMBER

• ACTOR_ID: A variable that contains the actor number (ID) of the actor whose animation frame you want to set.
• FRAME_NUMBER: The specific frame number (an integer) to which the actor’s animation should be set. This value typically corresponds to an index within the actor’s currently loaded animation sequence.

Usage Example: Freezing a Character in a Specific Pose

Imagine a cutscene where a character needs to strike a specific pose and hold it, or a puzzle where an object needs to be frozen in a particular animation state.

; In your cutscene script or puzzle logic:

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

; Assume ANIM_PLAYER_ATTACK is the animation ID for the player's attack
ANIM_PLAYER_ATTACK:
  .R_INT8 5 ; Example Animation ID

; Set the player's animation to the attack animation
VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_ATTACK

; Wait for a few frames to let the animation start
VM_IDLE 10

; Freeze the player on frame 3 of their attack animation
VM_ACTOR_SET_ANIM_FRAME PLAYER_ACTOR_ID, 3

VM_LOAD_TEXT TEXT_PLAYER_FROZEN
VM_DISPLAY_TEXT
VM_IDLE 120 ; Hold the pose for 2 seconds

; Resume normal animation or set to idle
VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_PLAYER_IDLE

; ... continue script ...

TEXT_PLAYER_FROZEN:
  .TEXT "Player is frozen in time!"
  .TEXT_END

In this example, after starting the ANIM_PLAYER_ATTACK, VM_ACTOR_SET_ANIM_FRAME PLAYER_ACTOR_ID, 3 forces the player actor to display the third frame of that animation. This allows for precise control over the visual presentation of the actor, useful for scripted events or specific gameplay mechanics.

Analogy to other programming languages/game engines: This is analogous to directly setting the current frame of an animation or a sprite’s sub-image index in a game engine:

• Unity: animator.Play("AnimationName", 0, normalizedTime); (where normalizedTime can be used to set a specific frame)
• Godot: animation_player.seek(time_in_seconds, true); or directly setting frame property of an AnimatedSprite.

It provides a low-level way to control an actor’s visual animation state, bypassing the automatic playback system.