mvbg

VM_ACTOR_SET_ANIM_SET

VM_ACTOR_SET_ANIM_SET is a GBVM instruction used to change the entire set of animations available to a specified actor.

Purpose: Actors in games often have different sets of animations depending on their state, equipment, or context. For example, a character might have one set of animations for walking and running, and a completely different set for swimming or flying. VM_ACTOR_SET_ANIM_SET is essential for:

• Character transformations: Changing a character’s visual and behavioral animations when they transform (e.g., into a monster, a vehicle, or a powered-up state).
• Equipment changes: Updating an actor’s animations to reflect new equipment (e.g., a sword-wielding animation set vs. a bow-wielding animation set).
• Contextual animations: Switching between animation sets for different gameplay modes (e.g., exploration animations vs. combat animations).

When VM_ACTOR_SET_ANIM_SET is called, the actor’s internal animation data pointer is updated to a new set of animations. This means that subsequent calls to VM_ACTOR_SET_ANIM will draw from this new set.

Syntax:

VM_ACTOR_SET_ANIM_SET ACTOR, OFFSET

• ACTOR: A variable that contains the actor number (ID) of the actor whose animation set you want to change.
• OFFSET: The animation set number (an integer). This value typically corresponds to an index or identifier for a predefined collection of animations within your game’s assets.

Usage Example: Character Transformation

Imagine a game where the player character can transform into a powerful beast. This transformation changes their appearance and their available actions (and thus, their animations).

; In your script, when the player triggers a transformation:

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

; Animation set IDs (these would be defined in your game's animation data)
ANIM_SET_HUMAN:
  .R_INT8 0
ANIM_SET_BEAST:
  .R_INT8 1

; Variable to track player form
VAR_PLAYER_FORM:
  .R_INT8 0 ; 0 = Human, 1 = Beast

; ... code for transformation trigger ...

TRANSFORM_TO_BEAST:
  ; Change the player's animation set to the beast form
  VM_ACTOR_SET_ANIM_SET PLAYER_ACTOR_ID, ANIM_SET_BEAST

  ; Set the default animation for the beast form (e.g., idle)
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_BEAST_IDLE

  ; Update player form flag
  VM_SET_CONST VAR_PLAYER_FORM, 1

  VM_LOAD_TEXT TEXT_TRANSFORMED
  VM_DISPLAY_TEXT
  VM_IDLE 60

  ; ... other beast-form specific logic ...
  VM_RET

TRANSFORM_TO_HUMAN:
  ; Change the player's animation set back to human form
  VM_ACTOR_SET_ANIM_SET PLAYER_ACTOR_ID, ANIM_SET_HUMAN

  ; Set the default animation for the human form
  VM_ACTOR_SET_ANIM PLAYER_ACTOR_ID, ANIM_HUMAN_IDLE

  ; Update player form flag
  VM_SET_CONST VAR_PLAYER_FORM, 0

  VM_LOAD_TEXT TEXT_TRANSFORMED_BACK
  VM_DISPLAY_TEXT
  VM_IDLE 60

  ; ... other human-form specific logic ...
  VM_RET

TEXT_TRANSFORMED:
  .TEXT "You transformed into a beast!"
  .TEXT_END

TEXT_TRANSFORMED_BACK:
  .TEXT "You returned to human form!"
  .TEXT_END

; Example animation IDs within each set (conceptual)
ANIM_HUMAN_IDLE:
  .R_INT8 0
ANIM_BEAST_IDLE:
  .R_INT8 0

In this example, VM_ACTOR_SET_ANIM_SET PLAYER_ACTOR_ID, ANIM_SET_BEAST completely changes the set of animations that the PLAYER_ACTOR_ID can use. After this, any VM_ACTOR_SET_ANIM calls will refer to animations within the ANIM_SET_BEAST collection. This allows for significant visual and functional changes to an actor based on game state.

Analogy to other programming languages/game engines: This is analogous to swapping out an entire animation controller or a set of animation clips for a character in a game engine:

• Unity: Changing the AnimatorController asset on an Animator component.
• Godot: Changing the AnimationPlayer node or loading a different AnimationLibrary.

It provides a high-level way to completely alter an actor’s animation capabilities and visual identity.