A delayed game is eventually good, but a rushed game is forever bad.
—
Shigeru Miyamoto
A cycle accurate emulator of the original 1989 Nintendo Game Boy.
Important
Consider this to be pre-alpha software. I make no guarantee of the stability of any documented APIs until the first official release.
This project aims to provide high-accuracy emulation of all major components in the SM83-based Nintendo Game Boy family of consoles. (Note that at this time, there are no plans to support the later Game Boy Advance, which has an entirely different architecture.) Each component is modular, enabling them to be easily substituted for one another. In turn, this leads to emulator instances supporting multiple implementations of core components with different accuracy/performance margins.
In accordance with the preference for modularity outlined above, the project is partitioned into the core, and various emulator frontends. Useful supporting crates are independently available as well. Also packaged in this repository are several open-source ROMs. These are used internally for testing and to demo project functionality.
Cargo — Rust's package manager — allows for a workspace of several crates to be specified within its manifest. Within this project, workspace crates are used with the structure as follows:
./
├── Cargo.lock # cargo lockfile
├── Cargo.toml # cargo manifest
├── Justfile # useful development commands
├── README.md # this document
├── ...
├── apps/ # frontend apps
├── core/ # emulation core
├── crates/ # support crates
├── docs/ # documentation
├── roms/ # open-source ROMs
├── src/ # emulation library
└── tests/ # integration tests
Tip
For downstream library users, I recommend using the top-level gameboy
crate
rather than directly using gameboy-core
, as it better structured for end
users and includes useful supporting modules.
- Implementation
- Audio (APU)
- Cartridges
- Save RAM to disk
- Support hardware
- MBC1
- MBC3
- MBC5
- Interrupts (PIC)
- Graphics (PPU)
- Functional correctness
- Background drawing
- Window overlay
- Sprite rendering
- Implementation accuracy
- Functional correctness
- Joypad
- Processor (CPU)
- Functional correctness
- Implementation accuracy
- Multi-cycle instructions
- Timed memory accesses
- Timing precision
- Timer
- Functional correctness
- Implementation accuracy
- Performance enhancements
- Real-time emulation
- Benchmark tests
- Testing
- Blargg (17/45)
- Mooneye (23/69)
- Color palette API
- Debugger API
- Breakpoints
- Instruction address (PC)
- Instruction opocode
- I/O operation (read/write)
- Softbreak (
ld b, b
) - Dynamic condition
- Memory peek/poke
- Register manipulation
- APU
- CPU
- Interrupts
- PPU
- Serial
- Timer
- Peripheral control
- Serial interface
- Breakpoints
- Exposed core API
- Frontend API
- Command-line
- Configuration file
- Re-mappable joypad
- Debugging support
- Interactive debugging
- CPU logging
- Memory rendering
- Dynamic speed changing
- Configuration file
- Cross platform (SDL)
- Native
- iOS
- macOS
- Web (WASM)
This project would not have been possible without the countless Game Boy community resources. Of these, I would like to specifically recognize the Game Boy Development community.
See the list of resources (in no particular order) used as research for this project below.
- Pan Docs: Go-to community resource documenting the inner workings of the Game Boy. "The single most comprehensive technical reference to Game Boy available to the public."
- Game Boy Architecture by Rodrigo Copetti: High-level practical
analysis of the Game Boy.
- Includes a helpful introduction to the PPU rendering pipeline.
- Game Boy: Complete Technical Reference: Summation of Gekkio's
comprehensive Game Boy research.
- Used for exact instruction timing breakdown.
- The Gameboy Emulator Development Guide: Documentation intended to
assist with development of emulators for the original DMG Game Boy.
- Used extensively for the initial PPU and timer implementations.
- Nitty Gritty Gameboy Cycle Timing: Down and dirty timing of the Game Boy's video hardware.
- Emu-Russia's DMG-01 SM83 Core Research: Verilog model with invaluable accompanying diagrams of the SM83 core.
- Test ROMs by Shay Green (a.k.a. Blargg): Classic introductory collection of test ROMs.
- Mooneye Test Suite: Comprehensive test suite for individual niche behaviours.
- dmg-acid2 by Matt Curie: Clever re-imagining of the Web Standards Project's Acid2 rendering test for the Game Boy's PPU.
This project is dual-licensed under both MIT License and Apache License 2.0. You have permission to use this code under the conditions of either license pursuant to the rights granted by the chosen license.