gib
gib copied to clipboard
plorefice
GameBoy emulator written in Rust
gib
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)
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 [email protected]:plorefice/gib
cd gib/
cargo build --release
Running the emulator
Once 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.
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 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 | 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 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 | 100% | Full pass! |
| oam_bug | - | Not tested yet |
| dmg_sound | 70% | Trigger and wave channels still wonky |
Gekkio's test suite
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 |
Resources
- 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 :pray:
plorefice