mvbg

VM_ACTOR_SET_SPRITESHEET_BY_REF

VM_ACTOR_SET_SPRITESHEET_BY_REF is a GBVM instruction used to change the entire spritesheet (graphical data) used by a specified actor, by providing a reference to the new spritesheet’s memory location and bank.

Purpose: Actors in Game Boy games are visually represented by sprites, which are drawn from spritesheets. This instruction allows for dynamic changes to an actor’s appearance by swapping out its entire graphical data. This is essential for:

• Character transformations: Changing a character’s visual appearance completely (e.g., a character transforming into a monster, a vehicle, or a powered-up state).
• Costume changes: Allowing characters to change outfits or forms during gameplay.
• State-based visuals: Altering an actor’s look based on its current state (e.g., a broken robot, a powered-up player).
• Optimized memory usage: Loading different spritesheets only when needed, rather than keeping all possible spritesheets in memory simultaneously.

When VM_ACTOR_SET_SPRITESHEET_BY_REF is called, the actor’s rendering system is updated to draw its sprites from the new spritesheet data. This is particularly useful when spritesheets are stored in different memory banks, as it handles the necessary bank switching.

Syntax:

VM_ACTOR_SET_SPRITESHEET_BY_REF ACTOR, FAR_PTR

• ACTOR: A variable that contains the actor number (ID) of the actor whose spritesheet you want to change.
• FAR_PTR: A pseudo-struct (or a variable pointing to one) that contains the address of the new spritesheet. This pseudo-struct typically has two members:
  • BANK: The memory bank number where the new spritesheet data is located.
  • DATA: The address (label) of the new spritesheet data within that bank.

Usage Example: Player Character Transforming into a Beast

Imagine a game where the player character can transform into a powerful beast. This transformation involves a complete change in their visual appearance, requiring a new spritesheet.

; 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

; Define references to the spritesheet data (these would be defined in your assets)
; Human form spritesheet
SPRITESHEET_HUMAN_REF:
  .R_INT8 BANK(SPRITESHEET_HUMAN)
  .R_INT16 SPRITESHEET_HUMAN
SPRITESHEET_HUMAN:
  ; ... raw sprite data for human form ...

; Beast form spritesheet
SPRITESHEET_BEAST_REF:
  .R_INT8 BANK(SPRITESHEET_BEAST)
  .R_INT16 SPRITESHEET_BEAST
SPRITESHEET_BEAST:
  ; ... raw sprite data for beast form ...

; ... code for transformation trigger ...

TRANSFORM_TO_BEAST:
  ; Change the player's spritesheet to the beast form
  VM_ACTOR_SET_SPRITESHEET_BY_REF PLAYER_ACTOR_ID, SPRITESHEET_BEAST_REF

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

  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 spritesheet back to human form
  VM_ACTOR_SET_SPRITESHEET_BY_REF PLAYER_ACTOR_ID, SPRITESHEET_HUMAN_REF

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

  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

ANIM_HUMAN_IDLE:
  .R_INT8 0
ANIM_BEAST_IDLE:
  .R_INT8 0

In this example, VM_ACTOR_SET_SPRITESHEET_BY_REF PLAYER_ACTOR_ID, SPRITESHEET_BEAST_REF instantly changes the player character’s entire visual appearance by loading a new spritesheet. This is a powerful way to implement significant visual transformations for actors in your game.

Analogy to other programming languages/game engines: This is analogous to dynamically loading and assigning a new texture or sprite atlas to a character in a game engine:

• Unity: Changing the Sprite property of a SpriteRenderer or swapping out an entire SpriteAtlas.
• Godot: Changing the texture property of a Sprite node or assigning a new SpriteFrames resource to an AnimatedSprite.

It provides a way to completely alter an actor’s visual identity by pointing it to a different set of graphical data, even if that data is located in a different memory bank.