A Game Boy research project and emulator written in Rust
RustGPL-3.0
Mooneye GB
Mooneye GB is a Game Boy research project and emulator written in Rust.
The main goals of this project are accuracy and documentation. Some existing
emulators are very accurate (Gambatte, BGB >= 1.5) but are not documented very
clearly, so they are not that good references for emulator developers. I want
this project to document as clearly as possible why certain behaviour is
emulated in a certain way. This also means writing a lot of test ROMs to figure
out corner cases and precise behaviour on real hardware.
Looking for the mooneye-gb test ROMs? They are now part of Mooneye Test Suite.
Non-goals:
CGB (Game Boy Color) support. It would be nice, but I want to make the normal
Game Boy support extremely robust first.
A debugger
A good user interface. Building native UIs with Rust is a bit painful at the
moment.
Warning:
Project is WIP
Doesn't work properly without a boot ROM
The emulator is lagging behind hardware research. I don't want to spend time
making short-lived and probably incorrect fixes to the emulator if I'm not
sure about the hardware behaviour.
Performance
Always compile in release mode if you care about performance!
On a i7-3770K desktop machine I can usually run ROMs with 2000 - 4000% speed.
Without optimizations the speed drops to 150 - 200%, which is still fine for
development purposes.
Raspberry Pi with X11 desktop works but is too slow because there is no OpenGL
acceleration.
The emulator is runnable on Android, but cross-compiling and packaging is a
huge pain and touch controls would have to be implemented, so I'm not
supporting Android at the moment.
Running the emulator
Requirements:
Rust 1.26
SDL2 development libraries for your platform must be installed
GUI
cargo run --release
Follow the instructions
Command-line
Acquire a Game Boy bootrom, and put it to $HOME/.local/share/mooneye-gb/bootroms/dmg_boot.bin
cargo build --release
cargo run --release -- PATH_TO_GAMEBOY_ROM
On Windows, also download an SDL2 package containing SDL2.dll, and put it to
target/debug and target/release.
Game Boy keys
Game Boy
Key
Dpad
Arrow keys
A
Z
B
X
Start
Return
Select
Backspace
Other keys
Function
Key
Fast forward
Shift
Toggle performance overlay
F2
Test suite
Blargg's tests
Test
mooneye-gb
cpu instrs
👍
dmg sound 2
❌
instr timing
👍
mem timing 2
👍
oam bug 2
❌
cgb sound 2
Notes:
cpu_instrs fails on MGB/SGB2 hardware and emulators emulating them correctly.
The ROM incorrectly detects the device as CGB, and attempts to perform a CPU
speed change which causes a freeze (STOP instruction with joypad disabled)
dmg_sound-2 test #10 can fail randomly on real hardware and seems to depend
on non-deterministic behaviour.
oam_bug-2 fails on all CGB, AGB, and AGS devices
cgb_sound-2 test #03 fails on CPU CGB, CPU CGB A, and CPU CGB B
