GB Studio Tutorial - Animated Tiles

This is a basic interactive how-to tutorial for animated background tiles in GBStudio 3. The source code was built using with GBS 3.0.3.

This tutorial based on NalaFala (Yousurname)'s Background Tile Swapping Guide for GB Studio 3
But I've dumbed it down a bit for people new to GBVM, like me :)

GB Studio Tutorials:

• 1.0 - Animated Tiles < This Tutorial
• 2.0 - Background Sprites

Play in your Browser

You can play the interactive version at https://phinioxglade.itch.io/gbstudio-3-animated-tile-tutorial

We will cover the following 5 key ascepts of tile swap:

• 1.0 - Basic Tile Swapping
• 1.1 - Animating a tile
• 1.2 - Impact of replacing tile
• 1.3 - Update a single tile
• 1.4 - Update a multiple unique tile

Additionally we will cover GBVM script features:

• Accessing global variables
• Set varaibles
• Adding a value to a variable

Useful Resources

• GBVM source file
• GBVM Command Reference
• GB Studio Central - Understanding GBVM
• GB Studio Plug-In Database

1.0. Basic Tile Swapping

We can swap tile with another tile using GBVM scripts.
There are 2 commands which can do this:

• VM_REPLACE_TILE
• VM_REPLACE_TILE_XY

VM_REPLACE_TILE_XY is the easier to use. So will focus on it.

The function VM_REPLACE_TILE_XY has 5 paramaters:

1. X = position of the tile to be swapped, e.g. 3
2. Y = position of the tile to be swapped, e.g. 8
3. TILEDATA_BANK = not sure but it appears to be tiles in VRAM. just use ___bank_tileset_0
4. TILEDATA = is the tileset reference, e.g. _tileset_0
5. START_IDX = is the tile index in the tileset we want to swap tile X Y with, the value between 0 to 255

In this tutorial we have two tilesets:

1. _tileset_0 = !letters
2. _tileset_1 = !waterfall

Tilesets are assigned in alphabetical order of the background name

Future versions of GBStudio will allow you to get the TILEDATA_BANK and TILEDATA from within the UI

Now for the fun bit :)
We will swap the tile at X=14 Y=9 with tile in _tileset_0 at index 57, tile X=17 Y=2 in the !letters scene

GBVM Script Example

; start of GBVM script
; lines starting with ; are comments and are ignored by the compiler
; push the START_IDX value we want onto the stack, then it can be accessed by the alias .ARG0
; This take up memory, be sure to release it when done
VM_PUSH_CONST 57
; call the swap function by passing the START_IDX using .ARG0 alias
VM_REPLACE_TILE_XY 14, 9, ___bank_tileset_0, _tileset_0, .ARG0
; free memory assigned to .ARG0
VM_POP 1
; end of GBVM script

And just like that we have swapped the tile

Now we will replace the same tile with tile in !waterfall tileset at index 2

GBVM Script Example

; start of GBVM script
VM_PUSH_CONST 2
VM_REPLACE_TILE_XY 14, 9, ___bank_tileset_0, _tileset_1, .ARG0
VM_POP 1
; end of GBVM script

And just like that we have swapped the tile

1.1. Animating a tile

By using a loop we can animate a tile.
This done by referencing the next tile in the tileset.
We need to store which tile index we want to replace.
In this example are using a global variable called:
Loop_Index
Each time we loop, add 1 to Loop_Index.
When Loop_Index becomes greater than 255 it will wrap back to 0.
So we dont need to check for index of out bounds in this case.

To use global variables in GBVM you must prefixing VAR_ to your variable name in uppercase:

VAR_

Example

VAR_LOOP_INDEX

So you use the Loop_Index in VM_REPLACE_TILE_XY we need to reference like so:

VM_REPLACE_TILE_XY 14, 9, ___bank_tileset_0, _tileset_0, VAR_LOOP_INDEX

1.2. Impact of replacing tile

When you change a tile all tiles of the same memory address are changed.

1.3. Update a single tile

If you want to change a single tile, it must be unique in the source artwork.
Tiles 1, 2 and 3 are unqiue. Even if tile 1 is replaced with 2 or 3 from the tileset, it started with a different memory address. So it remains unique.

1.4. Update a multiple unique tile

If you want to animate more than unique tiles, you need to replace each individually.
In this example we will use the staggered animation to highlight the effect.

How to use VM_RPN

We can use VM_RPN to calculate the offset, which has 4 paramaters:

1. .R_REF <VAR_NAME>
   <VAR_NAME> is the variable input, example .R_REF VAR_LOOP_INDEX
2. <.R_Type> <Opperator>
   R_Type: The value type, .R_INT8 or .R_INT16, there might be more options <Value>: input value to be used, example .R_INT8 27
3. .R_OPERATOR <Opperator>
   <Opperator> which math function, example .R_OPERATOR .ADD, there is many, refer to the GBVM reference
4. .R_STOP
   guessing it stops the function

GBVM Script Example

; start of GBVM script
; calculate the next tile index by added 1 to 
VAR_LOOP_INDEX
VM_RPN
    .R_REF      VAR_LOOP_INDEX
    .R_INT8     1
    .R_OPERATOR .ADD
    .R_STOP
; replace the tile with using the calcaluted offset index
VM_REPLACE_TILE_XY      14, 9, ___bank_tileset_0, _tileset_0, .ARG0
; if we use VAR_LOOP_INDEX we would added 2
; if we use last variable calculated, .ARG0, we can add 1 since it already 1
; this shows you can reuse .ARG0
VM_RPN
.R_REF      .ARG0
.R_INT8     1
.R_OPERATOR .ADD
.R_STOP
VM_REPLACE_TILE_XY      17, 9, ___bank_tileset_0, _tileset_0, .ARG0
VM_POP 1
; end of GBVM script

Hopefully this turtorial is useful to you