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
├── ...
├── apps/            # frontend apps
│  ├── cli/          # command-line app
│  ├── ios/          # SwiftUI iOS app
│  └── web/          # WebAssembly app
├── arch/            # arch primitives
├── bind/            # language bindings
│  ├── swift/        # Swift (UniFFI)
│  └── wasm/         # WebAssembly
├── core/            # emulation core
├── crates/          # support crates
│  ├── bfmt/         # bytes formatter
│  ├── chex/         # color hex parser
│  ├── hexd/         # hex dump printer
│  └── orng/         # wrapping ranges
├── docs/            # documentation
├── examples/        # example frontends
├── extras/          # extra emulator APIs
│  ├── cfg/          # app configuration
│  ├── gbd/          # game boy debugger
│  └── pal/          # palette presets
├── 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.

Modules

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.

Extras

• rugby-cfg: definition of app configuration options.
• rugby-gbd: provides an interactive prompt debugger.
• rugby-pal: collection of DMG color palette presets.

Frontends

• rugby-cli: a command-line interface application with rich configuration and comprehensive debugging.
• rugby-ios: a native iOS application built with SwiftUI.
• rugby-web: an online web application powered by Wasm.

Bindings

• rugby-swift: foreign function interface to Swift (UniFFI).
• rugby-wasm: cross-compilation with bindings to WebAssembly.

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

Credits

This project would not have been possible without the people, projects, and resources that contributed to my learning and make development so fun and easy.

See the Credit Roll for a full list.

Privacy

The project does not collect or transmit any data. Any data used by the project remains solely on your device.

See the Privacy Policy for full details.

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.