gib

Low-level, cycle-accurat original Gameboy (DMG) emulator written in Rust, also featuring several tools for ROM debugging and development.

It is still a WIP, but some simple ROMs have been tested and are (mostly) playable:

Tetris (JP) (Nintendo)
Dr. Mario (JP) (Nintendo)
The Legend of Zelda: Link's Awakening (US) (Nintendo)

Screenshots

In-game

Tetris	Dr. Mario	Link's Awakening

Development UI

Building the project

After installing Rust (you can use rustup for that), run:

git clone git@github.com:plorefice/gib
cd gib/
cargo +nightly build --release

Only nightly versions of Rust are supported right now.

Running the emulator

Once you have a ROM file, you can use:

cargo +nightly run --release [-- [--devel] [rom-file]]

The --devel flags will open the emulator in development/debugging mode, which includes disassembly view, memory viewer, step-by-step debugger and peripheral status overview.

The optional [rom-file] argument can be used to load a ROM directly from the command line. Alternatively, you can use the in-app menus; this is currently supported only in development mode.

Using the emulator

The joypad is mapped to the keyboard according to this table:

Joypad	Keyboard
Up	Up
Down	Down
Left	Left
Right	Right
B	Z
A	X
Select	Backspace
Start	Return
Turbo	Space

Running tests

Currently, unit tests exist for opcode size and timings, along with some peripherals. In the future, more complete tests will be developed. Some golden tests are also included to test against known working test ROMs (eg. blargg's).

You can run the test suite with:

cargo +nightly test --release

Features

The emulator is still a long way from being complete. The current status and roadmap are shown below.

Progress

Peripheral	Progress	Notes
CPU	100%	Timings verification still missing
Video	80%	BG, Sprite, Window and IRQ support
Sound	65%	Channels #1, #2 and #3 are mostly working
Joypad	80%	IRQ support missing
Link cable	0%	Not implemented yet
Timers	100%	Passes all Gekkio's acceptance tests
Interrupts	90%	Need to work on time accuracy
MBC	20%	Support for some functions of MBC1

Blargg's Test ROMs

Blargg's Gameboy hardware test ROMs results.

The passing tests are also integrated in the emulator's test suite.

Test ROM	Progress	Notes
cpu_instrs	100%	Full pass!
instr_timing	100%	Full pass!
interrupt_time	-	Requires CGB support
mem_timing-2	100%	Full pass!
mem_timing	100%	Full pass!
halt_bug	-	Not tested yet
oam_bug	-	Not tested yet
dmg_sound	-	Not tested yet

Gekkio's test suite

Gekkio's mooneye-gb test ROMs results.