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. 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.
Note
At this time, there are no plans to support the later Game Boy Advance, which has an entirely different architecture.
In accordance with the preference for modularity outlined above, the project is partitioned into the core, the debugger, 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
├── gbd/ # game boy debugger
├── roms/ # open-source ROMs
├── src/ # emulation library
└── tests/ # integration tests
Tip
For downstream library users, I recommend using the top-level rugby crate
rather than directly using rugby-core, as it better structured for end
users and includes useful supporting modules.
Main components of rugby are outlined below.
rugby: is the high-level library that provides the public API.rugby-core: contains the implementation of emulator cores.rugby-gbd: provides an interactive prompt debugging interface.
rugby-cli: a command-line interface application with rich configuration support and comprehensive debugging options.
Several additional frontends are planned for the future:
rugby-ios: a native iOS/macOS application, most likely using SwiftUI.rugby-sdl: a cross-platform application based upon the SDL framework.rugby-web: an online hosted frontend powered by Wasm.
Rigorous integration testing is provided to validate the implementation and prevent regressions in future versions.
| Suite | Passed | Failed |
|---|---|---|
| Acid2 | 0 | 17 |
| Blargg | 23 | 22 |
| Mealybug | 0 | 24 |
| Mooneye | 31 | 38 |
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.
This project uses and distributes the following open-source software under the conditions of their respective licenses:
- SameBoy's Boot ROM is included under the conditions of the MIT License (dated 29 Aug 2023). See the project here.
- A 2048 Game Boy port is included under the conditions of the zlib License (dated 29 Aug 2023). See the project here.
- Blargg's Test Suite is included under presumptive permissive licensing, though no explicit license could be found. See the project here.
- dmg-acid2 Test ROM is included under the conditions of the MIT License (dated 08 Jan 2024). See the project here.
- Mealybug Tearoom Tests is included under the conditions of the MIT License (dated 21 Apr 2024). See the project here.
- Mooneye Test Suite is included under the conditions of the MIT License (dated 06 Sep 2023). See the project here.
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.