Game Boy Emulator

An emulator of the original Nintendo Game Boy™.

Overview

This repository provides an emulator for the original Nintendo Game Boy™. Rather than trying to compete with many existing emulators, such as SameBoy and BGB, this implementation has started as and is an educational exercise as likely one of the best ways to understand how in particular a CPU works. Moreover, it is far from complete and still work in progress.

Requirements

The implementation has been done using the C++20 standard. Besides that, it utilises the SFML libraries for the user interface. However, at this stage, we require SFML version 2 due to the introduction of some breaking changes in later versions.

Usage

The emulator can be built using the CMake build system as follows:

mkdir build
cd build
cmake ..
cmake --build .

Importantly, due to copyright, this repository does not contain the original boot rom or cartridge roms. Those must be acquired elsewhere and provided when starting the programme via command-line arguments. As a matter of fact, the boot rom is not strictly necessary.

Example

In its current state, this emulator passes all of Blargg's CPU instruction behaviour tests.

Assuming the DMG-01 boot rom is located at data/DMG-01-ROM.gb (MD5 hash: 32fbbd84168d3482956eb3c5051637f5) and Blargg's test roms at data/test-roms/blargg/, the following executes the test rom for special instructions.

./emulator --boot-rom=data/DMG-01-ROM.gb --cartridge=data/test-roms/blargg/cpu_instrs/individual/01-special.gb

or

./emulator --cartridge=data/test-roms/blargg/cpu_instrs/individual/01-special.gb

References

In implementing this emulator, I have drawn on many references that describe the inner workings of the Game Boy™. In the following, I list a few in the hope that others might benefit from it.

• Pan Docs
• Game Boy™ CPU Manual
• "DMG-01 - How to Emulate a Game Boy" by Ryan Levick
• "Game Boy: Complete Technical Reference" by Joonas Javanainen
• "The Cycle-Accurate Game Boy Docs" by Antonio Niño Díaz
• emudev Blog by LilaQ
• RealBoy Blog by Sergio G. Del Real
• Emulation Programming by CodeSlinger
• "gbops, an accurate opcode table for the Game Boy" by Skyler Ross
• "GameBoy Opcode Summary" by Jeff Frohwein
• "A journey into GameBoy emulation" by Roberto Vaccari
• "Game Boy boot sequence" by Scott Knight
• "Gameboy 2BPP Graphics Format" by Marcus Huderle

Finally, I found Gameboy Doctor by Robert Heaton an excellent tool for debugging the implementation of the CPU.