Retro Boy is a simple Game Boy emulator written in Rust that can be played on the web. Try it here.

Introduction

Retro Boy is a cycle-accurate Game Boy emulator written in Rust. It uses wasm-pack to translate the Rust code into WebAssembly so it can be played on the web. The web frontend then uses Web Audio API and HTML Canvas for audio and graphics. It also leverages the browser's local storage to persist cartridge RAM data for battery-backed MBC cartridges.

Features

• Accurate CPU that passes all JSON CPU tests
• Accurate audio emulation
• Graphics emulation built using a scanline-based renderer
• MBC1, MBC3, MBC5, and HuC1 support
• RTC support for MBC3 cartridges
• Cartridge RAM that persists to browser local storage for battery-backed cartridges
• Support for GameShark or GameGenie cheats
• A web frontend that supports:
  • Fullscreen mode
  • Pausing/resuming
  • Selectable monochrome or color modes
  • Customizable key map for game controls
  • Management and enabling/disabling of game cheat codes
  • A mobile-friendy responsive design

How to Compile to WebAssembly

To compile the implementation to WebAssembly, you will first need to install wasm-pack with the command cargo install wasm-pack if you haven't done so already. Then, run sh ./build-wasm.sh to build the core project and generate the Javascript binding code in the web frontend directory.

Web Frontend

The web frontend for this emulator is a React/TypeScript app designed with Material UI. It is located in the frontends/web folder. The UI provides the ability to load a ROM as well as play, pause, or reset the emulator. It also provides a fullscreen mode.

To run the web frontend:

1. Compile the Rust code to WebAssembly and generate the Javascript binding code as described in the "How to Compile to WebAssembly" section.
2. When the binding code is generated, it will be added to the frontends/web/src/core directory.
3. Run yarn install in the frontends/web directory to install all dependencies.
4. Run yarn start in the same directory to run the application locally.

Screenshots

Test ROMs

This emulator passes the following test suites from Blargg's test ROM collection:

1. CPU instruction tests
2. CPU instruction timing tests
3. Memory timing tests
4. Memory timing tests 2
5. Interrupt timing tests (CGB)
6. APU tests (DMG)
7. APU tests (CGB)

Additionally, this emulator passes all JSON CPU tests, and only some tests from the Mooneye test ROM collection.

Test Suite

This project holds a fairly extensive test suite, as the bulk of the logic was designed using a TDD approach. There are a lot of tests that exercise CPU opcodes, and basic tests that exercise the GPU. Run cargo test to run the test suite.

Helpful Resources

For convenience, here is a list of the resources I used to build this emulator:

1. Gameboy CPU Manual
2. Pan Docs
3. Blargg's Test ROM Collection
4. Gameboy Doctor
5. Imran Nazar's Gameboy Emulator Tutorial