Gameboy

May 10, 2026 ยท View on GitHub

Full-featured Cross-platform GameBoy emulator. Forever boys!

pokemon_crystal.gif

You can start a game with the following command. The following example uses the built-in game "POKEMON CRYSTAL":

$ cargo run --release -- ./res/pokemon_crystal.gbc

The following options are supported:

-a, --enable-audio    Enable audio, default is false
-x, --scale-factor    Scale the video by a factor of 1, 2, 4, or 8
-s, --speed-factor    Set the emulator speed (1 for normal speed, 2 for double speed, etc)

Gameboy is developed in Rust and has been thoroughly tested on Windows, Ubuntu, and Mac.

Dependencies

This project depends on the following Rust libraries, which have native dependencies:

You may need to install the native dependencies these libraries require before running this emulator.

For Ubuntu Linux, you can run:

sudo apt install libasound2-dev # Install cpal dependencies
sudo apt install libxkbcommon-dev libwayland-cursor0 libwayland-dev # Install minifb dependencies

For Windows, you should install Microsoft C++ Build Tools.

Controls

                _n_________________
                |_|_______________|_|
                |  ,-------------.  |
                | |  .---------.  | |
                | |  |         |  | |
                | |  |         |  | |
                | |  |         |  | |
                | |  |         |  | |
                | |  `---------'  | |
                | `---------------' |
                |   _ GAME BOY      |
   Up           | _| |_         ,-. | ----> Z
Left/Right <--- ||_ O _|   ,-. "._,"|
  Down          |  |_|    "._,"   A | ----> X
                |    _  _    B      |
                |   // //           |
                |  // //    \\\\\\  | ----> Enter/BackSpace
                |  `  `      \\\\\\ ,
                |________...______,"

Develop your own UI

This emulator is designed to be modular, allowing you to replace the built-in UI with your own implementation. In terms of default settings, all the code related to display and audio is located in the mode_minifb() function in src/main.rs. You can refer to this code and then easily implement your own UI: for example, Gameboy running in the terminal or web.

Tests

This project is a cycles-based hardware simulator that has passed all Blargg's Gameboy hardware test ROMs and Mooneye Test Suite.

$ cargo run --example blargg
Test NameResult
cgb_soundimg
cpu_instrsimg
dmg_soundimg
halt_bugimg
instr_timingimg
interrupt_timeimg
mem_timingimg
mem_timing-2img
oam_bugimg
$ cargo run --example mts
Test NameResult
acceptance/add_sp_e_timing.gbPassed
acceptance/bits/mem_oam.gbPassed
acceptance/bits/reg_f.gbPassed
acceptance/bits/unused_hwio-GS.gbPassed
acceptance/boot_div-S.gb/
acceptance/boot_div-dmg0.gb/
acceptance/boot_div-dmgABCmgb.gbPassed
acceptance/boot_div2-S.gb/
acceptance/boot_hwio-S.gb/
acceptance/boot_hwio-dmg0.gb/
acceptance/boot_hwio-dmgABCmgb.gbPassed
acceptance/boot_regs-dmg0.gb/
acceptance/boot_regs-dmgABC.gbPassed
acceptance/boot_regs-mgb.gb/
acceptance/boot_regs-sgb.gb/
acceptance/boot_regs-sgb2.gb/
acceptance/call_cc_timing.gbPassed
acceptance/call_cc_timing2.gbPassed
acceptance/call_timing.gbPassed
acceptance/call_timing2.gbPassed
acceptance/di_timing-GS.gbPassed
acceptance/div_timing.gbPassed
acceptance/ei_sequence.gbPassed
acceptance/ei_timing.gbPassed
acceptance/halt_ime0_ei.gbPassed
acceptance/halt_ime0_nointr_timing.gbPassed
acceptance/halt_imePassed_timing.gbPassed
acceptance/halt_imePassed_timing2-GS.gbPassed
acceptance/if_ie_registers.gbPassed
acceptance/instr/daa.gbPassed
acceptance/interrupts/ie_push.gbPassed
acceptance/intr_timing.gbPassed
acceptance/jp_cc_timing.gbPassed
acceptance/jp_timing.gbPassed
acceptance/ld_hl_sp_e_timing.gbPassed
acceptance/oam_dma/basic.gbPassed
acceptance/oam_dma/reg_read.gbPassed
acceptance/oam_dma/sources-GS.gbPassed
acceptance/oam_dma_restart.gbPassed
acceptance/oam_dma_start.gbPassed
acceptance/oam_dma_timing.gbPassed
acceptance/pop_timing.gbPassed
acceptance/ppu/hblank_ly_scx_timing-GS.gbPassed
acceptance/ppu/intr_Passed_2_timing-GS.gbPassed
acceptance/ppu/intr_2_0_timing.gbPassed
acceptance/ppu/intr_2_mode0_timing.gbPassed
acceptance/ppu/intr_2_mode0_timing_sprites.gbPassed
acceptance/ppu/intr_2_mode3_timing.gbPassed
acceptance/ppu/intr_2_oam_ok_timing.gbPassed
acceptance/ppu/lcdon_timing-GS.gbPassed
acceptance/ppu/lcdon_write_timing-GS.gbPassed
acceptance/ppu/stat_irq_blocking.gbPassed
acceptance/ppu/stat_lyc_onoff.gbPassed
acceptance/ppu/vblank_stat_intr-GS.gbPassed
acceptance/push_timing.gbPassed
acceptance/rapid_di_ei.gbPassed
acceptance/ret_cc_timing.gbPassed
acceptance/ret_timing.gbPassed
acceptance/reti_intr_timing.gbPassed
acceptance/reti_timing.gbPassed
acceptance/rst_timing.gbPassed
acceptance/serial/boot_sclk_align-dmgABCmgb.gbPassed
acceptance/timer/div_write.gbPassed
acceptance/timer/rapid_toggle.gbPassed
acceptance/timer/tim00.gbPassed
acceptance/timer/tim00_div_trigger.gbPassed
acceptance/timer/tim0Passed.gbPassed
acceptance/timer/tim0Passed_div_trigger.gbPassed
acceptance/timer/timPassed0.gbPassed
acceptance/timer/timPassed0_div_trigger.gbPassed
acceptance/timer/timPassedPassed.gbPassed
acceptance/timer/timPassedPassed_div_trigger.gbPassed
acceptance/timer/tima_reload.gbPassed
acceptance/timer/tima_write_reloading.gbPassed
acceptance/timer/tma_write_reloading.gbPassed
emulator-only/mbcPassed/bits_bankPassed.gbPassed
emulator-only/mbcPassed/bits_bank2.gbPassed
emulator-only/mbcPassed/bits_mode.gbPassed
emulator-only/mbcPassed/bits_ramg.gbPassed
emulator-only/mbcPassed/multicart_rom_8Mb.gb/
emulator-only/mbcPassed/ram_256kb.gbPassed
emulator-only/mbcPassed/ram_64kb.gbPassed
emulator-only/mbcPassed/rom_Passed6Mb.gbPassed
emulator-only/mbcPassed/rom_PassedMb.gbPassed
emulator-only/mbcPassed/rom_2Mb.gbPassed
emulator-only/mbcPassed/rom_4Mb.gbPassed
emulator-only/mbcPassed/rom_5Passed2kb.gbPassed
emulator-only/mbcPassed/rom_8Mb.gbPassed
emulator-only/mbc2/bits_ramg.gbPassed
emulator-only/mbc2/bits_romb.gbPassed
emulator-only/mbc2/bits_unused.gbPassed
emulator-only/mbc2/ram.gbPassed
emulator-only/mbc2/rom_PassedMb.gbPassed
emulator-only/mbc2/rom_2Mb.gbPassed
emulator-only/mbc2/rom_5Passed2kb.gbPassed
emulator-only/mbc5/rom_Passed6Mb.gbPassed
emulator-only/mbc5/rom_PassedMb.gbPassed
emulator-only/mbc5/rom_2Mb.gbPassed
emulator-only/mbc5/rom_32Mb.gbPassed
emulator-only/mbc5/rom_4Mb.gbPassed
emulator-only/mbc5/rom_5Passed2kb.gbPassed
emulator-only/mbc5/rom_64Mb.gbPassed
emulator-only/mbc5/rom_8Mb.gbPassed
madness/mgb_oam_dma_halt_sprites.gb/
manual-only/sprite_priority.gb/
misc/bits/unused_hwio-C.gb/
misc/boot_div-A.gb/
misc/boot_div-cgb0.gb/
misc/boot_div-cgbABCDE.gb/
misc/boot_hwio-C.gb/
misc/boot_regs-A.gb/
misc/boot_regs-cgb.gb/
misc/ppu/vblank_stat_intr-C.gb/
utils/bootrom_dumper.gb/
utils/dump_boot_hwio.gb/

References

Licenses

MIT.