Skip to content

Latest commit

 

History

History
164 lines (136 loc) · 5.25 KB

README.md

File metadata and controls

164 lines (136 loc) · 5.25 KB
Raw

An M Cycle Accurate Gameboy Emulator Programmed in Rust

Currently In Development

  • The 2 mains goals of this project are to make a fairly accurate emulator and also learn the fundamentals of rust. It won't be the most accurate gameboy emulator in the world but I do want it to pass as many well known test roms as possible (blargg, mooneye, dmg-acid2, etc).
  • The main feature this emulator is lacking would be audio but that is next to be added (I am struggling with audio documentation so I will probably come back to this in the future)
  • Skip to Testing to see the current test roms its passes
  • Skip to Current Features to see what is currently emulated
  • Skip to Next Features to see what's planned
  • Skip to How to Run to try the emulator out

Screenshots

Button Mappings

Gameboy Button ==> Physical Keyboard

Up ==> Up Arrow

Down ==> Down Arrow

Left ==> Left Arrow

Right ==> Right Arrow

A ==> F

B ==> D

Start ==> Right Shift

Select ==> Enter/Return

How to Run

Install/Build Requirements

  • Rust
  • SDL2*

*Your main issue with running will probably be that the emulator uses sdl2. I've been developing this on windows and used features = ["bundled"] for the sdl2 dependency in the cargo.toml. This should mean you wont need to install sdl2 but you will need the tools to build it. I was missing the following on windows and linux:

  • Windows: CMake

  • Linux: libXext-dev (This is the only one I was missing, if your trying to run this from scratch you'll probably need other libraries aswell like build-essential.

Run Command

  • cargo run <rom-name> at the root of the repository

Debugging Features

  • cargo run --features "debug-file" (Output some register and mmio information to a file with the name <rom-name>.txt)
  • cargo run --features "debug-logs" (Output some register and mmio information to the console)
  • cargo run --features "blargg" (Stop a blargg test automatically)
  • cargo run --features "mooneye" (Stop an mts test automatically) Cargo also allows you to combine the above: cargo run --features "mooneye debug-file"

Regarding the debug-file feature

  • Be careful not to leave it running for very long or the file will become extremely large.
  • The file will be placed in a folder called debug-info/ which will be created in the root of this repo if it doesnt already exist
  • If the file already exists, a number will be appended on the end of the file name.

Tested Games

These are just the ones I've played at least a bit:

  • Pokemon Red
  • Kirby's Dream Land
  • Super Mario Land (World)
  • Mega Man V
  • Tetris

Testing

Currently Passes the Following Test Roms:

  • Blargg Tests
    • cpu_instrs
    • instr_timing
    • mem_timing/mem_timing2
    • halt_bug
  • dmg-acid2 (https://github.com/mattcurrie/dmg-acid2)
  • Emulator-Only (Mooneye - mts-20220522-1522-55c535c)
    • MBC1
    • MBC5
  • Acceptance (Mooneye - mts-20220522-1522-55c535c)
    • oam_dma/
    • bits/
    • instr/
    • timer/
    • General (Dont know what to call these)
      • boot_div-dmgABCmgb
      • boot_hwio-dmgABCmgb
      • boot_reg-dmgABC
      • call_timing2
      • call_cc_timing2
      • di_timing-GS
      • div_timing
      • ei_sequence
      • ei_timing
      • halt_ime0_ei
      • halt_ime0_nointr_timing
      • halt_ime1_timing
      • halt_ime1_timing2-GS
      • if_ie_registers
      • intr_timing
      • pop_timing
      • push_timing
      • rapid_di_ei
      • reti_intr_timing
      • rst_timing
      • oam_dma_restart
      • oam_dma_timing
      • oam_dma_start
      • add_sp_e_timing
      • call_timing
      • call_cc_timing
      • jp_cc_timing
      • jp_timing
      • ld_hl_sp_e_timing
      • ret_cc_timing
      • ret_timing
      • reti_timing
  • Manual-Only (Mooneye - mts-20220522-1522-55c535c)
    • sprite_priority (well.. as far as my eyes can tell)
  • rtc3test
  • Miscalleneous
    • lycscx.gb
    • lycscy.gb

Tests I care about that are failing from Mooneye Acceptance:

  • ppu/ - All of them fail :(

Features

Current Features

  • Memory Bank Controllers
    • None
    • MBC1 (Multicart Not implemented)
    • MBC3 with RTC3 (Passes basic rtc3 test)
    • MBC5
    • Battery for ram
  • CPU
  • Haltbug
  • Interrupts
  • DMA Transfer
  • Stat Blocking (Need to Test)
  • DMG Stat Quirk/Bug (Need to test)
  • PPU (Doesnt extend mode 3 properly)

Next Features

  • Sound (Aim is to pass blargg test)
  • Mooneye Acceptance PPU
  • Pass as many of Mealybug Tearoom Tests as possible
  • MBC2

Maybe Features

  • CGB Support

Not Planned Features

  • OAM Corruption Bug
  • MBC4, and the more obscure ones
  • Peripherals (Camera, Infrared Communication)
  • Multicart Roms