nickdesaulniers / 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 Development resources, tools, docs, related projects and open-source ROMs. Inspired by the awesome list thing.

Here you can find everything to get started and master the development of unofficial software for the original 1989 Game Boy.

Contents

• Intro
• Community
• Documentation
  • Peripherals
  • Cartridges
• Emulator Development
  • Open-Source emulators
• Software Development
  • Assemblers
  • Compilers
  • Emulators
  • Tools
• Programming Tutorials
  • ASM
    • Glitches and exploits
    • Timings
  • C
• Open-Source Games
  • ASM
  • C
• ROMs Disassembly
• Related sites, posts and projects
• About this project
  • Contribute
  • License
  • Special Thanks

Intro

• The Game Boy, a hardware autopsy.
• The Ultimate Boy Talk.
• Emulation of Nintendo Game Boy - Overview of the Game Boy hardware with the perspective of building an emulator.

Community

• gbdev Discord Server
• #gbdev on EFnet - IRC channel.
• gbdev.gg8.se - This is basically the home of the gbdev scene. The wiki has a lot of articles from previous sites, tutorials and other documents about a lot of topics.
• devrs.com/gb - Jeff Frohwein’s page, this the main reference for everything. Almost everything is archived here: code examples and working programs(ASM and C), complete documentation and various tools.

Documentation

• Game Boy Programming Manual - Official Game Boy programming & hardware manual by Nintendo. Pretty much everything in the console is covered and explained in this manual. This should be your first and main resource to start understanding what game boy is.
• The Cycle-Accurate Game Boy Docs - A precise documentation by AntonioND to make a cicle-accurate Game Boy emulator.
• Pan Docs - The single most comprehensive technical reference to Game Boy that is available to the public.
• Everything You Always Wanted To Know About GAME BOY - but were afraid to ask
• GBSOUND.txt - A document detailing the Game Boy sound engine.
• DMG Schematics - Hardware schematics.
• 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
• wla-dx documentation - WLA DX Macro Assembler Package manual.
• GBDK libraries documentation
• gbdev FAQs - Must read by Jeff Frohwein.
• Game Boy CPU InstructionSet Sheet (GCISheet) - Cheatsheet for the available Instruction Set.
• Opcode table
• Opcode table with timings and flags
• Game Boy CPU Manual - Assembly language commands, timings and opcodes.
• OP Codes cheatsheet
• Assembly Language Programming Course - Machine and assembly language programming concepts that illustrate basic principles and techniques. Application through study of the Z80 chip and Game Boy programming assignments (Center for Research in Arts, Technology, Education, and Learning CRATEL at Withicha State University).
• 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
• Archive of related files
• fruttenboel - Page with loads of information on the actual hardware, custom boards to interface with the console and other related projects.

Peripherals

• Game Boy Camera RE - Documentation about GB Camera and tools used to reverse engineer it by using Arduino UNO.
• Creating photorealistic 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

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 homemades 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 explaination 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 GameBoy cartridge with the development board STM32F4.
• Wolf - Gameboy cartridge with co-processor.

Emulator Development

• Blargg's test roms
• Gekkio's test roms
• 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.

Open-source emulators

• Mooneye-gb - A Game Boy research project and emulator written in Rust.
• php-terminal-Game Boy-emulator - PHP Terminal
• gameboy-Online - Javascript, HTML5 canvas and JavaScript audio APIs.
• cboy - C. Mac OS X and Linux.
• weplay - Collaborative Game Boy emulation powered by JavaScript.
• giibiiadvance - A GB, GBC emulator with GB Camera support. Written in C.
• GBE+ - Built in C++ and SDL. Focused on enhancements.
• Sameboy - Portable C.
• GameYob - Emulator for Nintendo (3)DS.
• oneup-gb - C++ DMG. Currently provides SDL frontend and Retroarch integration.
• rustboy - A basic DMG emulator written in Rust, using the Piston engine for window creation and graphics.
• Gearboy - C++. iOS, Raspberry Pi, Mac, Windows and Linux.
• AndroidGameBoyEmulator
• GameLad - C++/SDL almost fully featured emulator.
• Wadatsumi - Arrow.
• Binjgb - 5kloc emulator in C that passes most of the tests.
• jgilchrist - Modern C++.
• gameboyGO - Go.
• GameBoyEmulator-GBS - C++ 14 with a single library dependency of SFML.
• PyBoy - Python. Mac, Linux and Windows.
• scimitar - Rust.
• FunGBC - F#.
• barnacleboy - Rust.

Software Development

Assemblers

• rgbds - Assembler and linker package (a fork currently updated).
• wla-dx - Yet Another GB-Z80/Z80/.. Multi Platform Cross Assembler Package.
• gbasm - A JavaScript based compiler for Gameboy z80 assembly code.
• tniASM - Macro Assembler.
• Assembler - Assembler written in Swift.

Compilers

• The Game Boy Developer's Kit (GBDK) - A set of tools that enable to develop programs for the Nintendo Game Boy system in C. Includes a set of libraries for the most common requirements and generates image files for use with a real Game Boy.
• gbdk-osx - Patched GBDK 2.96a for the latest compilers on OS X.

Emulators

• BGB - Powerful Game Boy emulator and debugger. Provides an accurate hardware emulation.
• Gambatte - Open-source, cross-platform and accurate emulator for Game Boy and Game Boy Color.

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.
• Game Boy Tile Data Generator - HTML5 / JS web application that will convert bitmap images to hexidecimal data appropriate for use in tile based graphical applications, specifically GB.
• 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.
• Harry Mulder's GB Development - Some sources and home of Game Boy Tile Designer and Game Boy Map Builder tools.
• 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 gameboy assembly into Pokémon R/B/Y items (Source)
• bmp2cgb - 8bpp bitmap converter for Gameboy Color development.

Programming Tutorials

ASM

• ASMSchool - A set of lessons by Duo about coding in Assembly for GB/GBC and disassembling.
• dev'rs ASM section - A lot of working demos and sources.
• Assembly tutorial by David Pello - Good document to actually learn to produce working asm code for gb. Brief explainations of many important topics. Many examples with commented source code (spanish only).
• Assembly tutorial by David Pello - The english version of the resource above.
• Beginner's Guide to Reverse Engineering GB - Some starting tips on disassembling and reverse engineering.
• gb-template - A template with basic functions pre-made such as joypad input, DMA transfers, and map/tile data loading.
• assemblydigest - Exploring Game Boy programming techniques.
• Reverse Engineering for Beginners - Free ebook (1060 pages) by Dennis Yurichev.
• FlappyBoy: Making a simple Game Boy Game

Glitches and exploits

• DMA hijacking - A simple technique that allows you to run custom code in most GB/SGB/CGB games, provided you have an ACE exploit. Demo video.
• Pokèmon Yellow ASM hack - Debug menu. Demo video.

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

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.

Games

• Infinity

ASM

• RedPlusPlus - An upgrade to Pokémon Red. Fixes several bugs and adds a lot of new features.
• Tuff
• 2048-gb
• Snake
• PlantBoy
• Lazerpong
• Back to Color
• Geometrix
• µCity
• Carazu
• Snake-gb
• GB303 - GB303 wavetable-based TB-303 style synthesizer for the Nintendo Gameboy.
• Pokémon Christmas
• Sushi
• Flappy-boy-asm

C

• flappybird-gb
• FlappyBoy
• flappybird-gameboy - Yet another gbdk powered Flappybird clone
• Novascape
• Squishy the Turtle
• Quadratino
• Doctor How
• Super Princess' 2092 Exodus
• GBsnake
• gb-mines
• oranges
• red hot princess carnage
• loderunner
• Hives
• Bubble Factory

ROMs Disassembly

• Sonic 1
• Pokémon Red/Blue
• Pokémon Crystal
• Pokémon Pinball
• Pokémon TCG
• Reverse engineering Kirby's Dreamland 2
• pokemontools - a python module that provides various reverse engineering components for various Pokémon games.

Related sites, posts and projects

• 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.
• The Game Boy Project - Provides a study on the hardware and detailed constructional information for the realisation of three 8-bit bidirectional parallel ports.
• gbdk-n - Aims to update the gbdk libraries to be compatible with new versions of SDCC and provide helpers for building roms.
• Wiz - A high-level assembly language for writing homebrew on retro console platforms (Game Boy, NES, Atari 2600, and more).
• Gatesboy - Non-gaming purposes applications development.
• pdroms.de Game Boy releases.
• Game Boy Demospotting - A collection of demos.
• Nintendo's fake logos - Every cartridge has to show the authentic logo to be considered valid and be runned, but obviously some companies managed to exploit the check system.
• Booting the Game Boy with a custom logo - Bypassing the Nintendo logo check.
• GBDK Developers - Active blog about everything related to the scene. Including features, insights and interviews.
• Ostrich - A Game Boy Sound System player written in Swift.
• mGB - A Gameboy cartridge program that enables the Gameboy to act as a full MIDI supported sound module.
• GBVisualizer - Demonstrating the use of two undocumented Gameboy 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 Gameboy LCD controller can be hacked to make a Gameboy Color play a full motion video in color, together with music.
• rgbgfx - A program which converts PNG images into the Game Boy's planar tile format, for eventual integration into RGBDS.
• ArduinoGameBoy - Arduino based Game Boy cartridge reader and writer.
• gameboy-brainfuck - Implementation of a brainfuck interpreter.

About

Contribute

Take a look at Contribution Guidelines.

License

Licensed under GPLv3. See LICENSE for more information.

Special Thanks

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