rgy

No-std cross-platform Rust GameBoy emulator library. Rust GameboY (RGY, or Real GaY).

Try it on your PC

$ cargo run --example pc <a ROM file>

The example runs the GameBoy emulator in Mac/Linux/Windows.

Dependencies

On Ubuntu, you need to install these packages:

$ sudo apt install libasound2-dev libxcursor-dev libudev-dev

Key bindings

Keyboard	Gamepad	GameBoy
Up / W	DPad Up	Up
Left / A	DPad Left	Left
Down / S	DPad Down	Down
Right / D	DPad Right	Right
K / X	South / East	A
J / Z	West / North	B
Space	Select	Select
Enter	Start	Start
Escape	-	Close

Port it to a new environment

The library itself is environment independent. It can be even ported onto bare-metal. Once you implement environment-specific part, i.e. Hardware trait, you will get a GameBoy emulator for your environment.

struct Hardware;

// 1. Implement `rgy::Hardware`.
impl rgy::Hardware for Hardware {
    ...
}

// 2. Call `rgy::run`.
fn main() {
    let cfg = Config::new();
    let rom = include_bytes!("path_to_rom_file.gb");
    rgy::run(cfg, &rom, Hardware);
}

Emulation Status

• CPU
  • Supports all the documented instructions.
  • Emulates accurate read/write timing.
• Interrupts
  • Supports all the interrupts.
  • Emulates halt bug.
• Graphics
  • The most features are functioning.
  • OAM bug is not yet supported.
• Sound
  • The most features are functioning.
  • PCM registers are always emulated for sound tests.
• Joypad
• Timer
• Serial
• Cartridge (MBC 1,2,3,5, HuC 1)
• Gameboy Color feature is under development.

Test Status

Test status of Blargg's Gameboy hardware test ROMs

• cpu_instrs
• instr_timing
• mem_timing
• mem_timing-2
• oam_bug
• interrupt_time
• dmg_sound
  • 01-registers
  • 02-len ctr
  • 03-trigger
  • 04-sweep
  • 05-sweep-details
  • 06-overflow on trigger
  • 07-len sweep period sync
  • 08-len ctr during power
  • 09-wave read while on
  • 10-wave trigger while on
  • 11-regs after power
  • 12-wave write while on
• cgb_sound

Test status of Same Suite

• APU
  • apu/div_write_trigger.gb
  • apu/div_write_trigger_10.gb
  • apu/div_write_trigger_volume.gb
  • apu/div_write_trigger_volume_10.gb
  • apu/div_trigger_volume_10.gb
  • Channel 1
    • apu/channel_1/channel_1_delay.gb
    • apu/channel_1/channel_1_duty_delay.gb
    • apu/channel_1/channel_1_freq_change.gb
    • apu/channel_1/channel_1_align.gb (CGB double speed)
    • apu/channel_1/channel_1_align_cpu.gb (CGB double speed)
    • apu/channel_1/channel_1_duty.gb (CGB double speed)
    • apu/channel_1/channel_1_extra_length_clocking-cgb0B.gb (CGB double speed)
    • apu/channel_1/channel_1_freq_change_timing-A.gb (CGB double speed)
    • apu/channel_1/channel_1_freq_change_timing-cgb0BC.gb (CGB double speed)
    • apu/channel_1/channel_1_freq_change_timing-cgbDE.gb (CGB double speed)
    • apu/channel_1/channel_1_nrx2_glitch.gb
    • apu/channel_1/channel_1_nrx2_speed_change.gb
    • apu/channel_1/channel_1_restart.gb
    • apu/channel_1/channel_1_restart_nrx2_glitch.gb
    • apu/channel_1/channel_1_stop_div.gb
    • apu/channel_1/channel_1_stop_restart.gb
    • apu/channel_1/channel_1_sweep.gb
    • apu/channel_1/channel_1_sweep_restart.gb
    • apu/channel_1/channel_1_sweep_restart_2.gb
    • apu/channel_1/channel_1_volume.gb
    • apu/channel_1/channel_1_volume_div.gb
  • Channel 4
    • apu/channel_4/channel_4_lfsr.gb
    • apu/channel_4/channel_4_lfsr15.gb
    • apu/channel_4/channel_4_lfsr_7_15.gb
    • apu/channel_4/channel_4_lfsr_15_7.gb

Projects

The following projects use this library to run a GameBoy emulator.

• stickboy runs a GameBoy emulator on Macbook Pro (UEFI).
• biboy runs a GameBoy emulator on BIOS PC.
• waboy runs a GameBoy emulator on web browsers (wasm).