rboy: a Gameboy emulator in Rust

A Game Boy emulator written in Rust from scratch, that runs Pokemon Red.

We have done this project between five friends, during the time of a long weekend. Our hope was that by the end of the weekend, we would have a working emulator to play Pokemon Red. The goal has been achieved 🚀

The emulator includes:

• A .gb file loader / parser.

• An emulator that owns the CPU, MMU, and graphics.

• Support for interrupts and timers.

• A debugger that allows stepping through the code and inspecting registers and memory.

• A graphical user interface that remains in sync with the emulator's CPU instructions, and supports user inputs.

However, this project still has a lot of room for improvement.

• The screen does not simulate the actual hardware of the gameboy screen (ppu modes are not respected for drawing the pixels), potentially yielding to incorrect synchronisation between the CPU and the PPU.

• There are still some bugs with tiles and 8x16 objects.

• The sound system has not been implemented at all.

Code hierarchy and structure

The emulator is organized as a Rust workspace with several crates, each responsible for a specific component of the Game Boy hardware:

Core Crates

• cpu: CPU emulation implementing the Sharp LR35902 instruction set. It includes the representation of all the instructions, of the registers, of the timers and of the interrupts.

• emulator: High-level emulator that orchestrates all component: CPU, MMU, graphics, and input handling

• graphics: PPU (Pixel Processing Unit) and graphics rendering

• graphics-pixels: Frontend integration using the pixels library

Memory Crates

Regarding the memory, we wanted to keep a strong dissociation between "what can be accessed in the memory" vs "how is the access implemented". Therefore, we have decided on the following infrastructure: any crate can only access memory via traits and never via direct struct's public methods.

• memory/accesss: Defines the memory access traits for all the components of the emulator.

• memory/mmu: Memory Management Unit that routes reads/writes between cartridge and console memory. Implements memory access traits for CPU, graphics, and other components.

Then, there are two specific memory crates, which are only imported by the MMU:

• memory/cartridge: Cartridge and MBC5 (Memory Bank Controller) implementation

• memory/gb_memory: Game Boy internal memory

Binary

• bins/rboy: Main CLI application
  • main: Command-line interface with run and debug commands
  • debugger: Interactive debugger for stepping through code and inspecting state

Run the emulator

The main binary is rboy, so you can get help with

cargo run --bin rboy --release -- --help

There are two commands: run and debug. Eg, if you want to run the hello-world.gb example: you just do the following command.

cargo run --bin rboy --release -- run examples/hello-world.gb

If instead you wanted to start the debugger, you would do:

cargo run --bin rboy --release -- debug examples/hello-world.gb

Contribution

Read the contribution guidelines

Gameboy developing environments

See the Gameboy environments page about some tooling to get started.

Glossary

Term	Meaning	Explanation
DMG	Dot Matrix Game	The original 1989 black-and-white Game Boy model. Often used to refer to the non-color hardware.
GBC	Game Boy Color	The 1998 upgraded console with color graphics and slightly faster CPU.
ROM	Read-Only Memory	The program chip inside a game cartridge. Emulator loads it from a .gb file.
RAM	Random Access Memory	Working memory used by the console for variables, game state, and graphics buffers.
VRAM	Video RAM	A separate memory area holding image tiles and background maps for rendering.
MBC	Memory Bank Controller	Hardware in many cartridges that allows switching between multiple ROM or RAM banks, letting large games fit on limited address space.
CPU	Central Processing Unit	The Game Boy's main processor (a Sharp LR35902, similar to a Z80). Executes all instructions.
PPU	Pixel Processing Unit	The graphics subsystem that reads VRAM and draws pixels to the screen each frame.
APU	Audio Processing Unit	The sound generator that produces tones, noise, and music.
I/O	Input/Output	Communication between the console and external devices — buttons, link cable, etc.
M Cycle	Machine Cycle	The smallest timing unit used by the CPU; several M-cycles make up one instruction.
VBlank	Vertical Blanking Interval	The brief period between screen refreshes when graphics memory can safely be updated.
Opcode	Operation Code	The numeric byte that identifies which instruction the CPU should execute.
Interrupt	Hardware Signal	A hardware-triggered signal that temporarily pauses the CPU to run special code (e.g., for timers or input).