Rugby

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.

Goal

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.

Organization

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.

Workspace

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 dev commands
├── README.md        # this document
├── ...
├── apis/            # app interfaces
│  ├── cfg/          # app configuration
│  └── gbd/          # game boy debugger
├── apps/            # frontend apps
│  ├── cli/          # command-line app
│  └── web/          # web assembly app
├── arch/            # arch primitives
├── core/            # emulation core
├── crates/          # support crates
│  ├── chex/         # color hex parser
│  ├── hexd/         # hex dump printer
│  └── wrange/       # wrapping ranges
├── docs/            # documentation
├── lib/             # library frontends
│  └── retro/        # libretro port
├── roms/            # open-source ROMs
│  ├── boot/         # boot ROM images
│  ├── games/        # playable demos
│  └── test/         # test ROM images
├── src/             # top-level 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.

Components

Main components of rugby are outlined below.

• rugby: is the high-level library that provides the public API.
• rugby-arch: defines the architecture primitives for emulation.
• rugby-core: contains the implementation of emulator cores.

Interfaces

• rugby-cfg: definition of application configuration options.
• rugby-gbd: provides an interactive prompt debugging interface.

Frontends

• rugby-cli: a command-line interface application with rich configuration support and comprehensive debugging options.
• rugby-web: an online web application powered by Wasm.

Several additional frontends are planned for the future:

• rugby-ios: a native iOS application built with SwiftUI.
• rugby-sdl: a cross-platform application based upon the SDL framework.

  note: no longer planned, use rugby-cli or libretro instead.

Libraries

• libretro: implementation of the libretro API.

Testing

Rigorous integration testing is provided to validate the implementation and prevent regressions in future versions.

Suite	Passed	Failed
Acid2	17	0
Blargg	23	22
Mealybug	0	24
Mooneye	30	39

References

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.

Documentation

• 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.

Hardware

• Emu-Russia's DMG-01 SM83 Core Research: Verilog model with invaluable accompanying diagrams of the SM83 core.

Attribution

This project uses and distributes the following open-source software under the conditions of their respective licenses:

Firmware

• SameBoy's Boot ROM is included under the conditions of the MIT License (dated 29 Aug 2023). See the project here.

Games

• 2048 is included under the conditions of the zlib License (dated 29 Aug 2023). See the project here.
• Porklike is included under the conditions of the MIT License (dated 16 Oct 2024). See the project here.

Testing

• 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.

License

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.