wtjones / awesome-gbdev

A curated list of Game Boy development resources such as tools, docs, emulators, related projects and open-source ROMs.

Awesome Game Boy Development

Join us on Discord

A curated list of awesome Game Boy (Color) Development resources, tools, docs, related projects and open-source ROMs. Inspired by the awesome list thing.

Contents

• Intro
  • Disambiguation
• Community
• Documentation
  • Misc
  • Cheatsheets, Tables
  • Hardware
  • Game Boy Color
  • Peripherals
  • Cartridges
• Emulator Development
  • Testing
  • Open Source Emulators
• Software Development
  • Assemblers
  • Compilers
    • Experimental/Proof of Concepts
  • Emulators
  • Tools
• Programming
  • ASM
    • Timings
    • Boilerplates
  • C
  • Syntax highlighting packages
• Games
  • ASM
  • C
  • Hack ROMs
  • Demos
• ROMs Disassembly
  • Articles and tools
• Related projects
  • Directories
  • Websites
• About
  • Contribute
  • License
  • Acknowledgements
  • Sponsors

Intro

• The Game Boy, a hardware autopsy.
• The Ultimate Game Boy Talk.
• Emulation of Nintendo Game Boy - Overview of the Game Boy hardware with the perspective of building an emulator.
• To C Or Not To C - Overview of the Game Boy's capabilities, discussing the pros and cons of the available development tools, and providing tips to write more efficient code.

Disambiguation

Although this documentation is focused on the original (1989) Game Boy (DMG), the Game Boy Color (GBC) and Super Game Boy (SGB) are very similar systems, with few important distinctions, such as:

• Different hardware specifications
• Specific hardware and software features
• Specific registers
• Specific bugs and exploitable behaviours

If you aim to develop your software for SGB or GBC, or you want to know how it runs on the other systems, you may want to take advantage and adapt to these differences, check the Game Boy Color category and look for specific references to GBC/CGB and SGB.

Community

• gbdev Discord Server
• #gbdev on EFnet - IRC channel.
• gbdev.gg8.se Wiki
• devrs.com/gb - Old home of the scene: examples, sources, complete documentation, guides, tutorials and various tools.

Documentation

• Game Boy Programming Manual - Official Game Boy programming and hardware manual by Nintendo.
• Pan Docs - Historical comprehensive technical reference, wikified, corrected and updated. Original version.
• The Cycle-Accurate Game Boy Docs - A precise documentation by AntonioND to make a cycle-accurate Game Boy emulator.
• Game Boy: Complete Technical Reference by Gekkio.

Misc

• Introduction to Game Boy Hacking - Workshop introducing basic assembly, debugging and reverse engineering.
• Everything You Always Wanted To Know About GAME BOY - but were afraid to ask
• GBSOUND.txt - A document detailing the Game Boy sound engine.
• GB Instructions Game Boy Assembly commands.
• GB ASM Tips - Some tips for coding in Assembly by Jeff Frohwein.
• ASMotor Manual - A reference for RGBDS.
• ASMotor v1.10 documentation
• gbdev FAQs - Must read by Jeff Frohwein.
• Game Boy Bootrom - Commented dump of the DMG bootrom.
• GB Technical Information - Some old code resources.
• Differences between the Z80 and the gameboy's processor
• Gameboy 2BPP Graphics Format - Information on how the Game Boy interprets VRAM tile data to color pixels.

Cheatsheets, Tables

• Game Boy Crib Sheet - A handy printable reference sheet with ASM opcodes, memory locations, and much more (repository).
• OP Codes cheatsheet
• rednex gbz80 opcode reference
• Opcode table
• Opcode table with timings and flags
• Game Boy CPU Instruction Set Sheet (GCISheet) - Cheatsheet for the available Instruction Set.

Hardware

• DMG Schematics - Hardware schematics.
• The Game Boy Project - Provides a study on the hardware and detailed constructional information for the implementation of three 8-bit bidirectional parallel ports.
• Related custom hardware - by Gekkio.
• ESP8266 GB Dev Board - Dev board for Game Boy accessories development, powered by ESP8266.
• ESP8266 GB Printer - A device that emulates the GB Printer and lets you retrieve images using WiFi.
• fruttenboel - Page with loads of information on the hardware, custom boards to interface with the console and other related projects.
• Game Boy hardware database - Data and photos of various types of Game Boy consoles.

Game Boy Color

• Game Boy Color Bootstrap ROM
• Unused Palettes
• GBC colorization palettes in the BIOS
• High resolution GBC schematics
• GameBoy Color Boot ROM Disassembly

Peripherals

• Game Boy Camera RE - Documentation about GB Camera and tools used to reverse engineer it by using Arduino UNO.
• Creating photo realistic images with neural networks and a Gameboy Camera
• The Game Boy Printer - An in-depth technical document about the printer hardware, the communication protocol and the usual routine that games used for implementing the print feature.
• Ben Heck Reverse Engineers Game Boy Printer (Errata: the used thermal paper is expired, 4 colors are actually printable).
• Arduino Game Boy Printer Emulator - Emulating a Game Boy Printer via the Game Boy Link cable with an Arduino Nano.
• Mobile Game Boy Adapter
• GB KISS LINK MODEM

Cartridges

• AntonioND's docs - Corrected schematics and infos on cartridge header data.
• Gekkio's Game Boy cartridge types - An overview on existing cartridge types.
• Gekkio's cartridge analysis:
  • DMG-BEAN-02;
  • MBC1;
  • no MBC.
• Game Boy Cartridges Schematics - Schematics for MBC2 and MBC3 types.
• Cartridges PCB photos
• Reiner Ziegler's Game Boy page - Commercial and homemade programmable cartridges and programming systems. Tutorials, wiring and schematics provided.
• MBC1+RAM+Battery cartridge Schematic - First schematics by Jeff Frohwein.
• MBC1 and MBC2 cartridges circuits and explanation on how these MBC actually bank switch and control RAM.
• GB Rom List - Navigable table of every GB game released with details on their cartridges.
• Game Boy cartridge PCB photos
• Emulating a GameBoy Cartridge - Emulating the functionality of a Game Boy cartridge with the development board STM32F4.
• Wolf - Game Boy cartridge with co-processor.

Emulator Development

• Reverse Engineering fine details of Game Boy hardware (errata) - 43 minutes talk by Gekkio given at Disobey 2018.
• Building a Game Boy emulator in JavaScript - Step by step tutorial.
• Writing a Game Boy emulator, Cinoop
• RealBoy Emulator - A series of posts about the design and implementation of the RealBoy Emulator.
• Codeslinger - Another series of posts documenting the building of an emulator.
• Why did I spend 1.5 months creating a Gameboy emulator? - Blog post.
• binjgb rewind - Implementing a rewind feature.
• Emulation Accuracy
• Decoding Gameboy Z80 opcodes - How to algorithmically decode gameboy instructions as opposed to writing one huge switch-case statement for over 500 instructions.
• Porting a GO Game Boy emulator to WebAssembly

Testing

• Blargg's test roms
• Gekkio's test roms
• SameSuite
• GB Accuracy Tests
• 144p Test Suite - Port of Artemio Urbina's 240p Test Suite to the Game Boy.

Open Source Emulators

Software Development

Assemblers

• RGBDS - Assembler and linker package. Documentation.
• wla-dx - Yet Another GB-Z80/Z80/.. Multi Platform Cross Assembler Package. Documentation.

Compilers

• GBDK - A set of tools that enable to develop in C. Includes a set of libraries for the most common requirements and generates ready ROM files. Documentation.
  • gbdk-osx - Patched GBDK 2.96a for the latest compilers on OS X.
  • gbdk-n - Aims to update the gbdk libraries to be compatible with new versions of SDCC and provide helpers for building roms. Does not support ROM banking, thus limiting ROM size to 32K.
• clang-gbz80 - Clang port to the GBZ80 CPU.

Experimental/Proof of Concepts

• Wiz - A high-level assembly language for writing homebrew on retro console platforms (Game Boy, NES, Atari 2600, and more).
• gbforth - A Forth-based Game Boy development kit.
• gbasm - A JavaScript based compiler for Game Boy z80 assembly code.
• tniASM - Macro Assembler.
• Assembler - Assembler written in Swift.
• llvm-gbz80 - LLVM port to the GBZ80 CPU (similar to the deprecated euclio/llvm-gbz80).

Emulators

• BGB - Powerful Game Boy emulator and debugger. Provides an accurate hardware emulation.
• SameBoy - Accurate emulator with a wide range of powerful debugging features.
• Mooneye GB - Research project and emulator in Rust.
• Gambatte - Open-source, cross-platform and accurate emulator for Game Boy and Game Boy Color.

A lot more of emulators, written in various languages/stacks, can be found in the Open Source emulators list.

Tools

• ZGB - A little engine for creating games for the original Game Boy (expands gbdk, more info here).
• DevSound - Sound driver embeddable in homebrews which supports pulse width manipulation, arpeggios, and multiple waveforms.
• Carillon Player - Music Engine for Game Boy & Game Boy Color.
• Game Boy Tile Data Generator - HTML5 / JS web application that will convert bitmap images to hexadecimal data appropriate for use in tile based graphical applications, specifically GB.
• Harry Mulder's GB Development - Some sources and home of Game Boy Tile Designer and Game Boy Map Builder tools.
• GBTiles - Converts .GBR files created with Harry Mulder's Tile Designer (GBTD) and .GBM files created with Harry Mulder's Map Builder (GBMB) to different formats for use with the Game Boy and GBDK.
• GBT PLAYER - A music player library and converter kit for Game Boy that can be used with RGBDS.
• ROM Header Utility - An online tool to inspect and modify a ROM's header data, including the logo.
• gbcamextract - Extracts photos from Game Boy Camera saves.
• GBExtended - C library extending gbdk.
• GBZ80 to items - An online converter, translates Game Boy assembly into Pokémon R/B/Y items (Source).
• bmp2cgb - Graphics converter for Game Boy Color development providing real time palette adjustments.
• png2gb - CLI tool to convert image file to game boy .c array.
• gbdk-lib-extension - A small set of sources and tools for the Game Boy Development Kit by Michael Hope.
• GB-convert - Game Boy tile conversion and map editor tool (converts to assembly).
• cart-dumper - Game Boy Cartridge Dumper ROM.
• Game Boy LCD sniffing - Sniff your Game Boy's LCD using a logic analyzer.
• Dot Matrix Game Editor - An IDE for Game Boy programming in a C-like language called GBL, with many other features like tile and map extraction, WLA-DX assembly, and more.
• brewtool - A collection of primitive editor/converter tools for making assets used with homebrew ROM development.
• Game Boy Text Tools - Set of tools for text manipulation and translation of Game Boy ROMs written in NodeJS
• mmlgb - A MML parser and GBDK sound driver for the Nintendo Game Boy.
• XPMCK - An MML-based music compiler with support for Game Boy & Game Boy Color.
• mgbdis - Game Boy ROM disassembler with RGBDS compatible output.
• Retr0 GB - An engine for creating games (expands GBDK).
• awake - Game Boy decompiler.
• swapdump - Diagnostic utility for Game Boy flashcarts.
• Gameboy-LinkUp - Game Boy LinkUp serial cable networking project.

Programming

ASM

• gb asm tutorial - Step by step tutorial, building several ROMs to accompany its explanations.
• ASMSchool - A set of lessons by Duo about coding in Assembly for GB/GBC and disassembling.
• hardware.inc - Standard include file containing Game Boy hardware definitions for use in RGBDS projects.
• dev'rs ASM section - A lot of working demos and sources.
• Assembly tutorial by David Pello - Good document to learn to produce working asm code for gb. Brief explanations of many important topics. Many examples with commented source code.
• assemblydigest - Exploring Game Boy programming techniques:
  • Making an Empty Game Boy ROM (in RGBDS)
  • Making an Empty Game Boy ROM (in Wiz)
  • Making Art for the Game Boy
  • Helpful Libraries
• Beginner's Guide to Reverse Engineering GB - Some starting tips on disassembling and reverse engineering.
• FlappyBoy: Making a simple Game Boy Game
• Super Game Boy development - Step by step tutorial to implement Super Game Boy features (frame and palettes).
• GameBoy programming tutorial: Hello World! - Step by step tutorial.

Timings

• Game Boy DMA transfer routines - Understanding and using DMA routines.
• Nitty Gritty Gameboy Cycle Timing
• Mode3 Sprite Timing
• GameBoy Color DMA-Transfers v0.0.1
• STAT interrupt timings
• Video Timing

Boilerplates

• gb-template - A template with basic functions such as joypad input, DMA transfers, and map/tile data loading.
• rgbds-template - Basic hello-world example for Game Boy using RGBDS.
• Game Boy Assembly Language Primer - Simple template code with memory defines, copy routines and IBM font tilemap.
• bootstrap.gb - An example Game Boy project.
• Gameboy Boilerplate - Boilerplate project to move quicker into the actual assembly code for your game.

C

• 8-Bit Wonderland - Well-written introductory document about how the Game Boy works and how to start developing working code for it.
• Grooves Game Boy Programming - A complete set of lessons about implementing various game mechanics in a Game Boy game.
• How to Write a Simple Side Scrolling Game - Old (but still relevant) tutorial.
• Just another simple tutorial
• GBDK Tutorial - Fairly minimal game demo for getting started with GBDK.
• GBDK Sprite - Presents a workflow for getting multiple sprites to display and animate.
• GBDK Color - Extends your knowledge of basic spriting on the Game Boy by adding colors to sprites, backgrounds and the window layer.
• GBDK Joypad - Details the use of the joypad with GBDK.
• Game Boy home of Flavor - Some full games and sources.
• GBDK Configuring and Programming Tutorial - Configuring GBDK, Using Tiles, Colliding Sprites, GBTD, GBMB, Memory Management and ROM Banking.
• Simplified GBDK examples

Syntax highlighting packages

• Atom language package for RGBASM - Atom syntax highlighting for RGBDS assembly.
• gbz80-highlight - Notepad++ and gedit syntax highlighting files for RGBDS assembly.
• Vim syntax file for the Game Boy assembler RGBASM - Vim syntax highlighting for RGBDS assembly.
• Vim syntax file for RGBDS - Another Vim syntax highlighting file for RGBDS assembly.
• rgbds_textmate - Some syntax highlighting rules for coding in Z80 assembly as a Textmate language plugin. Works in Sublime Text 2 and 3. The syntax is particularly designed for RGBDS and Game Boy-specific Z80 instructions.
• Z80 Assembly support for Visual Studio Code
• rgbds-vscode - Visual Studio Code language extension for RGBDS GBZ80 Assembly

Games

• Homebrew Hub - Every unofficial homebrew ever produced for Game Boy playable online (mobile/touch too): a community-lead attempt to collect, archive and save every unofficial game, homebrew, demo, patch, hackrom for Game Boy (Color) produced by the community through years of passionate work.
• Infinity - RPG developed by Affinix Software primarily between the years 1999 and 2001. The game never found a publisher and was eventually canceled. Got recently released with the full source, development tools and workflows.

ASM

• RedPlusPlus - An upgrade to Pokémon Red. Fixes several bugs and adds a lot of new features.
• Tuff
• 2048-gb
• Snake
• PlantBoy
• Lazerpong
• Geometrix
• µCity
• Carazu
• Snake-gb
• GB303 - GB303 wavetable-based TB-303 style synthesizer for the Nintendo Game Boy.
• Sushi
• Flappy-boy-asm
• kupman and some other projects
• Adjustris
• exeman
• Aevilia
• GBSlides - A simple Game Boy Powerpoint-like slides viewer.
• Pokered-gbc - Pokémon Red remade with full GBC support.
• ToyToy
• StefaN - Fourway Breakout clone.
• Galaxia
• desgb - DES encryption.
• superhappyfunbubbletime

C

• FlappyBoy
• flappybird-gameboy
• fbgb
• Novascape
• Squishy the Turtle
• Quadratino
• Doctor How
• Super Princess' 2092 Exodus
• GBsnake
• gb-mines
• oranges
• red hot princess carnage
• loderunner
• Hives
• Bubble Factory - Vanilla SDCC (no gbdk).
• GBC Atari Boxing - Atari 2600 Boxing clone for the Game Boy (Color).
• GB raycaster, Vision-8 and some other projects
• Tobu Tobu Girl - An arcade platformer for the Game Boy.
• Burly Bear vs. The Mean Foxes (GBC port)
• PostBot
• Guns & Riders

Hack ROMs

• Trainin' in a Winter Wonderland (Pokemon Gold (U))

Demos

• Back to Color
• beach-gbc
• CUTE DEMO
• 10 PRINT Game Boy
• Roboto Demo

ROMs Disassembly

• Pokémon Red/Blue
• Pokémon Crystal
• Pokémon Yellow
• Pokémon Gold and Silver
• Pokémon Pinball
• Pokémon TCG
• pokegold-spaceworld - Pokémon Gold and Silver 1997 Space World demo.
• Link's Awakening DX
• Oracle of Ages
• Tetris - Based on Jeff Frohwein's original disassembly.
• FX Hammer
• Harvest Moon 3

Articles and tools

• Reverse engineering Kirby's Dreamland 2
• pokemontools - a python module that provides various reverse engineering components for various Pokémon games.
• Reverse Engineering a Gameboy ROM with radare2 - A walkthrough to reverse engineer a Game Boy ROM challenge using radare2.
• Disassembling Link's Awakening - A series of blog posts about disassembling Link's Awakening DX.
• Reverse Engineering the GameBoy Tetris
• DMA hijacking - A simple technique that allows you to run custom code in most GB/SGB/CGB games, provided you have an ACE exploit.

Related projects

• ArduinoBoy - Serial communication (MIDI) from an Arduino to the Game Boy for music applications such as LittleSoundDJ, Nanoloop, and mGB.
• papiGB - Game Boy Classic fully functional FPGA implementation from scratch.
• fpgaboy - Implementation Nintendo's Game Boy console on an FPGA.
• Piglet - A LUA-driven AI that plays classic Game Boy color games using experimentation. In active development.
• Gatesboy - Non-gaming purposes applications development.
• Ostrich - A Game Boy Sound System player written in Swift.
• mGB - A Game Boy cartridge program that enables the Game Boy to act as a full MIDI supported sound module.
• GBVisualizer - Demonstrating the use of two undocumented Game Boy Color registers, nicknamed PCM12 (FF76) and PCM34 (FF77), which can be used to read the current PCM amplitude of the 4 APU channels.
• GBVideoPlayer - A technical demo demonstrating how the Game Boy LCD controller can be hacked to make a Game Boy Color play a full motion video in color, together with music.
• ArduinoGameBoy - Arduino based Game Boy cartridge reader and writer.
• gameboy-brainfuck - Brainf*ck interpreter.
• gbfk - Brainf*ck interpreter, with input.
• gb-save-states - Patches to add save state support to Game Boy games when playing on the original hardware.
• gbcpu - A CPU and peripherals implementing the Game Boy instruction set and functionality.
• Digitized Speech in Game Boy Games
• Sniffing Game Boy serial traffic with an STM32F4
• Virtual Game Boy Printer with an STM32F4
• Printing on the Game Boy Printer using an STM32F4
• Pokemon Pocket Computer: - What is it and how to use it to make cheat codes.
• Booting the Game Boy with a custom logo - Bypassing the Nintendo logo check.
• Making a Game Boy game in 2017: A "Sheep It Up!" Post-Mortem (part 1, part 2)
• Nintendo's fake logos - Every cartridge has to show the authentic logo to be considered valid and be run, but obviously some companies managed to exploit the check system.
• liblsdj - Utility library for interacting with the LSDj save format (.sav), song files (.lsdsng) and more.
• lsdpatch - Tool for modifying samples, fonts and palettes on LSDj ROM images.
• Game Boy video effects - Some little experiments using the STAT interrupt to do funny video manipulations.

Directories

• Archive of related files
• The Game Boy Archive - A library of Game Boy related software, hardware and literature. Aimed to mirror and preserve old and fragmented contributions from the last three decades.
• The Game Boy Archive - Salvage - Historical archive of software, old articles, FAQs and various documents.

Websites

• GBDK Developers - Active blog about everything related to the scene. Including features, insights and interviews.
• pdroms.de Game Boy releases.
• Game Boy Demospotting - A collection of demos.
• Handheld Underground - Unlicensed games, blog posts about Game Boy, home of the hhugboy emulator.

About

Contribute

Take a look at Contribution Guidelines.

License

Licensed under GPLv3. See LICENSE for more information.

Acknowledgements

Thanks to every contributor of this project, Jeff Frohwein, Pascal Felber, KOOPa, Pan of Anthrox, GABY, Marat Fayzullin, Paul Robson, BOWSER, neviksti, Martin “nocash" Korth, Nitro2k01, Duo, Chris Antonellis, Michael Hope, Beware, Jonathan “Lord Nightmare” Gevaryahu, Carsten Sorense, Sindre Aamås, Otaku No Zoku, GeeBee.

Sponsors

Special thanks to our friends at DigitalOcean, sponsoring the open source activites of our Game Boy Development community (announcement).