Mastodon
Larold's Jubilant Junkyard
Larold's Jubilant Junkyard
Table of Contents
How to show a background in gbdk
Every game needs graphics. The next step in this tutorial is to show a background. Part 2 will extend from the minimal template used in Part 1. Besides during gameplay, backgrounds can be used as splash screens, large bosses, and even for menus.
Table of Contents

Drawing on the Background and Window Layers

Drawing on the Background and Window Layers

This is part 2 of my “How to make a Gameboy Game” tutorial series. If you haven’t read part 1 yet, you can find it here. In part 1, a minimal GBDK template was used get a minimal/blank .gb ROM file created. In this part 2 we will get a basic background showing. Here is a visual:

Image to VRAM to Background

If you want to know more about the inner workings of backgrounds, checkout our our guide on Gameboy Graphics. From here, part 2 can be broken down into 4 major steps.

  1. Convert the Background Image to GBDK .c and .h files.
  2. Add our .c and .h files to existing code
  3. Place the background tiles into VRAM (set_bkg_data)
  4. Showing the background  (set_bkg_tiles)

The background and window layers are tile maps, made of 8×8 sized tiles. Each layer is 32 tiles wide, and 32 tiles high. This makes their overall max size in pixels 256x256px. The background and window layers do not support transparency, and they share the same Tile data in VRAM. (This means that the window and background will use the same tiles). The background and window can be moved freely separately.

The Gameboy screen is 160px by 144px. The tiles in the background & window tilemaps will wrap around when they exceed the 256px mark vertically and/or horizontally. Here is an awesome video that explains more about the background and window on the Gameboy.

If you want to learn how to draw maps larger than 256x256px in size, check out this tutorial: Drawing Large Maps in GBDK

Check us out on Youtube

If you are a visual learner, check out the Larold’s Jubilant Junkyard YouTube Page. I’ve started uploading videos there too. The video editing process takes a lot longer than writing tutorials, and am juggling multiple projects at once, but it is on my TODO list to do a full video series and more.

Initial Files

For this step, i’m going to be using a basic background i created from my logo. I’ve already converted the background to GBDK format here:

Those two files need to be downloaded and placed alongside your main.c file. Once these two files have been downloaded, we need to make sure the .c file is actually compiled and included in our .gb file.

Make.bat:

				
					:: delete previous files
DEL *.gb

:: compile .c files into .o files
C:\gbdk\bin\lcc -c -o main.o main.c
C:\gbdk\bin\lcc -c -o LaroldsJubilantJunkyard.o LaroldsJubilantJunkyard.c

:: Compile a .gb file from the compiled .o files
C:\GBDK\bin\lcc -o DrawingOnTheBackgoundAndWindow.gb main.o LaroldsJubilantJunkyard.o

:: delete intermediate files created for the conmpilation process
DEL *.asm
DEL *.lst
DEL *.ihx
DEL *.sym
DEL *.o

In our main.c file we need to include the header file also.


Main.c:

				
					#include <gb/gb.h>
#include "LaroldsJubilantJunkyard.h"

void main(void)
{
    DISPLAY_ON;
}

Showing the background

The entire background layer can be turned on and off. By default, it is off. We can use these two macros to turn it on and off.
 
Main.c:
				
					#include <gb/gb.h>
#include "LaroldsJubilantJunkyard.h"

void main(void)
{
    DISPLAY_ON;
    
    SHOW_BKG;
    // Use HIDE_BKG; to turn the background OFF
}

Placing background tiles into VRAM

VRAM stands for “Video RAM”. Before we get into how to display backgrounds and sprites, the topic of VRAM must be shortly explained.

For Gameboy games, it is a essentially a variable collection of 8x8px tiles. There is a dedicated space in VRAM for sprites, and another dedicated space in VRAM for the background/window (they share this space). Both spaces can have a maximum of 256 tiles. The contents of these spaces can be changed at any time.

For ANYTHING to be displayed on screen, it must be stored in VRAM first. Everything you see on screen maps to a VRAM tile.

The GBDK “set_bkg_data” function will place a given number of tiles in the VRAM space dedicated to the window/background. This function takes in 3 parameters.

  1. The first parameter is where in VRAM to start placing the tile.
  2. The second parameter is how many tiles to place in VRAM
  3. The Third parameter is a pointer to the actual tiledata. I have a tutorial on understanding the GBDK/Gameboy Tileformat

Usage of the “set_bkg_data” function looks like this:

				
					#include <gb/gb.h>
#include "LaroldsJubilantJunkyard.h"

void main(void)
{
    DISPLAY_ON;
    
    SHOW_BKG;
    // Use HIDE_BKG; to turn the background OFF

    // Load & set our background data
    set_bkg_data(0,178,LaroldsJubilantJunkyard_data);
}

Drawing tiles on the Background Layer

The “set_bkg_data” function handles putting tiles in VRAM for the window and background. Now that we have our desired tiles in VRAM, we can display them on the background & window layers. To do this we must use the “set_win_tiles” and “set_bkg_tiles” functions to tell the background/window tile maps which tiles to display. These two functions will place tiles, from VRAM, onto the window and background layer.
				
					#include <gb/gb.h>
#include "LaroldsJubilantJunkyard.h"

void main(void)
{
    DISPLAY_ON;
    
    SHOW_BKG;
    // Use HIDE_BKG; to turn the background OFF

    // Load & set our background data
    set_bkg_data(0,178,LaroldsJubilantJunkyard_data);
    
    // The gameboy screen is 160px wide by 144px tall
    // We deal with tiles that are 8px wide and 8px tall
    // 160/8 = 20, and 144/8 = 18
    set_bkg_tiles(0,0,20,18,LaroldsJubilantJunkyard_map_plane0);
}

If you now run the make.bat file, you should see a background with the default gameboy colors. It’s not very pretty, but it’s something. We can add colors later in this tutorial.

Simple Background Drawn in default Gameboy Colors

Drawing tiles on The Window Layer

The gameboy also has a “window” layer. The window layer is always above the background, non-transparent, and uses the same tiles in VRAM. The window layer is commonly used for drawing a HUD. You’ll see it in many games for drawing the score, level, and or health.
 
GBDK 2020 defines a “set_win_data” function. However this does the same thing as the “set_bkg_data” function. You  can actually use “set_win_data” and “set_bkg_data” interchangeably, since the window and background occupy they use same tiles in VRAM.
However, if you want to display tiles on the window, you don’t use the “set_bkg_tiles” function. Instead, you use a matching “set_win_tiles” function, who’s parameters are exactly the same.
 
By default, the window is not visible. We can use a GBDK-provided macros “SHOW_WIN” and/or “HIDE_WIN” to show or hide the window respectively. We are not going to use the window layer in this tutorial, so no code snippet will be given to avoid confusion.

Adding color to the background/window (Gameboy Color Only)

This section only applies for gameboy color games. If we want to enable color backgrounds, then we need to do a little more. Firstly, we need to add the “-Wm-yC” flag when compiling our .gb file.

				
					:: Compile a .gb file from the compiled .o files
C:\GBDK\bin\lcc -Wm-yC  -o DrawingOnTheBackgoundAndWindow.gb main.o LaroldsJubilantJunkyard.o

Secondly, we need to update our headers to include <gb/cgb.h>.

				
					#include <gb/gb.h>
#include <gb/cgb.h>
#include "LaroldsJubilantJunkyard.h"

void main(void)
{
    ... Code from previous steps
    
    // The "LaroldsJubilantJunkyard_pallette" color palette is defined in LaroldsJubilantJunkyard.c
    set_bkg_palette(0,1,LaroldsJubilantJunkyard_pallette);
}

Thirdly, we need to put our desired color palettes in VRAM. The following code places 1 palette in the first color palette slot.

				
					#include <gb/gb.h>
#include <gb/cgb.h>
#include "LaroldsJubilantJunkyard.h"

void main(void)
{
    ... Code from previous steps
    
    // The "LaroldsJubilantJunkyard_pallette" color palette is defined in LaroldsJubilantJunkyard.c
    set_bkg_palette(0,1,LaroldsJubilantJunkyard_pallette);
}
For gameboy color games, a second map can be specified. This second map and previously mentioned map are often referred to as “planes”. This second map is stored in VRAM bank 1. This second map should be the same size as the first map, however it’s values DO NOT point to tiles in VRAM. The values in the second map define attributes for their associated values in the first map.
 
From left (bit 7) to right (bit 0):
  • bit 7 – priority: When set to 1, the associated tile appears ABOVE sprites.
  • bit 6 – vertical flip: When set to 1, the associated tile is flipped vertically.
  • bit 5 – horizontal flip: When set to 1, the associated tile is flipped horizontally.
  • bit 4 – not used
  • bit 3 – Which bank (0 or 1) the tile is taken from
  • bits 2-0 – Which color palette to use.

If you are just setting which color palette to use, like in this tutorial, you just need to use a value between0 and 7 inclusive.

The second map is stored in VRAM bank 1. To switch to bank 1, we need to use a GBDK provided “VBK_REG” macro. Oncewe are in VRAM bank 1, we can setthetiles for our second map/plane.

				
					#include <gb/gb.h>
#include <gb/cgb.h>
#include "LaroldsJubilantJunkyard.h"

void main(void)
{
    ... Code from previous steps 

    // Switch to bank 1 for writing background tile attributes.
    VBK_REG=1;
    set_bkg_tiles(0,0,20,18,LaroldsJubilantJunkyard_map_plane1);
}
Always remember to switch bank to bank 0, after setting your background tile attributes.
				
					#include <gb/gb.h>
#include <gb/cgb.h>
#include "LaroldsJubilantJunkyard.h"

void main(void)
{
    ... Code from previous steps

    // Switch back to bank 0 to prevent accidentally writing to bank 1
    VBK_REG=0;
}
With all of that said and done, we should end up with something like this in BGB:
BGB Colored Background

The final product can also be seen on github: https://github.com/LaroldsJubilantJunkyard/drawing-on-the-background-and-window

If you want to draw very large maps, The Junkyard has a tutorial on that too: Drawing Large Maps in GBDK

My Game Boy tutorials have a lot of C Programming. If you need help, here’s a book that may help you:
C Programming Language, 2nd Edition
Who else is making Game Boy Games?

There are many individuals who are developing games for retro consoles. Here’s one you might like:

il_794xN.3831672056_s19b
BlackCastleBox
BlackCastleBack

Black Castle

Created By: Userx07F

The times were dark and the kingdom was threatened by a black warlock. His evil magic brought disease and destruction to the land, but none of the king’s knights found the courage to fight him. One day a young knight appeared. He set out for the warlock’s black castle to free the kingdom from his tyranny.

Buy it Today

Other Tutorials:

PNG2asset for gbdk-2020
rpg style movement like in zelda for gbdk 2020
Parallax Backgrounds with GBDK
Sign-up for the Junkyard Newsletter!

Receive updates as soon as possible, by signing up for the Junkyard Newsletter. Get all the latest information delivered straight to your email box. New Tutorials, New Events, Game Reviews, Giveaways and more.

How to make Gameboy Games
Making Popular Games for Gameboy
Social Media
Helpful Gameboy Resources

Sign-Up for the "Junkyard Newsletter" for more Game Boy news!

If you like Game Boy Game Development, subscribe to the Junkyard Newsletter. Stay up-to-date with all the latest Game Boy news. It’s free, and you can unsubscribe any time!