GBDK 2020 Docs  4.1.1
API Documentation for GBDK 2020
Getting Started

Follow the steps in this section to start using GBDK-2020.

1. Download a Release and unzip it

You can get the latest releases from here: https://github.com/gbdk-2020/gbdk-2020/releases

2. Compile Example projects

Make sure your GBDK-2020 installation is working correctly by compiling some of the included example projects.

If everything works in the steps below and there are no errors reported then each project that was built should have its own .gb ROM file (or suitable extension for the other supported targets).

Windows (without Make installed):

Navigate to a project within the example projects folder ("examples\gb\" under your GBDK-2020 install folder) and open a command line. Then type: 

compile

or 

compile.bat

This should build the example project. You can also navigate into other example project folders and build in the same way.

Linux / MacOS / Windows with Make installed:

Navigate to the example projects folder ("examples/gb/" under your GBDK-2020 install folder) and open a command line. Then type: 

make

This should build all of the examples sequentially. You can also navigate into an individual example project's folder and build it by typing make.

3. Use a Template

To create a new project use a template!

There are template projects included in the GBDK example projects to help you get up and running. Their folder names start with template_.

  1. Copy one of the template folders to a new folder name.
  2. If you moved the folder out of the GBDK examples then you must update the GBDK path variable and/or the path to LCC in the Makefile or compile.bat so that it will still build correctly.
  3. Type make on the command line in that folder to verify it still builds.
  4. Open main.c to start making changes.

4. If you use GBTD / GBMB, get the fixed version

If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the const fix and other improvements. See const_gbtd_gbmb.

5. Review Coding Guidelines

Take a look at the coding guidelines, even if you have experience writing software for other platforms. There is important information to help you get good results and performance on the Game Boy.

If you haven't written programs in C before, check the C tutorials section.

6. Hardware and Resources

If you have a specific project in mind, consider what hardware you want to target. It isn't something that has to be decided up front, but it can influence design and implementation.

What size will your game or program be?

  • 32K Cart (no-MBC required)
  • Larger than 32K (MBC required)
  • See more details about ROM Banking and MBCs

What console platform(s) will it run on?

If targeting the Game Boy, what hardware will it run on?

7. Set up C Source debugging

Tracking down problems in code is easier with a debugger. Emulicious has a debug adapter that provides C source debugging with GBDK-2020.

8. Try a GBDK Tutorial

You might want to start off with a guided GBDK tutorial from the GBDK Tutorials section.

  • Note: Tutorials (or parts of them) may be based on the older GBDK from the 2000's before it was updated to be GBDK-2020. The general principles are all the same, but the setup and parts of the toolchain (compiler/etc) may be somewhat different and some links may be outdated (pointing to the old GBDK or old tools).

9. Read up!

10. Need help?

Check out the links for online community and support and read the FAQ.

Migrating From Pre-GBDK-2020 Tutorials

Several popular GBDK Tutorials, Videos and How-to's were made before GBDK-2020 was available, as a result some information they include is outdated or incompatible. The following summarizes changes that should be made for best results.

Also see:

Use auto-banking

GBDK-2020 now supports auto-banking (rom_autobanking). In most cases using auto-banking will be easier and less error prone than manually assigning source and assets to banks.

  • There is a source example banks_autobank project.

Non-standard types (UINT8, etc)

The old GBDK types UINT8, INT8, UINT16, INT16 are non-standard and less portable.

The following should be used instead: uint8_t, int16_t, uint16_t, int32_t, uint32_t and bool.

These are standard types defined in stdint.h (#include <stdint.h>) and stdbool.h (#include <stdbool.h>).

If using GBTD / GBMB, get the fixed version

If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the const fix and other improvements. See const_gbtd_gbmb.

LCC and SDCC flags that are not needed

The following flag is no longer needed with lcc and sdcc, it can be removed without any loss of performance.

ROM Header Settings (such as Color, SGB, etc)

Setting ROM bytes directly with -Wl-yp0x<address>=0x<value> is no longer supported. Instead use makebin flags. For example, use -Wm-yC instead of -Wl-yp0x143=0xC0. See faq_gb_type_header_setting.

GBDK Header include changes

The following header files which are now cross platform were moved from gb/ to gbdk/: bcd.h, console.h, far_ptr.h, font.h, gbdecompress.h, gbdk-lib.h, incbin.h, metasprites.h, platform.h, version.h

  • When including them use #include <gbdk/...> instead of #include <gb/>

Include .h headers, not .c source files

Do not #include .c source files into other .c source files. Instead create .h header files for them and include those.

Use the Template Projects

Modern project templates are included with GBDK-2020. Using them (and their Makefile or compile.bat) as a starting point for projects is recommended and can help ensure better default settings and project organization.

Use hUGEtracker instead of gbt_player

hUGEtracker and its driver hUGEdriver are smaller, more efficient and more versatile than gbt_player.