Skip to content
BranchesTags

Repository files navigation

Gameboy

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.

About

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

Topics

emulatorgameboyrust

Resources

Readme
MIT license
Activity
Custom properties

Stars

1.4k stars

Watchers

19 watching

Forks

87 forks
Report repository

Releases

Packages

Used by

Contributors

Languages