Skip to content

Latest commit

 

History

History
150 lines (124 loc) · 5.19 KB

README.md

File metadata and controls

150 lines (124 loc) · 5.19 KB
Raw

rgy

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

Latest version Documentation License Actions Status

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).