From 45e64b971c8547ff6c5a36313e740d67e8d5eda6 Mon Sep 17 00:00:00 2001 From: DualFroz Date: Fri, 28 Aug 2026 23:07:54 +0200 Subject: [PATCH] docs: add README with build, usage and verification gate instructions --- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8eeee84 --- /dev/null +++ b/README.md @@ -0,0 +1,79 @@ +# gameboy-sharp + +A Game Boy (DMG) emulator written in C# (.NET 6). The core is a pure library with +no frontend dependency, so the whole machine runs and is verified headless. + +## Status - wave 1 + +Working, test-verified core that runs real DMG software: + +- CPU LR35902: full opcode set + CB prefix, cycle-accurate M-cycle timing, Z/N/H/C + flags, interrupts (VBlank/LCD/Timer/Serial/Joypad), HALT + HALT bug, STOP (minimal), + delayed EI, DI, RETI. +- MMU: full memory map, I/O registers, echo RAM, OAM DMA. +- Cartridge: header parse, MBC1 (ROM/RAM banking), MBC3 and MBC5 banking (no RTC yet), + plain ROM. +- PPU: per-scanline mode 2/3/0 + VBlank timing, LCDC/STAT/SCX/SCY/LY/LYC/WX/WY/BGP/OBP0/OBP1, + background + window (with the window internal line counter) + sprites (8x8 and 8x16, + X/OAM priority, 10-per-line limit, BG priority), 160x144 framebuffer, STAT/LYC interrupts. +- Timer: DIV/TIMA/TMA/TAC via the internal 16-bit counter, falling-edge detection and the + TIMA overflow reload delay. +- Joypad and serial (serial output is captured, which is how the Blargg tests are scored). +- APU: register-level stub (open-bus read masks, NR52 power). No synthesis yet - wave 2. + +## Layout + +- `src/GameBoy.Core` - the machine (no frontend dependency). +- `src/GameBoy.Cli` - headless runner: loads a ROM, runs frames, dumps the framebuffer. +- `tests/GameBoy.Core.Tests` - the verification gate. + +## Verification gate + +`dotnet test` runs, headless: + +- `cpu_instrs` (Blargg) - asserts the serial log reports `Passed` and never `Failed`. +- `instr_timing` (Blargg) - same serial assertion. +- `dmg-acid2` - decodes the reference PNG and asserts the rendered framebuffer matches it + pixel for pixel (0 mismatches out of 23040). +- CPU micro tests (flags, DAA, push/pop, CB swap). + +``` +dotnet test -c Release +``` + +## Running a ROM (headless) + +``` +dotnet run --project src/GameBoy.Cli -c Release -- [options] + --frames N run N frames (default 60) + --serial run until the serial log says Passed/Failed, then print it + --png write the framebuffer as an 8-bit grayscale PNG + --ascii print the framebuffer as ASCII art + --ascii-out

write the ASCII art to a file +``` + +Examples: + +``` +dotnet run --project src/GameBoy.Cli -c Release -- tests/roms/cpu_instrs.gb --serial +dotnet run --project src/GameBoy.Cli -c Release -- tests/roms/dmg-acid2.gb --frames 200 --png acid2.png +``` + +## Test ROMs and licenses + +Vendored under `tests/roms/` purely to run the verification gate: + +- `cpu_instrs.gb`, `instr_timing.gb` - Blargg's Game Boy hardware test ROMs by Shay Green + (blargg), released for free distribution. Fetched from + https://github.com/retrio/gb-test-roms +- `dmg-acid2.gb` and `dmg-acid2-ref.png` - the DMG variant of the PPU acid test by + Matt Currie, MIT licensed. Fetched from https://github.com/mattcurrie/dmg-acid2 + +These are third-party artifacts kept only for testing; their own licenses apply. + +## Not covered yet (wave 2+) + +APU synthesis (4 channels + mixdown), MBC3 RTC + MBC5 corner cases, battery RAM save +(`.sav`), Game Boy Color, a windowed frontend (Raylib-cs/SDL - needs a display, so it was +left out of this headless wave), a debugger (breakpoints, disassembler, tile/OAM viewers) +and save states.