. This is intended as a learning project.
Visit the Releases page and download the latest version for your OS.
Run a ROM:
gbcemu run [path_to_rom]
-h to view all flags and options.
- Arrows for direction keys
S: A button
A: B button
X: start button
Z: select button
Emulator GUI keys:
K: save emulator state
L: load emulator state
;: reset the emulator
O: draw basic tile outline (toggle)
P: pause (toggle)
Note: these are replaced with buttons in the WASM version.
- Dr. Mario (DMG, no ROM banking)
- Tetris World (DMG, no ROM banking)
- Kirby's Dream Land (DMG, MBC1)
- Tetris World DX (GBC, MBC1)
- Super Mario Bros. Deluxe (GBC, MBC5)
- Pokemon Yellow (GBC, MBC5)
- Donkey Kong Country (GBC, MBC5)
- Dragon Warrior Monsters (GBC, MBC5)
- The Legend of Zelda: Link's Awakening DX (GBC, MBC5)
- Pokemon Gold (GBC, MBC3+RTC)
- Hits glitch after intro (#3)
- Shantae (GBC, MBC5)
- Not working, stuck on blue screen
The emulator is divided into three crates:
lib: main library for emulating a Gameboy
emu: emulator frontend GUI written using SDL2 (runs on macOS, Windows, and Linux)
libcompiled to WASM and running on a
- Functional tests: verify the basic functions of the CPU and peripherals
- Integration tests: run existing test ROMs and ensure that they pass
These tests run on every commit to the repo.
Due to the SDL dependency, you have to install some dependencies before you can build the emulator. Note that SDL is automatically built as part of the Rust-SDL2 build script, but the script needs a few tools:
- C compiler (MSVC, GCC, Clang)
Since we statically link against
libsdl on all platforms to avoid having to ship the DLL with the emulator, you do not need to install SDL for the build.
- Install the VSC++ build tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
rustup(this also installs
- Install CMake: https://cmake.org/download/
The full build in release mode (including SDL) on a 10 core Windows VM takes ~1 min.
The emulator comes with a simple GDB-like debugger CLI. Note that the debugger is not included by default.
To build the emulator with debugger support:
cargo build --manifest-path emu/Cargo.toml --features debug
As soon as you run the emulator, it will jump into the REPL. The following commands are available:
n: Step to the next instruction.
n <num>: Skip the next
info [r]egs: Dump all registers.
p <addr>: Print the byte at the specified memory address.
b <addr>: Set a breakpoint on an instruction address. Note that you can have multiple active breakpoints.
info [b]reak: List all breakpoints that have been set.
disable <index>: Disable the breakpoint with the given index.
d <index>: Delete the breakpoint with the given address.
r: Continue running the emulator until the next breakpoint is hit.
[l]ist: Disassemble the next five instructions, starting from the current one.
[l]ist <count>: Disassemble the next
countinstructions, starting from the current one.
[h]ist: Dump the last five executed instructions.
[h]ist <count>: Dump the last