Skip to content

A Game Boy research project and emulator written in Rust

License

Notifications You must be signed in to change notification settings

Gekkio/mooneye-gb

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Mooneye GB

Mooneye GB is a Game Boy research project and emulator written in Rust.

Build Status

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

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

Command-line

  1. Acquire a Game Boy bootrom, and put it to $HOME/.local/share/mooneye-gb/bootroms/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

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

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