README.markdown

Mooneye GB

Mooneye GB is a Game Boy 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.

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 good debugger. A primitive debugger exists for development purposes, and it is enough.
• A 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

Accuracy

This project already passes Blargg's cpu_instrs, instr_timing, and mem_timing-2 tests.

Things that need significant work:

• GPU emulation accuracy
• APU emulation in general

There's tons of documentation and tons of emulators in the internet, but in the end I only trust real hardware. I follow a fairly "scientific" process when developing emulation for a feature:

1. Think of different ways how it might behave on real hardware
2. Make a hypothesis based on the most probable behaviour
3. Write a test ROM for such behaviour
4. Run the test ROM on real hardware. If the test ROM made an invalid hypothesis, go back to 1.
5. Replicate the behaviour in the emulator

All test ROMs are manually run with these devices:

Device	Model	Mainboard	CPU
Game Boy	DMG-01	DMG-CPU-04	DMG CPU B
Game Boy Pocket	MGB-001	MGB-ECPU-01	CPU MGB
Game Boy Pocket	MGB-001	MGB-LCPU-01	CPU MGB
Super Game Boy	SNSP-027	SGB-R-10	SGB-CPU-01
Super Game Boy	SHVC-027	SGB-R-10	SGB-CPU-01
Super Game Boy 2	SHVC-042	SHVC-SGB2-01	CPU SGB2
Game Boy Color	CGB-001	CGB-CPU-03	CPU CGB C
Game Boy Color	CGB-001	CGB-CPU-04	CPU CGB D
Game Boy Color	CGB-001	CGB-CPU-05	CPU CGB D
Game Boy Advance	AGB-001	AGB-CPU-10	CPU AGB A
Game Boy Advance SP	AGS-001	C/AGS-CPU-21	CPU AGB B E
Game Boy Advance SP	AGS-101	C/AGT-CPU-01	CPU AGB B E

These devices will also be used, but results for old tests have not yet been verified:

Device	Model	Mainboard	CPU
Game Boy	DMG-01	DMG-CPU-02	DMG CPU A
Game Boy	DMG-01	DMG-CPU-06	DMG CPU B
Game Boy Color	CGB-001	CGB-CPU-02	CPU CGB B
Game Boy Color	CGB-001	CGB-CPU-06	CPU CGB E
Game Boy Advance	AGB-001	AGB-CPU-01	CPU AGB

For now, the focus is on DMG/MGB/SGB/SGB2 emulation, so not all tests pass on CGB/AGB/AGS or emulators emulating those devices.

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

GUI

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

Command-line

1. Acquire a Game Boy bootrom, and put it to $HOME/.mooneye-gb/dmg_boot.bin
2. cargo build --release
3. 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

Accuracy comparison

Versions used:

• mooneye-gb (master)
• BGB 1.5.2
• Gambatte 2015-03-23 (f9fb003)
• GiiBiiAdvance 2015-05-16 (dbf669a)
• Higan v098 (in Game Boy mode, except for SGB/SGB2-specific test ROMs)
• KiGB 2.05
• MESS 0.163

Blargg's tests

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
cpu instrs	👍	👍	👍	👍	👍	❌	👍
dmg sound 2	❌	👍	👍	❌	❌	❌	❌
instr timing	👍	👍	👍	👍	👍	❌	👍
mem timing 2	👍	👍	👍	👍	👍	❌	👍
oam bug 2	❌	❌	❌	❌	❌	❌	❌

Mooneye GB acceptance tests

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
add sp e timing	👍	❌	👍	❌	👍	❌	❌
boot hwio G	👍	👍	👍	❌	👍	❌	❌
boot regs dmg	👍	👍	👍	👍	👍	👍	👍
call timing	👍	❌	👍	❌	👍	❌	❌
call timing2	👍	❌	👍	❌	👍	❌	❌
call cc_timing	👍	❌	👍	❌	👍	❌	❌
call cc_timing2	👍	❌	👍	❌	👍	❌	❌
di timing GS	👍	👍	👍	❌	👍	👍	👍
div timing	👍	👍	👍	👍	👍	❌	👍
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	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
mem oam	👍	👍	👍	👍	👍	👍	👍
reg f	👍	👍	👍	👍	👍	👍	👍
unused_hwio GS	👍	❌	👍	❌	❌	❌	❌

GPU

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
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	❌	❌	❌	❌	❌	❌	❌
stat irq blocking	❌	❌	👍	❌	❌	❌	❌
vblank stat intr GS	👍	👍	❌	👍	👍	❌	❌

Timer

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
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

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
mbc1 rom 4banks	👍	❌	👍	👍	👍	❌	👍

Mooneye GB manual tests

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
sprite priority	👍	👍	👍	❌	👍	❌	❌

Mooneye GB misc tests

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
boot hwio C		👍		❌		❌	❌
boot hwio S		❌		❌	👍	❌	❌
boot regs A		❌		❌		❌
boot regs cgb		👍		❌		❌	👍
boot regs mgb		👍		👍			👍
boot regs sgb		❌		👍	👍	❌	👍
boot regs sgb2		❌		👍	❌	❌

Bits

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
unused hwio C		❌		❌		❌	❌

GPU

Test	mooneye-gb	BGB	Gambatte	GiiBiiAdvance	Higan	KiGB	MESS
vblank stat intr C		❌		❌		❌	❌

Test naming

Some tests are expected to pass only a single type of hardware:

• dmg = Game Boy
• mgb = Game Boy Pocket
• sgb = Super Game Boy
• sgb2 = Super Game Boy 2
• cgb = Game Boy Color
• agb = Game Boy Advance
• ags = Game Boy Advance SP

In general, hardware can be divided on to a couple of groups based on their behaviour. Some tests are expected to pass on a single or multiple groups:

• G = dmg+mgb
• S = sgb+sgb2
• C = cgb+agb+ags
• A = agb+ags

For example, a test with GS in the name is expected to pass on dmg+mgb + sgb+sgb2.

License and copyright

Mooneye GB is licensed under GPLv3+. Copyright (C) 2014-2016 Joonas Javanainen joonas.javanainen@gmail.com