mvbg

VM_ACTOR_REPLACE_TILE

VM_ACTOR_REPLACE_TILE is a GBVM instruction used to dynamically replace specific tiles within an actor’s spritesheet with new tile data.

Purpose: Actors in Game Boy games are rendered using spritesheets, which are collections of small graphical tiles. This instruction allows for fine-grained control over an actor’s appearance at runtime, enabling:

Dynamic visual effects: Changing parts of an actor’s sprite to show damage, power-ups, or environmental effects (e.g., a character getting wet).
Custom animations: Creating unique, on-the-fly animations by swapping out individual tiles within a sprite.
Conditional appearance: Altering an actor’s look based on game state or player interaction (e.g., a treasure chest opening).
Optimized sprite usage: Reusing existing sprite memory by replacing only the necessary tiles rather than loading an entirely new spritesheet.

This instruction is powerful for creating subtle or dramatic visual changes to actors without requiring a full spritesheet swap.

Syntax:

VM_ACTOR_REPLACE_TILE ACTOR, TARGET_TILE, TILEDATA_BANK, TILEDATA, START, LEN

ACTOR: A variable that contains the actor number (ID) of the actor whose spritesheet tiles you want to replace.
TARGET_TILE: The tile number within the actor’s current spritesheet that you want to start replacing. Spritesheets are typically indexed starting from 0.
TILEDATA_BANK: The memory bank number where the new tile data (TILEDATA) is located. This handles bank switching for the new graphics.
TILEDATA: The address (label) of the new tile data. This points to the raw graphical data (pixels) for the replacement tiles.
START: The starting tile index within the TILEDATA array. This allows you to select a subset of tiles from the new tile data.
LEN: The amount of tiles to be replaced, starting from TARGET_TILE in the actor’s spritesheet and START in the TILEDATA.

Usage Example: Showing a Character Taking Damage

Imagine a player character who shows a visual indication of damage (e.g., a red tint or a broken shield) when their health drops below a certain threshold. You can have a separate set of “damaged” tiles and swap them in.

; In your player damage script:

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

; Assume VAR_PLAYER_HEALTH is the player's current health
VAR_PLAYER_HEALTH:
  .R_INT16 50

; Damaged sprite tiles (these would be defined in your assets)
DAMAGED_SPRITE_TILES_BANK:
  .R_INT8 BANK(DAMAGED_SPRITE_TILES)
DAMAGED_SPRITE_TILES:
  ; ... raw tile data for the damaged version of the player sprite ...

; Original sprite tiles (for restoring)
NORMAL_SPRITE_TILES_BANK:
  .R_INT8 BANK(NORMAL_SPRITE_TILES)
NORMAL_SPRITE_TILES:
  ; ... raw tile data for the normal player sprite ...

; Check if player health is low and damage effect is not active
VM_IF_CONST .LTE, VAR_PLAYER_HEALTH, 20, APPLY_DAMAGE_EFFECT, 0
  VM_JUMP END_DAMAGE_CHECK

APPLY_DAMAGE_EFFECT:
  ; Replace the first 8 tiles of the player's spritesheet with damaged tiles
  ; Assuming the player sprite uses 8 tiles and we want to replace them all.
  VM_ACTOR_REPLACE_TILE PLAYER_ACTOR_ID, 0, DAMAGED_SPRITE_TILES_BANK, DAMAGED_SPRITE_TILES, 0, 8

  VM_LOAD_TEXT TEXT_PLAYER_DAMAGED
  VM_DISPLAY_TEXT
  VM_IDLE 60

END_DAMAGE_CHECK:
  ; ... continue script ...

; Later, if health recovers, you might restore the original tiles:
RESTORE_NORMAL_SPRITE:
  VM_ACTOR_REPLACE_TILE PLAYER_ACTOR_ID, 0, NORMAL_SPRITE_TILES_BANK, NORMAL_SPRITE_TILES, 0, 8
  VM_RET

TEXT_PLAYER_DAMAGED:
  .TEXT "You are badly hurt!"
  .TEXT_END

In this example, when the player’s health drops below 20, VM_ACTOR_REPLACE_TILE is used to swap out the player’s normal sprite tiles with DAMAGED_SPRITE_TILES. This creates an immediate visual feedback of the player’s condition. If the player recovers, the NORMAL_SPRITE_TILES can be swapped back in.

Analogy to other programming languages/game engines: This is analogous to directly manipulating the texture or sprite data of a game object at a low level. In modern engines, you might achieve similar effects with shaders or by swapping out entire sprite assets. However, on the Game Boy, directly replacing tiles is a common and efficient way to achieve dynamic visual changes without consuming excessive memory for multiple full spritesheets.