Gekkio/mooneye-gb

A Game Boy research project and emulator written in Rust

Rust

971

704 commits

updated Mar 16, 2023

See the code

README

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.

For documentation about known behaviour, see Game Boy: Complete Technical Reference

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

Mooneye GB acceptance tests

Test	mooneye-gb
add sp e timing	👍
boot div dmg0	❌
boot div dmgABCmgb	❌
boot div S	❌
boot div2 S	❌
boot hwio dmg0	❌
boot hwio dmgABCmgb	❌
boot hwio S	👍
boot regs dmg0	👍
boot regs dmgABC	👍
boot regs mgb	👍
boot regs sgb	👍
boot regs sgb2	👍
call timing	👍
call timing2	👍
call cc_timing	👍
call cc_timing2	👍
di timing GS	👍
div timing	👍
ei sequence	👍
ei timing	👍
halt ime0 ei	👍
halt ime0 nointr_timing	👍
halt ime1 timing	👍
halt ime1 timing2 GS	👍
if ie registers	👍
intr timing	👍
jp timing	👍
jp cc timing	👍
ld hl sp e timing	👍
oam dma_restart	👍
oam dma start	👍
oam dma timing	👍
pop timing	👍
push timing	👍
rapid di ei	👍
ret timing	👍
ret cc timing	👍
reti timing	👍
reti intr timing	👍
rst timing	👍

Bits (unusable bits in memory and registers)

Test	mooneye-gb
mem oam	👍
reg f	👍
unused_hwio GS	👍

Instructions

Test	mooneye-gb
daa	👍

Interrupt handling

Test	mooneye-gb
ie push	👍

OAM DMA

Test	mooneye-gb
basic	👍
reg_read	👍
sources GS	👍

PPU

Test	mooneye-gb
hblank ly scx timing GS	👍
intr 1 2 timing GS	👍
intr 2 0 timing	👍
intr 2 mode0 timing	👍
intr 2 mode3 timing	👍
intr 2 oam ok timing	👍
intr 2 mode0 timing sprites	❌
lcdon timing GS	❌
lcdon write timing GS	❌
stat irq blocking	❌
stat lyc onoff	❌
vblank stat intr GS	👍

Serial

Test	mooneye-gb
boot sclk align dmgABCmgb	❌

Timer

Test	mooneye-gb
div write	👍
rapid toggle	👍
tim00 div trigger	👍
tim00	👍
tim01 div trigger	👍
tim01	👍
tim10 div trigger	👍
tim10	👍
tim11 div trigger	👍
tim11	👍
tima reload	👍
tima write reloading	👍
tma write reloading	👍

Mooneye GB emulator-only tests

MBC1

Test	mooneye-gb
bits bank1	👍
bits bank2	👍
bits mode	👍
bits ramg	👍
rom 512kb	👍
rom 1Mb	👍
rom 2Mb	👍
rom 4Mb	👍
rom 8Mb	👍
rom 16Mb	👍
ram 64kb	👍
ram 256kb	👍
multicart rom 8Mb	👍

MBC2

Test	mooneye-gb
bits ramg	👍
bits romb	👍
bits unused	👍
rom 512kb	👍
rom 1Mb	👍
rom 2Mb	👍
ram	👍

MBC5

Test	mooneye-gb
rom 512kb	👍
rom 1Mb	👍
rom 2Mb	👍
rom 4Mb	👍
rom 8Mb	👍
rom 16Mb	👍
rom 32Mb	👍
rom 64Mb	👍

Mooneye GB manual tests

Test	mooneye-gb
sprite priority	👍

Mooneye GB misc tests

Test	mooneye-gb
boot div A
boot div cgb0
boot div cgbABCDE
boot hwio C
boot regs A
boot regs cgb

Bits

Test	mooneye-gb
unused hwio C

PPU

Test	mooneye-gb
vblank stat intr C

License and copyright

emulator

game-boy

gameboy

gameboy-emulator

rust

Significant stargazers

(top 24 of 25)

Linda_pp

1,943 followers · starred Nov 2021

Maja Kądziołka

291 followers · starred Feb 2020

pyfisch

50 followers · starred May 2018

Nick Desaulniers

984 followers · starred Feb 2018

Similar repos

libraries/gameboy

Full featured Cross-platform GameBoy emulator by Rust. Forever boys!.

1,427

raphamorim/gameboy

The Gameboy emulator that runs everywhere (Terminal, Web, Desktop)

893

akatsuki105/magia

This emulator is OLD and BAD, please visit DawnGBA

477

michelhe/rustboyadvance-ng

RustBoyAdvance-NG is a Nintendo™ Game Boy Advance emulator and debugger, written in the rust…

671

linoscope/CAMLBOY

A Game Boy emulator written in OCaml that runs in your browser 🐫 🎮

640

smparsons/retroboy

A Game Boy emulator written in Rust.

1,037

lemoncmd/gamevoy

game boy emulator in V

abbysmal/Goodboy

A pure OCaml Gameboy emulator