Mooneye GB - Game Boy Emulator

Mooneye GB is a Game Boy research project and emulator written in the Rust programming language. This project aims to provide a highly accurate and well-documented emulator for the original Game Boy.

Project Goals

Accuracy and Documentation

The primary objectives of Mooneye GB are to achieve high accuracy in emulation and to provide thorough documentation. While other emulators like Gambatte and BGB are known for their accuracy, they often lack clear documentation, making them less useful as references for emulator developers. Mooneye GB strives to fill this gap by explaining the reasons behind specific emulation behaviors.

Test ROMs

To understand the precise behavior of the Game Boy hardware, Mooneye GB involves creating numerous test ROMs. These tests help identify corner cases and document exact hardware behaviors, ensuring the emulator's accuracy.

Documentation Resource

For detailed technical information about the Game Boy, see the Game Boy: Complete Technical Reference. This reference is an invaluable resource for understanding the Game Boy's inner workings.

Non-Goals

Mooneye GB has several non-goals, including:

• CGB (Game Boy Color) support: The focus is on making the original Game Boy support robust before considering Game Boy Color.
• Debugger: There are no plans to integrate a debugger.
• User Interface: Building native UIs in Rust can be challenging, so a sophisticated UI is not a priority.

Warning

Mooneye GB is a work-in-progress (WIP) project. It requires a boot ROM to function correctly and may lag behind the latest hardware research. The focus is on accurate emulation based on thorough research rather than quick fixes.

Performance

Always compile in release mode for better performance. On an i7-3770K desktop, Mooneye GB can run ROMs at speeds of 2000% to 4000%. Without optimizations, the speed drops to 150% to 200%, which is still acceptable for development purposes.

Platforms

• Desktop: Runs well on powerful desktops but may be slow on Raspberry Pi without OpenGL acceleration.
• Android: Although runnable, the complexity of cross-compiling and the lack of touch controls make Android support impractical at the moment.

Running the Emulator

Requirements

• Rust 1.26
• SDL2 development libraries

GUI Mode

To run the emulator with a GUI:

1. cargo run --release
2. Follow the on-screen instructions.

Command-Line Mode

1. Obtain a Game Boy boot ROM and place it at $HOME/.local/share/mooneye-gb/bootroms/dmg_boot.bin.
2. cargo build --release
3. Run a Game Boy ROM with: cargo run --release -- PATH_TO_GAMEBOY_ROM.

Note for Windows: Download an SDL2 package containing SDL2.dll and place it in target/debug and target/release.

Key Mappings

Game Boy Controls

Game Boy	Key
Dpad	Arrow keys
A	Z
B	X
Start	Return
Select	Backspace

Additional Controls

Function	Key
Fast forward	Shift
Toggle performance overlay	F2