My Gameboy Emulator

A Game Boy (DMG-01) emulator written in Rust.

Features

• Sharp SM83 CPU — full instruction set including CB-prefixed opcodes, interrupts (V-Blank, STAT, Timer, Joypad), and halt/stop handling
• PPU — scanline-accurate rendering (OAM scan, draw, H-Blank, V-Blank) with background, window, and sprite support; classic DMG green palette
• APU — four audio channels: two square waves, one wave channel, one noise channel
• Memory Bank Controllers — ROM-only (MBC0) and MBC1 (covers Tetris, Super Mario Land, Donkey Kong, and more)
• Timer — DIV and TIMA registers with correct overflow/interrupt behaviour
• Joypad — keyboard-mapped D-pad and action buttons
• 60 fps cap — frame timing locked to the DMG's 59.7 fps regardless of display refresh rate

Requirements

• Rust (edition 2024 / Rust 1.85+)

Building & Running

# Build in release mode
cargo build --release

# Run (edit main.rs to point at your ROM)
cargo run ./roms/rom_file.gb --release

You must specify the path to the ROM file you want to play.

Scale factor

The window renders at 160×144 scaled up by SCALE_FACTOR (default 5 → 800×720). Change the constant in src/main.rs to adjust.

Controls

Game Boy button	Keyboard key
D-pad Up	Arrow Up
D-pad Down	Arrow Down
D-pad Left	Arrow Left
D-pad Right	Arrow Right
A	Z
B	X
Start	Enter
Select	Backspace

Project Structure

src/
├── main.rs           # Window setup and entry point
├── lib.rs            # Main emulation loop (CPU + PPU + APU + timing)
├── cpu/
│   ├── mod.rs        # Sharp SM83 CPU, registers, interrupt handling
│   ├── opcodes.rs    # Standard opcodes
│   └── cb_opcodes.rs # CB-prefixed opcodes
├── mmu/
│   ├── memory.rs     # System bus trait
│   ├── memory_controller.rs  # Bus routing + I/O registers
│   └── cartridge.rs  # MBC0 / MBC1 cartridge support
├── ppu/
│   └── mod.rs        # Pixel Processing Unit (scanline renderer)
├── apu/
│   ├── mod.rs        # Audio Processing Unit
│   ├── square.rs     # Square wave channels (CH1, CH2)
│   ├── wave.rs       # Wave channel (CH3)
│   ├── noise.rs      # Noise channel (CH4)
│   └── components.rs # Shared envelope / length / sweep components
├── audio_output.rs   # cpal audio backend
├── joypad.rs         # Joypad register + keyboard polling
└── timer.rs          # DIV / TIMA timer
roms/                 # Place your .gb ROM files here
tests/                # Integration tests

References

• Pan Docs — comprehensive DMG technical reference
• Game Boy Complete Technical Reference (Gekkio)
• Game Boy Opcode Summary (Izik)
• Blargg's Test ROMs
• Mooneye GB Tests

License

MIT