mvbg

VM_ACTOR_SET_SPRITESHEET

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

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. It 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 treasure chest opening, a damaged enemy).
• Optimized memory usage: Loading different spritesheets only when needed, rather than keeping all possible spritesheets in memory simultaneously.

When VM_ACTOR_SET_SPRITESHEET 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 ACTOR, SHEET_BANK, SHEET

• ACTOR: A variable that contains the actor number (ID) of the actor whose spritesheet you want to change.
• SHEET_BANK: The memory bank number where the new spritesheet data (SHEET) is located. This is crucial for accessing graphical data that might be in a different ROM bank.
• SHEET: The address (label) of the new spritesheet data within that bank. This points to the raw graphical data (pixels and tile definitions) for the new appearance.

Usage Example: NPC Becoming a Zombie

Imagine a villager NPC who, after a certain event (e.g., a curse), transforms into a zombie. This involves a complete change in their visual appearance.

; In your script, when the transformation event occurs:

; Assume VILLAGER_ACTOR_ID is the actor ID for the villager
VILLAGER_ACTOR_ID:
  .R_INT8 20 ; Example Actor ID

; Define the spritesheet data (these would be defined in your assets)
; Villager spritesheet
SHEET_VILLAGER_BANK:
  .R_INT8 BANK(SHEET_VILLAGER)
SHEET_VILLAGER:
  ; ... raw sprite data for normal villager ...

; Zombie spritesheet
SHEET_ZOMBIE_BANK:
  .R_INT8 BANK(SHEET_ZOMBIE)
SHEET_ZOMBIE:
  ; ... raw sprite data for zombie ...

; ... code for curse event ...

CURSE_TRANSFORMATION:
  ; Change the villager's spritesheet to the zombie form
  VM_ACTOR_SET_SPRITESHEET VILLAGER_ACTOR_ID, SHEET_ZOMBIE_BANK, SHEET_ZOMBIE

  ; Set the default animation for the zombie form (e.g., idle)
  VM_ACTOR_SET_ANIM VILLAGER_ACTOR_ID, ANIM_ZOMBIE_IDLE

  VM_LOAD_TEXT TEXT_VILLAGER_CURSED
  VM_DISPLAY_TEXT
  VM_IDLE 60

  ; ... other zombie-specific logic (e.g., change AI) ...
  VM_RET

TEXT_VILLAGER_CURSED:
  .TEXT "The villager has been cursed!"
  .TEXT_END

ANIM_ZOMBIE_IDLE:
  .R_INT8 0 ; Example animation ID for zombie idle

In this example, VM_ACTOR_SET_SPRITESHEET VILLAGER_ACTOR_ID, SHEET_ZOMBIE_BANK, SHEET_ZOMBIE instantly changes the villager’s entire visual appearance by loading the zombie spritesheet. This is a powerful way to implement significant visual transformations for actors in your game, making the game world feel dynamic and responsive to events.

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.