GBDK 2020 Docs  4.1.1
API Documentation for GBDK 2020
Supported Consoles & Cross Compiling

Consoles Supported by GBDK

As of version 4.0.5 GBDK includes support for other consoles in addition to the Game Boy.

  • Game Boy and related clones
    • Nintendo Game Boy / Game Boy Color (GB/GBC)
    • Analogue Pocket (AP)
    • Mega Duck / Cougar Boy (DUCK)
  • Sega Consoles
    • Sega Master System (SMS)
    • Sega Game Gear (GG)
  • MSX DOS (MSXDOS) (partial support)
  • NES (NES) (partial support)

While the GBDK API has many convenience functions that work the same or similar across different consoles, it's important to keep their different capabilities in mind when writing code intended to run on more than one. Some (but not all) of the differences are screen sizes, color capabilities, memory layouts, processor type (z80 vs gbz80/sm83) and speed.

Cross Compiling for Different Consoles


When compiling and building through lcc use the -m<port>:<plat> flag to select the desired console via its port and platform combination.


When building directly with the sdcc toolchain, the following must be specified manually (when using lcc it will populate these automatically based on -m<port>:<plat>).

When compiling with sdcc:

  • -m<port>, -D__PORT_<port> and -D__TARGET_<plat>

When assembling with sdasgb (for GB/AP) and sdasz80 (for SMS/GG):

  • Select the appropriate include path: -I<gbdk-path>lib/<plat>

When linking with sdldgb (for GB/AP) and sdldz80 (for SMS/GG or MSXDOS):

  • Select the appropriate include paths: -k <gbdk-path>lib/<port>, -k <gbdk-path>lib/<plat>
  • Include the appropriate library files -l <port>.lib, -l <plat>.lib
  • The crt will be under <gbdk-path>lib/<plat>/crt0.o

MSXDOS requires an additional build step with makecom after makebin to create the final binary:

  • makecom <image.bin> [<image.noi>] <>

The NES port has --no-peep specified (in lcc) due to a peephole related codegen bug in SDCC that has not yet been merged.

  • If you wish to build without that flag then SDCC can be called directly instead of through lcc.
  • Alternately, custom peephole rules from a file can be passed in using -Wf--peep-file (lcc) or --peep-file (sdcc).

Console Port and Platform Settings

Note: Starting with GBDK-2020 4.1.0 and SDCC 4.2, the Game Boy and related clones use sm83 for the port instead of gbz80

  • Nintendo Game Boy / Game Boy Color
    • lcc : -msm83:gb
    • port:sm83, plat:gb
  • Analogue Pocket
    • lcc : -msm83:ap
    • port:sm83, plat:ap
  • Mega Duck / Cougar Boy
    • lcc : -msm83:duck
    • port:sm83, plat:duck
  • Sega Master System
    • lcc : -mz80:sms
    • port:z80, plat:sms
  • Sega Game Gear
    • lcc : -mz80:gg
    • port:z80, plat:gg
    • lcc : -mz80:msxdos
    • port:z80, plat:msxdos
  • NES
    • lcc : -mmos6502:nes
    • port:mos6502, plat:nes

Cross-Platform Constants

There are several constant #defines that can be used to help select console specific code during compile time (with #ifdef, #ifndef) .

Console Identifiers

  • When <gb/gb.h> is included (either directly or through <gbdk/platform.h>)
    • When building for Game Boy:
      • NINTENDO will be #defined
      • GAMEBOY will be #defined
    • When building for Analogue Pocket
      • NINTENDO will be #defined
      • ANALOGUEPOCKET will be #defined
    • When building for Mega Duck / Cougar Boy
      • NINTENDO will be #defined
      • MEGADUCK will be #defined
  • When <sms/sms.h> is included (either directly or through <gbdk/platform.h>)
    • When building for Master System
      • SEGA will be #defined
      • MASTERSYSTEM will be #defined
    • When building for Game Gear
      • SEGA will be #defined
      • GAMEGEAR will be #defined
  • When <msx/msx.h> is included (either directly or through <gbdk/platform.h>)
    • MSXDOS will be #defined

Console Hardware Properties

Constants that describe properties of the console hardware are listed below. Their values will change to reflect the current console target that is being built.

Using <gbdk/...> headers

Some include files under <gbdk/..> are cross platform and others allow the build process to auto-select the correct include file for the current target port and platform (console).

For example, the following can be used

#include <gbdk/platform.h>
#include <gbdk/metasprites.h>

Instead of

#include <gb/gb.h>
#include <gb/metasprites.h>


#include <sms/sms.h>
#include <sms/metasprites.h>

Cross Platform Example Projects

GBDK includes an number of cross platform example projects. These projects show how to write code that can be compiled and run on multiple different consoles (for example Game Boy and Game Gear) with, in some cases, minimal differences.

They also show how to build for multiple target consoles with a single build command and Makefile. The Makefile.targets allows selecting different port and plat settings when calling the build stages.

Cross Platform Asset Example

The cross-platform Logo example project shows how assets can be managed for multiple different console targets together.

In the example utility_png2asset is used to generate assets in the native format for each console at compile-time from separate source PNG images. The Makefile is set to use the source PNG folder which matches the current console being compiled, and the source code uses set_native_tile_data() to load the assets tiles in native format.

Porting From Game Boy to Analogue Pocket

The Analogue Pocket operating in .pocket mode is (for practical purposes) functionally identical to the Game Boy / Color though it has a couple changes listed below. These are handled automatically in GBDK as long as the practices outlined below are followed.

Official differences:

  • Altered register flag and address definitions
  • Different logo data in the header at address 0x0104:
    • 0x01, 0x10, 0xCE, 0xEF, 0x00, 0x00, 0x44, 0xAA, 0x00, 0x74, 0x00, 0x18, 0x11, 0x95, 0x00, 0x34, 0x00, 0x1A, 0x00, 0xD5, 0x00, 0x22, 0x00, 0x69, 0x6F, 0xF6, 0xF7, 0x73, 0x09, 0x90, 0xE1, 0x10, 0x44, 0x40, 0x9A, 0x90, 0xD5, 0xD0, 0x44, 0x30, 0xA9, 0x21, 0x5D, 0x48, 0x22, 0xE0, 0xF8, 0x60

Observed differences:

  • MBC1 and MBC5 are supported, MBC3 won't save, the HuC3 isn't supported at all (via JoseJX)
  • The Serial Link port does not work
  • The IR port in CGB mode does not work as reliably as the Game Boy Color

In order for software to be easily ported to the Analogue Pocket, or to run on both, use the following practices.

Registers and Flags

Use API defined registers and register flags instead of hardwired ones.

Boot logo

As long as the target console is set during build time then the correct boot logo will be automatically selected.

Porting From Game Boy to Mega Duck / Cougar Boy

The Mega Duck is fairly similar to the classic Game Boy. It has a couple altered register flag and address definitions, no boot logo and a different startup/entry-point address. In order for software to be easily ported to the Mega Duck, or to run on both, use the following practices.

Registers and Flags

Use API defined registers and register flags instead of hardwired ones

Porting From Game Boy to SMS/GG

Tile Data and Tile Map loading

Tile and Map Data in 2bpp Game Boy Format

  • set_bkg_data() and set_sprite_data() will load 2bpp tile data in "game boy" format on both GB and SMS/GG.
  • On the SMS/GG set_2bpp_palette() sets 4 colors that will be used when loading 2bpp assets with set_bkg_data(). This allows GB assets to be easily colorized without changing the asset format. There is some performance penalty for using the conversion.
  • set_bkg_tiles() loads 1-byte-per-tile tilemaps both for the GB and SMS/GG.

Tile and Map Data in Native Format

Use the following api calls when assets are avaialble in the native format for each platform.


  • GB/AP: loads 2bpp tiles data
  • SMS/GG: loads 4bpp tile data


  • GB/AP: loads 1-byte-per-tile tilemaps
  • SMS/GG: loads 2-byte-per-tile tilemaps

There are also bit-depth specific API calls:

Emulated Game Boy Color map attributes on the SMS/Game Gear

On the Game Boy Color, VBK_REG is used to select between the regular background tile map and the background attribute tile map (for setting tile color palette and other properties).

This behavior is emulated for the SMS/GG when using set_bkg_tiles() and VBK_REG. It allows writing a 1-byte tile map separately from a 1-byte attributes map.

Tile map attributes on SMS/Game Gear use different control bits than the Game Boy Color, so a modified attribute map must be used.

Hardware Comparison

The specs below reflect the typical configuration of hardware when used with GBDK and is not meant as a complete list of their capabilities.


  • Sprites:
    • 256 tiles (upper 128 are shared with background) (amount is doubled in CGB mode)
    • tile flipping/mirroring: yes
    • 40 total, max 10 per line
    • 2 x 4 color palette (color 0 transparent). 8 x 4 color palettes in CGB mode
  • Background: 256 tiles (typical setup: upper 128 are shared with sprites) (amount is doubled in CGB mode)
    • tile flipping/mirroring: no (yes in CGB mode)
    • 1 x 4 color palette. 8 x 4 color palettes in CGB mode
  • Window "layer": available
  • Screen: 160 x 144
  • Hardware Map: 256 x 256


  • Sprites:
    • 256 tiles (a bit less in the default setup)
    • tile flipping/mirroring: no
    • 64 total, max 8 per line
    • 1 x 16 color palette (color 0 transparent)
  • Background: 512 tiles (upper 256 are shared with sprites)
    • tile flipping/mirroring: yes
    • 2 x 16 color palettes
  • Window "layer": not available
  • SMS
    • Screen: 256 x 192
    • Hardware Map: 256 x 224
  • GG
    • Screen: 160 x 144
    • Hardware Map: 256 x 224

Safe VRAM / Display Controller Access


  • VRAM / Display Controller (PPU)
    • VRAM and some other display data / registers should only be written to when the STATF_B_BUSY bit of STAT_REG is off. Most GBDK API calls manage this automatically.


  • Display Controller (VDP)
    • Writing to the VDP should not be interrupted while an operation is already in progress (since that will interfere with the internal data pointer causing data to be written to the wrong location).
    • Recommended approach: Avoid writing to the VDP (tiles, map, scrolling, colors, etc) during an interrupt routine (ISR).
    • Alternative (requires careful implementation): Make sure writes to the VDP during an ISR are only performed when the _shadow_OAM_OFF flag indicates it is safe to do so.