mvbg

VM_LOAD_TILESET

VM_LOAD_TILESET is a GBVM instruction used to load new graphical tile data into the Game Boy’s Video RAM (VRAM), specifically for background tiles, starting at a specified tile ID.

Purpose: Game Boy games are built using tiles, which are small (typically 8x8 pixel) graphical blocks. These tiles are stored in VRAM and are then used to construct backgrounds and sprites. VM_LOAD_TILESET is essential for:

Changing background graphics: Updating the visual appearance of a scene by loading a new set of background tiles (e.g., transitioning from a forest to a cave).
Dynamic environments: Loading different tile sets for various areas of the game world, allowing for diverse visual themes.
Memory management: Swapping out tile data in VRAM to make space for new graphics, as VRAM is a limited resource on the Game Boy.
Animation: While less common for full tilesets, it can be used to load animated background tiles by swapping them out periodically.

When VM_LOAD_TILESET is called, it copies a block of tile data from ROM (or another memory bank) into VRAM, starting at the specified IDX (tile ID). Any background maps that use these tile IDs will then display the newly loaded graphics.

Syntax:

VM_LOAD_TILESET IDX, BANK, BKG

IDX: The starting tile ID in VRAM where the new tiles will be loaded. This is the index into the VRAM tile data where the first tile of the new tileset will be placed.
BANK: The memory bank number where the source tile data (BKG) is located. This is crucial for accessing graphical data that might be in a different ROM bank.
BKG: The address (label) of the source tile data. This points to the raw graphical data (pixels) for the tiles you want to load.

Usage Example: Loading a New Tileset for a Scene Transition

Imagine your game transitions from an outdoor forest area to an indoor cave. You would load a new tileset containing cave-specific graphics when entering the cave scene.

; In your script, when entering the cave scene:

; Define the tileset data (these would be defined in your assets)
; Forest tileset
TILESET_FOREST_BANK:
  .R_INT8 BANK(TILESET_FOREST)
TILESET_FOREST:
  ; ... raw tile data for forest environment ...

; Cave tileset
TILESET_CAVE_BANK:
  .R_INT8 BANK(TILESET_CAVE)
TILESET_CAVE:
  ; ... raw tile data for cave environment ...

; ... code for scene transition trigger ...

ENTER_CAVE_SCENE:
  ; Load the cave tileset into VRAM, starting at tile ID 0
  VM_LOAD_TILESET 0, TILESET_CAVE_BANK, TILESET_CAVE
  ; IDX: 0 (start loading from the beginning of VRAM tile data)
  ; BANK: TILESET_CAVE_BANK (the bank where the cave tiles are)
  ; BKG: TILESET_CAVE (the address of the cave tile data)

  ; After loading the tileset, you would typically load a new background map
  ; that uses these new tiles.
  VM_OVERLAY_SET_MAP MAP_CAVE_BACKGROUND, 0, 0 ; Load the cave background map

  VM_LOAD_TEXT TEXT_ENTER_CAVE
  VM_DISPLAY_TEXT
  VM_IDLE 60

  ; ... continue scene setup (e.g., spawn actors, set camera) ...
  VM_RET

TEXT_ENTER_CAVE:
  .TEXT "You entered a dark cave!"
  .TEXT_END

MAP_CAVE_BACKGROUND:
  ; ... tile map data for the cave background, referencing tiles from TILESET_CAVE ...

In this example, VM_LOAD_TILESET 0, TILESET_CAVE_BANK, TILESET_CAVE copies the graphical data for the cave environment into the Game Boy’s VRAM. Once loaded, any background maps that reference these tile IDs will automatically display the new cave graphics. This allows for seamless visual transitions between different areas of your game.

Analogy to other programming languages/game engines: This is analogous to loading a new texture atlas or sprite sheet into graphics memory in a modern game engine, or updating the tile data in a tilemap system:

Unity (Tilemap): Loading a new Tilemap asset or programmatically updating Tilemap.SetTile() with new Tile assets.
Godot (TileMap): Changing the TileSet resource or updating individual cell data with set_cell().

It provides the core functionality for managing and updating the graphical assets that form the static backgrounds of your Game Boy game.