Getting Started With 2020 GBDK

This tutorial is for getting started with GBDK. It is the first part of my “How to make a Gameboy Game” tutorial series. It is going to help you get setup developing with the 2020 GBDK. By the end, you should have a basic .gb file running in an emulator. This tutorial can be broken down into 4 parts.

  • Installing Visual Studio Code
  • Downloading the GBDK
  • Downloading a Gameboy Emulator
  • Getting a minimal .GB rom file created and running.

Installing Visual Studio Code

Knowledge of programming will be required for this tutorial. Any text editor can be used for programming. You can use notepad if you truly want. However, some editor’s have feature sets that make development a lot easier. Out of preference, in this tutorial series I will be using Visual Studio Code.

This part of getting started with 2020 GBDK is relatively straight forward. On the Visual Studio Code homepage you should see a button for downloading it. Visual Studio Code runs on multiple operating systems. Select and download the version for your operating system. I am running on a windows PC, so i’ll use the windows version.

Installing Visual Studio Code

Once the download is completed, start the installation. No real guide is needed at this part. You should be fine with the default installation options. Once done, open up the program and you should see something similar to the following image:

The Visual Studio Code Starting Screen

That’s it! You’ve installed Visual Studio Code. Next, we want to get the 2020 GBDK.

Downloading the 2020 GBDK

The GBDK can be downloaded from it’s GitHub Repository here: https://github.com/gbdk-2020/gbdk-2020. GBDK 2020 is an open source project. All of the source code can be viewed downloaded for free. However, the source code is not needed for getting started with gbdk. We only need our platform specific binaries.

GBD 2020 Binaries

Select & download the binaries for your computer’s operating system. Each download is just a zipped set of files. Once downloaded, unzip the files. I unzipped the GBDK to C:/gbdk. Before we get to code, let’s get a emulator to run on.

Downloading a Gameboy Emulator

BGB will be the emulator of choice when Getting Started with GBDK. it can be found here: https://bgb.bircd.org/. There is no installation needed. BGB comes as a standalone exe file.

The contents of the BGB downloadable

Unzip these files, and you are ready to go. The emulator can be run by double-clicking on the bgb.exe. Now that we have an emulator, let’s get a GB rom file running on it.

Getting Started with a minimal .GB rom file created and running.

Once we have GBDK downloaded, getting a minimal project running is super simple. I’ve created a basic git repo here. Download the code, and extract to a desired location. Once extracted, change the make.bat to point to your GBDK folder. 

In this repo are 3 .c files, and a make.bat file. The make.bat file will compile the 3 .c files and create a .gb file. This .gb file can be run in any gameboy emulator. Here is an example of what’s in the make.bat file:

				
					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
				
			

This file assumes your gbdk folder is located at C:\GBDK. You’ll need to adjust each instance of C:\GBDK\bin\lcc to reflect wherever you downloaded and extracted the GBDK.

The make.bat file can be run from the command terminal by simply typing “make.bat” in the command terminal.

Once you’ve run the make.bat file, a MinimalGameboyProject.gb file will be created. If you drop this MinimalGameboyProject.gb file into BGB, you should get an empty screen.

That’s it! You’re all done getting started with 2020 GBDK. You could take this .gb file and play it in a flash cart (like the EZ Flash Jr). Additionally you could write this .gb file to a actual physical (repro) gameboy cartridge. That would require hardware like this. These topics will be discussed later. If you found this helpful, please share on social media. Send me a message on facebook if you need help, or you can reach out by email to [email protected]

If you want to know a little bit more about what’s going on in this minimal project, check out this guide below:

Looking at a minimal GBDK 2020 Project

Looking at a minimal gbdk 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...