A Gameboy Color (GBC) emulator written in Rust. 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]
Run with -h
to view all flags and options.
Controls:
S
: A buttonA
: B buttonX
: start buttonZ
: select buttonEmulator GUI keys:
K
: save emulator stateL
: load emulator state;
: reset the emulatorO
: draw basic tile outline (toggle)P
: pause (toggle)]
: Fast-forward (while held)=
: Increase emulation speed by 1x-
: Decrease emulation speed by 1x0
: Reset emulation speed to 1xNote: these are replaced with buttons in the WASM version.
The emulator is divided into three crates:
lib
: main library for emulating a Gameboyemu
: emulator frontend GUI written using SDL2 (runs on macOS, Windows, and Linux)emu-wasm
: lib
compiled to WASM and running on a Canvas2D
in JSThere are two types of tests:
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:
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.
rustup
(this also installs rustc
and cargo
): https://www.rust-lang.org/tools/install
cargo build
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 num
instructions.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 count
instructions, starting from the current one.[h]ist
: Dump the last five executed instructions.
[h]ist <count>
: Dump the last count
executed instructions.