A Gameboy Color (GBC) emulator written in Rust

There are two types of tests:


. This is intended as a learning project.

Quick Start

1. Download

Visit the Releases page and download the latest version for your OS.

2. Run

Run a ROM:

gbcemu run [path_to_rom]

Run with -h to view all flags and options.

3. Play


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

Games Tested

  • 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


Project Structure

The emulator is divided into three crates:

  1. lib: main library for emulating a Gameboy
  2. emu: emulator frontend GUI written using SDL2 (runs on macOS, Windows, and Linux)
  3. emu-wasm: lib compiled to WASM and running on a Canvas2D in JS


  1. Functional tests: verify the basic functions of the CPU and peripherals
  2. 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:

  1. CMake
  2. 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.


  1. Install the VSC++ build tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
  2. Install rustup (this also installs rustc and cargo): https://www.rust-lang.org/tools/install
  3. Install CMake: https://cmake.org/download/
  4. 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.

Collection of the latest Issues



Comment Icon0

This may require a re-write of the core Gameboy to use an event scheduler instead of a lock-step emulation approach.



Comment Icon1

Right after the player first appears, some tiles get invalid tile attributes written to bank 1 of VRAM. The data should have been written to bank 0. For some reason, these invalid writes to the tile map area only occur for 3 lines worth of tiles. Also, the failure is intermittent, even for the same save state.


In BGB, writing to the tilemap takes place in this function:

The callstack to get here is:


Find the latest versions by id

Information - Updated May 13, 2022

Stars: 32
Forks: 2
Issues: 2

Repositories & Extras

maomi: A rust wasm framework for building pages with components

maomi is a MVVM-like framework for web development

maomi: A rust wasm framework for building pages with components

Rust / Wasm client web app framework

Pull requests which improve test coverage are also very welcome

Rust / Wasm client web app framework

A Rust/WASM Library to interact with Bitcoin SV

npm i bsv-wasm-bundler --save

A Rust/WASM Library to interact with Bitcoin SV

WASM / Rust / D3 example

Fetch data with Rust + WASM and show it with JS + D3

WASM / Rust / D3 example


A template for kick starting a Rust and WebAssembly project using Tutorial


rust wasm worker hello world

Built using the template at which

rust wasm worker hello world

👷‍♀️🦀🕸️ rustwasm-worker-template

A template for kick starting a Cloudflare worker project using

👷‍♀️🦀🕸️ rustwasm-worker-template

Rust WASM Web Worker Examples

This repository contains four different examples of using web workers in conjunction with WASM in

Rust WASM Web Worker Examples


WebAssembly でマンデルブロ集合を描きます

Facebook Instagram Twitter GitHub Dribbble