A Game Boy (DMG) emulator written in Rust, optimised for real-time performance on resource-constrained hardware.
Peripherals (PPU, APU, timer, serial) are advanced once per complete SM83 instruction rather than once per M-cycle. This cuts peripheral-advancement overhead roughly 4× compared to M-cycle granularity. The trade-off is that behaviour which depends on mid-instruction peripheral state — primarily wave-channel read/write-while-on quirks — is not reproduced accurately.
- SM83 CPU (all official opcodes + CB-prefixed instructions)
- Scanline-based PPU with OAM DMA, sprites, window, and BG rendering
- MBC1 / MBC1 Multicart / MBC3 / No-MBC cartridge support
- APU with all four channels (pulse × 2, wave, noise) and frame sequencer
- Timer peripheral (DIV/TIMA/TMA/TAC) with accurate DIV-reset behavior
- Joypad peripheral (P1 register, joypad interrupt)
- Serial port output (used by Blargg test ROMs)
no_stdcore — runs on bare metal and WASM
| Suite | Status | Notes |
|---|---|---|
| Blargg cpu_instrs (11/11) | ✅ | |
| Blargg instr_timing | ✅ | |
| Blargg mem_timing | ✅ | |
| Blargg dmg_sound (9/12) | Tests 09, 10, 12 skipped — wave channel mid-instruction quirks require M-cycle accuracy | |
| dmg-acid2 (PPU) | ✅ | |
| Mooneye MBC1 (13/13) | ✅ | |
| Mooneye OAM DMA | ✅ |
rustyboy/
├── core/ # no_std emulator core (CPU, PPU, APU, memory)
├── platform/
│ ├── web/ # Browser platform (Axum server + WASM client)
│ │ ├── client/ # wasm-bindgen crate compiled to WASM
│ │ ├── server/ # Axum HTTP server serving ROMs and static files
│ │ └── Dockerfile # Multi-stage Docker build
│ └── pico2w/ # Raspberry Pi Pico 2W embedded platform
│ ├── src/ # Embassy async firmware
│ ├── memory.x # RP2350A flash/RAM layout
│ └── README.md # Setup, wiring, and flash instructions
└── Cargo.toml # Workspace root
| Platform | Description |
|---|---|
| web | Docker-hosted browser emulator with DMG Game Boy UI |
| pico2w | Portable handheld on Raspberry Pi Pico 2W (RP2350A) |
# Build and test the core
cargo test -p rustyboy-core
# Build the web platform (requires wasm-pack)
# See platform/web/README.md for full instructions
# Build the Pico 2W firmware (requires cross-compilation target)
# See platform/pico2w/README.md for full instructions
cd platform/pico2w
cargo build --releasecargo xtask wraps the per-platform build, deploy, and flash workflows behind
one command so you don't have to remember the underlying Docker / picotool /
probe-rs invocations. Run it from the workspace root.
cargo xtask <command> <target>| Command | Target | What it does |
|---|---|---|
build |
web |
Build the rustyboy-web Docker image |
build |
pico |
Cross-compile the pico2w firmware (release, ARM Cortex-M33) |
deploy |
web |
Build the image, (re)start the container, and print the URL |
deploy |
pico |
Build the firmware and flash over USB BOOTSEL — no SWD probe needed |
run |
pico |
Flash via SWD probe and stream defmt RTT logs (Ctrl-C to stop) |
crash |
pico |
Pull the crash log from the device over USB and decode it (no probe) |
setup |
web |
Install Docker Engine and add the current user to the docker group |
setup |
pico |
Build + install picotool from source and write Raspberry Pi udev rules |
Common workflows:
# Web: build + run the browser emulator, then open the printed http://<ip>:8080
cargo xtask deploy web
# Pico (no debug probe): hold BOOTSEL, plug in USB, then flash
cargo xtask deploy pico
# Pico (with SWD probe): flash and watch live RTT logs
cargo xtask run picoFirst-time setup for each platform is a one-off cargo xtask setup <target>.
| Flag | Applies to | Effect |
|---|---|---|
| (default) | deploy web |
Dev mode: server runs with DEV_MODE=1 (Google OAuth bypassed, a local dev user is auto-logged-in) and RUST_LOG=info (server logs + browser [client] breadcrumbs appear in docker logs). |
--prod |
deploy web |
Production mode: disables the dev-mode default and requires real Google sign-in. |
--debug-overlay |
build web, deploy web |
Build the WASM client with the on-screen debug overlay (--features debug-overlay; adds the "DBG" toggle). Off by default. |
--roms <DIR> |
deploy web |
Bind-mount <DIR> as the ROM library (read-only). Defaults to <workspace>/roms; a leading ~ is expanded. |
# Dev mode is the default — no auth, logs visible, custom ROM folder:
cargo xtask deploy web --roms ~/roms/extracted
# Production deploy with real Google auth:
cargo xtask deploy web --prod
# Dev mode with the on-screen debug overlay:
cargo xtask deploy web --debug-overlayNote:
deploy webserves over plain HTTP on your LAN IP. The client's ROM hashing falls back to a pure-JS SHA-256 whencrypto.subtleis unavailable (it only exists in secure contexts — HTTPS orlocalhost), so ROMs load correctly regardless of how the page is reached.