gameboy-emulator

Experimental Game Boy emulator written in Rust.

There are several frontends available for no reason but to experiment with different languages and frameworks consuming the main core written in Rust. The eframe frontend provides some debugging tools.

Disclaimer: this emulator is an experimental project for educational purposes. The development and use of emulators is legal, as long as no copyrighted content is illegally obtained. This means you are responsible for dumping your own boot ROMs and games. However, there exists free and open-source content in case you'd like to test this project and/or contribute 😊

Features

• CPU
• PPU
• APU
• Input (native only)
• Cartridge
  • No MBC
  • MBC1
  • MBC2
  • MBC3
    • MBC30
    • RTC
  • MBC5
• Saving
• Debugging UI
• More debugging UI
• Automated ROM tests (failing tests are disabled, typically with a reason)
  • blargg
  • mooneye-test-suite
  • dmg-acid2 (DMG and CGB)
  • cgb-acid2

Screenshots

boop

Repository structure

• .: Package/configuration files for all modules.
• external: External dependencies.
• core: Core modules.
  • gb-core: Main core written in Rust.
  • gb-core-c: gb-core shims for use in other languages. Contains a C/C++ header file with the function declarations.
  • gb-core-swift: Contains a Swift package that wraps gb-core-c in a Swift class.
  • gb-core-wasm: gb-core wrapper targeting WASM.
  • gb-opcode-info: Contains opcode info for use in other modules.
• platform: Language/framework specific frontends.
  • browser: Browser app written in TypeScript using Vite and React.
  • eframe: Native app written in Rust using eframe.
  • sdl2-c: Native app written in C using SDL2.
  • sdl2-rust: Native app written in Rust using SDL2.
  • sdl2-swift: Native app written in Swift using SDL2. Likely unsupported on Windows and Linux, but was briefly tested on the latter.
  • swiftui: Native app written in Swift using SwiftUI.

Setup

Rust

# Install rustup: https://www.rust-lang.org/

rustup default stable

# Arch
sudo pacman -S rust rust-src rust-wasm

wasm-pack

Required to build the browser app.

# Install wasm-pack from source
cargo install wasm-pack

# Arch
sudo pacman -S wasm-pack

# macOS
brew install wasm-pack

# npm
npm install -g wasm-pack

SDL2

Required to build the C and Swift apps.

# Arch
sudo pacman -S sdl2

# macOS
brew install sdl2

Building

# Native
cargo build

# Browser app
pnpm build # Will build the Rust dependencies as well

# Swift
cargo build --release
cd platform/sdl2-swift
swift build

Running

# Native
# Add --release after `run` if debug mode is too slow.
cargo run -- roms/rom.gb

# Native with info logs
RUST_LOG=info cargo run -- roms/rom.gb

# Browser app
pnpm i
pnpm dev

# Swift
cd platform/sdl2-swift
swift run GameBoy ../../roms/rom.gb

Tests

Check gb-core/tests for all the supported integration tests. Any failing test is commented out, typically with a reason. Unit tests are also included for some modules. Both the ALU and the instructions are being tested using sm83-test-data, so it may take a while for the tests to finish.

cargo test

todo

• Improve code and repo quality
• APU
• Input (implemented for some frontends. Needs to be improved)
• Saving
• Improve accuracy
  • Implement FIFO fetcher instead of a scanline renderer
• Better debugging UI
• More automated ROM tests
• Pass more tests
• Game Boy Color support (done? ish.)

References

• Pan Docs
• Game Boy: Complete Technical Reference
• mooneye-gb
• SameBoy
• The Cycle-Accurate Game Boy Docs
• CPU opcode reference
• A journey into GameBoy emulation