80 lines
3.2 KiB
Markdown
80 lines
3.2 KiB
Markdown
# 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 -- <rom.gb> [options]
|
|
--frames N run N frames (default 60)
|
|
--serial run until the serial log says Passed/Failed, then print it
|
|
--png <path> write the framebuffer as an 8-bit grayscale PNG
|
|
--ascii print the framebuffer as ASCII art
|
|
--ascii-out <p> 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.
|