Dr. Thomas Tensi Paganinistraße 60
D-81247 München

Extended C Library for the Nintendo Gameboy Color

The GBExtended Library is an open source C library and extends Michael Hope's Gameboy classic library GBDK. Its main goal is to put another abstraction layer over those routines to facilitate the development of two-dimensional map-based games. It is only helpful for you when you are doing program development for that classical platform.


Basic Concepts

A 2D map-based-game consists of a rectangular map of equally sized cells. Each cell represents one kind of object at this position on the map, typically static objects like lawn, rock, water or buildings for a birds-eye-view or different floors when the map is a cross-section of a building. This means that static objects are put into the raster defined by the cells of the map.

For large maps only small parts are visible on the display of the GameBoy. The visible part of the map is defined by the map viewport and the library provides means to define the position of the viewport on the map very precisely.

Note that finally the cells have to be shown via hardware background tiles — that means 8x8 pixel bitmaps — on the GameBoy. To make the mapping easier each cell is represented by a rectangle of tiles with an integer number of tiles in the x- and y-dimension. This means that a displayed tile belongs to exactly one cell of the map.

There are also nonstatic objects called sprites. Sprites may be at arbitrary positions on the map. This means that there is a coordinate system on the map and since the sprites shall be positioned very precisely, the map coordinate system uses fixed-point-values.

Each sprite consists of several hardware sprites with arbitrary relative positions to each other. The hardware sprites are — similar to background tiles — 8x8 pixel bitmaps which overlay the background, but are partly transparent. That means that a moving object may have a non-rectangular shape and even holes.


Just moving objects across a plane of background objects is not too exciting. Another extension is that sprites and map cells may be animated.

A map animation is described by a sequence of phases for one cell called map animation schedule. Each phase tells what object kind is shown at a specific cell for how long.

The same idea goes for sprite animations. A sprite animation schedule also consists of phases which last for some time. A phase describes how the component hardware sprites are positioned, what tiles they use and whether they have some special properties (like being rotated or use some palette). As opposed to map animations which stop after some time, sprite animations are continuous. That means at the end of an animation the animation is restarted.

All the time specifications mentioned above are relative to the time unit which is the time between two frames. This is about 1/60th of a second. The implementation sends tick events to the appropriate modules whenever the frame changes and triggers the appropriate updates.

User Interaction: Keys, Windows and Dialogs

The only input from the user is via the joypad. The cursor pad and the different buttons are considered as keys. Several routines allow to check whether and which key has been pressed, to wait for some key pressed, to wait for a set of keys to be pressed or for the release of all keys. This is simply a beautification of Michael Hope's excellent module [Hope].

Text-based conversation with the user is done in a window. A window uses the complete display and provides a 20 columns by 18 rows alphanumeric display. There are standard operations available for the window like clearing, writing texts or numbers and positioning the cursor.

It is also possible to have a bordered window where the frame occupies one character width on each side. All the window routines work as before, but only on the inner drawing area to protect the border.

Based on the window module several kinds of dialogs are supported. There are routines to show a text message and two routines to show menus. The simpler menu routine allows a selection from a list, the more complicated routine uses callbacks at each menu position which take care of user key presses and change the string at the cursor position accordingly. For example this can be used for a setup dialog where properties of the game can be defined. Each line stands for some parameter and the callback routine knows the possible values and how to change them upon a keypress.


The sound capabilities of the GameBoy are abstracted by the sound module. The main focus of sound processing in this library lies on melodies oriented at the MIDI standard. A melody is a sequence of sound events. An event consists of some MIDI pitch, a volume and a channel. There are only few channels on the GameBoy: channels 0 and 1 are monophonic melody channels, channel 2 is the drum channel.

Each event has some delta time relative to the previous event. This delta time is given as a multiple of the frame interval of 1/60th second. As in MIDI a musical note is modelled by an on-event and some later off-event (with a volume of zero).

Sound processing is done within the frame gap for sound events which have been put into an event queue earlier. It is also possible to start and stop the playback of events at any time.

Basic Modules

There are additional modules providing elementary services:


You can download the following files here

Note that my loderunner game also uses the GBExtended Library.