A WIP Game Boy emulator with a focus on accuracy and useful debugging tools.
- M-Cycle steppable
- Scheduler-driven execution
- Event system for observability, including support for crossbeam channels
- Flexible breakpoints built on top of the event system
- Reusable components separated along crate boundaries
- CLI utility
dmgcatfor working with cartridge metadata - Hybrid scanline/FIFO renderer (in-progress)
- Detailed, configurable logging
A simplified frontend made just for running ROMs. No debug tools or other advanced features.
This project requires cargo about to generate license information for the Help > About dialog and as a sanity check when adding new dependencies.
cargo install cargo-aboutYou can build and run for desktop with the following command:
cargo run --bin dotmatrix_eframeYou can build and run for the web using Trunk. Once it's installed, run the following commands:
cd crates/eframe_simple_frontend
trunk serve --openThis project uses cargo's built-in test framework for testing. Once all the pre-requisites are satisfied, just run the following command:
cargo testThis will run individual unit tests, as well as freely available test ROMs and CPU test data.
To run the test suite you will need to do two things:
The test suite is largely built upon external test data that has been verified against real hardware and/or other known-working emulators.
- The Single Step Tests provide the state of the CPU before and after each instruction, as well as the bus activity captured during execution.
- The Game Boy Test Suites provide freely available test ROMs and enough metadata to detect pass/fail states.
This test data is included via git submodules, which you can clone with the following commands:
# When cloning for the first time
git clone --recursive https://github.com/Estus-Dev/DotMatrix
# If you've already cloned the main repo and just need to download the submodules
git submodule update --init --recursiveThe test suite is designed to run with the original bootrom, which you can dump to a flashcart from your own hardware via Joonas Javanainen's bootrom_dumper.gb and a single piece of wire.
Once you have the bootrom, store it in an environment variable called DOTMATRIX_DMG_BOOTROM in base64.
Logs are stored in a state or data_local dir according to the directories crate. The path to the current log will be printed to the console on startup. For instance on Windows they are stored in %localappdata%\estus\dotmatrix_roms\data\logs.
Verbosity is configured via the RUST_LOG environment variable.
Use caution when enabling debug or trace level logs, as they can be quite noisy and take up a lot of space. For instance: Enabling trace level logging for the dotmatrix_cpu::cpu::fetch_opcode will produce logs containing nearly the full CPU state at a rate of up to 1mhz.
For tests that are covered by Peach's logs you can assign any non-empty value to $DOTMATRIX_TEST_PEACH_LOGS to generate compatible logs in a peach folder. These are stored near the standard logs, and when enabled the path to these will also be printed.
There is a convenience script available to diff against the original logs.
NOTE: Peach's logs only include one copy of the bootrom logs; individual test logs pick up where the bootrom left off. That means you'll need to do a touch of cleanup before comparing them. Either concatentate the original bootrom log into each of the original test logs, or remove the start of each newly generated log up until the instruction at PC = 0x00FE.
Please use Peach's Logs instead.
Final-frame screenshots can be automatically saved depending on the value of $DOTMATRIX_SCREENSHOT. Valid values are always, failure, and the default value of never.
Upon saving a screenshot, the path is printed to the console.
Screenshots can be controlled through the DOTMATRIX_SCREENSHOT variable above, but will default to failure instead of never.
Any screenshots produced will be uploaded as job artifacts. You can rerun a job after setting DOTMATRIX_SCREENSHOT in the actions config to produce screenshots if needed.