Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Guide on how to use background tile swapping in GB Studio 3. (Made by NalaFala/Yousurname)

Background Tile Swapping Guide for GB Studio 3

Background tile swapping is a new built-in feature of GB Studio 3, but it is not yet easily accessible as of this guide. Background tile swapping can be useful for multiple things, such as animation and HUDs if you do not want to use sprites/palette swapping for them.


Firstly, you must determine whether you need to swap every tile of a certain type (like water animation) or just a certain tile on the background (such as placing a flower on a specific tile of grass). This guide will cover the former type of tile swapping.

Now, you have to make a background with all the tiles that you want to replace with. Below is an example of such for a flower animation.

Make sure to name the background image as first alphabetically compared to the other background names. You can do this by adding a ! before the file name.

Add a scene into your GB Studio project with this background. You may need to make this a logo scene. It is okay if the player can not reach this scene, but the scene has to be here for it to be loaded into the game.


Next, select the scene where you want to swap tiles. Add the event named "GBVM Script." There are two GBVM commands that you can use for this: VM_REPLACE_TILE_XY and VM_REPLACE_TILE. VM_REPLACE_TILE_XY is easier to use, so inside the text box, type the commands

VM_REPLACE_TILE_XY      X, Y, ___bank_tileset_0, _tileset_0, .ARG0
VM_POP                  1

Note: in GB Studio versions after 3.0.3, add a reference to the tiles background, then click on it to copy the required text, then paste it in place of ___bank_tileset_0, _tileset_0.

where START_IDX is the tile index you want to replace with from the tiles background you created before (e.g. 0 for the first tile, 1 for the second, etc.) and X and Y denote the position of the tile you want to replace on this scene (you can hover over a specific tile to see its coordinates). You likely will not need to change the numbers for ___bank_tileset_0 and _tileset_0 unless you have more than 256 tiles to replace with.

Alternatively, you can do something like

VM_REPLACE_TILE_XY      X, Y, ___bank_tileset_0, _tileset_0, VAR_MYVAR

after setting the global variable "MyVar" to the tile you want to replace with.

For example, here is my code for swapping the flower tile at X: 4, Y: 11 with the left-shifted flower tile.

VM_PUSH_CONST           1
VM_REPLACE_TILE_XY      4, 11, ___bank_tileset_0, _tileset_0, .ARG0
VM_POP                  1

Combined with other scripts, here is the result:

Copy link

untoxa commented Dec 20, 2021

VM_REPLACE_TILE_XY X, Y, ___bank_tileset_0, _tileset_0, VAR_MYVAR will change it to the index, stored in MYVAR. 0, as shown above, will be the first variable which is, obviously, random

Copy link

quentintamar commented Jan 9, 2022

this is nice ! i have a few question about it :

  • whats the point of adding Myvar at the end ? i've trouble to get that, i need to attribute a variable to each tile ? how do i do that ?
  • we give the line we want to use in the "store tile scene" but how did you give the information to take the 2nd and 3st frame of that line for the animation ?
  • the background image that store all frames can be as big as we want ?

Thanks :)

Copy link

Y0UR-U5ERNAME commented Jan 15, 2022


  • You can set the variable MyVar to some number that represents the index of the tile you want to replace with, before using the GBVM script.
  • The 2nd frame is index 1 and the 3rd frame is index 2.
  • In this case, the background image can have up to 256 unique tiles.

Copy link

TobyOrachee commented Apr 12, 2022

This code seems to replace all duplicates of the XY tile. I'm trying to replace just the one tile, can you help me with that?

Copy link

Polyducks commented Jun 29, 2022

@TobyOrachee Either make the initial tile unique and replace it with a new tile, or use Pau Tomas' plugin for background text and put your sprite on the font.

EDIT: see the second half of this tutorial (1.3) for replacing individual tiles:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment