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.
#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();
}
}
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.
// Loop forever
while(1) {}
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.
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
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.
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.
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.
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.
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.