Looking at a minimal GBDK 2020 Project

GBDK 2020 comes with a C compiler. This allows users to compile Gameboy games in C, rather than in Assembly. The C programming language is easier to understand than Assembly. However, there is a tradeoff. What you get in convenience, you lose in performance and control. It won’t be taught on The Junkyard, but for maximum capabilities and performance, Assembly should be used.

If you don’t know C, here are some basic tutorials on the GBDK 2020 Docs. If you’re just getting started with GBDK, definitely bookmark the GBDK 2020 docs’ getting started page.

This section is going to teach you each aspect of a Minimal GBDK 2020 Project . A barebones GBDK 2020 project has 2 main parts. It has an entry point .C file, and some way to compile said .C file into a .gb file. That .gb file can be run on gameboy cartridges and in emulators like BGB.

The following 2 code snippets are straight from my ‘minimal-gameboy-project‘ repo on github.

The Main.c File

				
					#include <gb/gb.h>

void main(void)
{
    DISPLAY_ON;

    // Loop forever
    while(1) {

		// Done processing, yield CPU and wait for start of next frame
        wait_vbl_done();
    }
}

The "Main" Function

Our “main” function outlines the entry point for our game. When a gameboy or emulator loads up a game, it will execute this main function and all logic in it. When the main function’s logic is done, the gameboy/emulator will remain in it’s current state.

Turning the Display On

				
					DISPLAY_ON;

Although sometimes this may be unneccessary, this line ensures that the display is actually on. That way, any tiles we try to draw are actually drawn on the screen.

The Game Loop

				
					// Loop forever
while(1) {}

Almost every game has a “game loop”. This loop’s condition is set to ‘1’. Which means it will run infinitely. In this loop we would normally put all of our game’s logic.

Waiting for Vertical Blank Completion

				
					wait_vbl_done();

Straight from GBDK documentation: This function HALTs the CPU and waits for the vertical blank interrupt (VBL) to finish. This is often used in main loops to idle the CPU at low power until it’s time to start the next frame. It’s also useful for syncing animation with the screen re-draw. If the screen is off this function returns immediately.

In my own words: This function can be used to achieve a certain desired frame rate, and restrict the next iteration of your game loop from running before everything is rendered.

The Make.c File

There are different ways to compile .c files, but my current preference are simple windows batch files. I’ve tried to comment everything with REM statements, but i’ll break everything down for clarity.

				
					REM delete previous files
DEL *.gb

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

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

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

Removing previous .gb files

				
					DEL *.gb

The first step delete’s the previous .gb file. This step can be omitted without error. However, it’s easier for me to see when there is an error when i use this line. If i don’t see a .gb file, then i know compilation failed for some reason.

Compiling our C files

				
					C:\gbdk\bin\lcc -c -o main.o main.c

The line compiles our main.c file into an object file called main.o. NOTE: you may have to adjust based on the location of your lcc executable. By default, GBDK 2020 binaries come with lcc.exe executables ready to go. They are located in the “bin” folder.

Compiling our .GB ROM

				
					C:\GBDK\bin\lcc  -o MinimalGameboyProject.gb main.o

The line takes our compiled main.o file, and any other .o files compiled, and then combines them into a single file named “MinimalGameboyProject.gb”. If all goes well, this file can be run on gameboy emulators and/or actual gameboy cartridges.

Cleanup

This step is optional but recommended. For clarity, this step removes any extra files generated from the previous commands.

				
					DEL *.asm
DEL *.lst
DEL *.ihx
DEL *.sym
DEL *.o

That’s it! I hope everything was clear. If not, please do reach out. Your criticism and questions help The Junkyard out a lot. If you found this informative, please do share it on social media.