Jack Tricker / Writing

A Game Boy emulator in Rust

Jack Tricker, 14 April 2025 (updated 12 October 2026)


rustboy is a Game Boy emulator written in Rust. It boots Tetris, Dr. Mario and Pokémon Blue, and you can try it in a browser with your own ROM file.

The CPU, one opcode at a time

I started at the end of March 2025 with the processor. The Game Boy's CPU has about 500 instructions, half of them behind a 0xCB prefix. I wrote them roughly in order from a table of opcodes, and the commit log for early April reads like the table: "0x0A", "0x18", "0x1F", "0x8F". The unprefixed half took a week, from 2 to 8 April, and the prefixed half was finished the next day.

Finding the bugs

Five hundred hand-written instructions will have bugs in them, and a game that crashes doesn't say which instruction was wrong. Two tools do. Blargg's test ROMs exercise the instructions a group at a time and print "Passed" or "Failed" over the serial port. Gameboy Doctor takes a log of the registers at every instruction, compares it with a log from a correct emulator, and reports the first line that differs.

These are some of the bugs they found:

The timer followed, in a commit titled "timer working lol". By the middle of April the CPU ran the test ROMs, but its interrupt handling was still wrong and there was no screen. Everything the emulator produced was text from the serial port. Apart from a few small commits, I left it like that for over a year.

A screen

In August 2026 I picked it up again with Claude Code, which wrote most of what follows. Nearly all of it went in on one day, the 28th.

The interrupt fixes came first. RETI now turns interrupts back on immediately, and the emulator reproduces a bug in the real CPU: if HALT runs while interrupts are disabled and one is already waiting, the byte after it is executed twice. With those fixes all of Blargg's CPU tests pass, and they run as part of cargo test.

Then came cartridge support (the MBC1, MBC3 and MBC5 bank-switching chips), the joypad, and a screen, drawn a scanline at a time with the background, the window and sprites. Tetris boots to its title screen and the menu works. Dr. Mario reaches its title screen, and Pokémon Blue plays through its intro.

In October the emulator was compiled to WebAssembly and published on GitHub Pages, with on-screen buttons for phones.

What it doesn't do

There is no sound, no save files and no link cable. The screen is timed a scanline at a time, which is coarser than the real hardware.

[ Return to top ] [ All writing ]


Jack Tricker / me@jacktricker.com
Last modified: 12 October 2026