GameBoy Emulator

GameBoy Emulator

This is a GameBoy emulator written in Rust. It can be compiled to native and WebAssembly; see the build section for more details.

Emulator supports sound, several hardware types, RTC, gameboy color emulation, sprites, and saving to browser local storage (web) and user config directories (native)

The web assembly port is currently hosted here

Screenshots

Installing

The native version is published to crates.io and can be installed by running:

cargo install gameboy_opengl

Then you can run it by running: gameboy_emulator from your terminal

Building from source

The project uses Cargo as a build system.

Native (desktop)

Prerequisites: a normal Rust toolchain with cargo; SDL2 is bundled via the sdl2 crate.

cargo build --package gameboy_opengl --bin gameboy_emulator --release

Run the binary with a ROM path:

# Linux / macOS
./target/release/gameboy_emulator /path/to/game.gb

# Windows
.\target\release\gameboy_emulator.exe C:\path\to\game.gb

WebAssembly

The browser build uses wasm-pack (which wraps wasm-bindgen) and loads the UI from static/index.html.

Prerequisites:

rustup target add wasm32-unknown-unknown
cargo install wasm-pack

From the repository root (the gameboy_emulator crate that builds gameboy_lib as a cdylib):

wasm-pack build . --release --target web --out-dir static/pkg

This writes JavaScript and Wasm bindings under static/pkg/. The HTML page imports ./pkg/gameboy_lib.js and calls init() before start.

Serve the static directory over HTTP (browsers block Wasm on file://):

cd static && python3 -m http.server 8080

Then open http://localhost:8080 in a browser, choose a ROM, and play.

If audio does not start immediately, click or tap the page once; browsers often require a user gesture before AudioContext runs.

Alternative: wasm-bindgen CLI

If you prefer not to install wasm-pack, build the crate and run wasm-bindgen yourself:

cargo build --release --target wasm32-unknown-unknown
wasm-bindgen target/wasm32-unknown-unknown/release/gameboy_lib.wasm \
  --out-dir static/pkg --target web

You need wasm-bindgen on your PATH (for example cargo install wasm-bindgen-cli, matching the wasm-bindgen crate version used in this repo).