A debugging tool that compares your Game Boy emulator's CPU state against a reference to pinpoint bugs in test ROMs.
Gameboy Doctor is a debugging tool for developers building Game Boy emulators. It compares your emulator's CPU state log against a reference log from a passing emulator to find the exact tick where states diverge, helping isolate and fix bugs in test ROMs like Blargg's cpu_instrs.
Developers and hobbyists building Game Boy emulators who are stuck debugging test ROM failures and need precise, actionable insights into CPU state mismatches.
It eliminates guesswork by pinpointing exact divergence points with detailed diagnostics, works with minimal emulator implementations, and requires no third-party libraries—saving significant debugging time compared to manual tracing.
Debug and fix your gameboy emulator
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.
Requires only Python3 with no third-party libraries, making it easy to set up and run on any system, as stated in the README's Requirements section.
Identifies the precise tick where CPU state diverges from a reference, providing register mismatches and the last executed opcode to guide fixes, as shown in the example output.
Doesn't require an LCD or completed test runs; usable with a minimally functional CPU and motherboard, emphasized in the 'What is Gameboy Doctor?' section.
Allows piping emulator output directly for immediate feedback during development, with instructions in the 'Feed your logfile' section.
Currently only supports Blargg's cpu_instrs individual test ROMs, excluding other test suites, as admitted in the 'Future Work' section.
Demands hardcoding LCD behavior (LY register to 0x90) and modifying the emulator to log CPU state in a specific format, which adds complexity and potential for errors.
Lacks a graphical interface, relying solely on terminal output, which might be less intuitive for developers accustomed to visual debuggers or integrated environments.