THE CHALLENGE
Keeping a whole machine in sync
Emulation is a coordination problem: CPU instructions, memory access, timers, video, and sound must advance together. Matchaboy explores those interactions directly, then makes the internal machine state visible and testable.
ENGINEERING
Timing the bus, pixels, and replay
The core is C++20 and uses the standard library rather than an emulator framework. The CPU decodes primary and CB instructions through a real memory bus that advances the PPU, timer, DMA, serial, and audio hardware. Cartridge support includes ROM-only, MBC1, MBC3/RTC, and MBC5 banking.
The renderer emits pixels through eight-slot background and object FIFOs. Per-dot fetches, window and object stalls, priority rules, and register-write timing are part of the implementation. The harness records original test-ROM verdicts, framebuffers, instruction traces, cycle counts, and hashes.
The wider Matcha platform adds deterministic snapshots, a preallocated 60-frame history, real UDP serial-link rollback/replay, and batched emulator instances through a C ABI and Python/Gymnasium wrapper. Silicon Autopsy displays memory activity, disassembly, FIFO state, and the four APU channels.
Test through the actual hardware path
Unit programs and external ROMs use the same CPU/bus/peripheral instances. Completion of a fixed-frame run is not automatically counted as a test pass.
Retain reproducible evidence
Frozen campaigns preserve source and ROM hashes, binaries, traces, and reference frames. The dashboard readback is checked against the headless view.
Report correctness and speed separately
The documented M3 campaign passes its correctness checks but misses the 50,000 aggregate-FPS and low-latency rollback targets. The implementation keeps those failures visible.