Low-level, cycle-accurate 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)
| Tetris | Dr. Mario | Link's Awakening |
|---|---|---|
 |
 |
 |
After installing Rust (you can use rustup for that), run:
git clone [email protected]:plorefice/gib
cd gib/
cargo build --releaseOnce you have a ROM file, you can use:
cargo 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.
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 |
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 test --releaseThe emulator is still a long way from being complete. The current status and roadmap are shown below.
| Peripheral | Progress | Notes |
|---|---|---|
| CPU | 100% | Timings verification still missing |
| Video | 80% | BG, Sprite, Window and IRQ support |
| Sound | 70% | 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 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 | 100% | Full pass! |
| oam_bug | - | Not tested yet |
| dmg_sound | 70% | Trigger and wave channels still wonky |
Gekkio's mooneye-gb test ROMs results.
The passing tests are also integrated in the emulator's test suite.
| Test Suite | Progress | Notes |
|---|---|---|
| acceptance/bits/ | 100% | Full pass! |
| acceptance/instr/ | 100% | Full pass! |
| acceptance/interrupts/ | 0% | Not yet |
| acceptance/oam_dma/ | 100% | Full pass! |
| acceptance/ppu/ | - | Not tested yet |
| acceptance/serial/ | - | Not tested yet |
| acceptance/timer/ | 100% | Full pass! |
| acceptance/boot_* | 100% | All default boot values are correct |
- GBDev Wiki
- The PanDocs
- Pastraiser's Gameboy CPU (LR35902) instruction set
- GameBoy Opcode Summary
- gbz80
- Gekkio's mooneye-gb test ROM sources
... and any other brave soul posting any kind of GB info on the Internet 🙏