From bafcec683184949dac38d8e94e35609f6f672d09 Mon Sep 17 00:00:00 2001 From: DualFroz Date: Fri, 28 Aug 2026 23:10:48 +0200 Subject: [PATCH] docs: add project README --- README.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1ce4cac --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# chip8-sharp + +A complete, tested CHIP-8 emulator written in C# (.NET 6). + +The core is a pure library with no rendering or input dependencies, so the full +instruction set is verified headlessly against the standard community test ROMs. +A separate Raylib frontend provides a scaled window, keyboard input and a square-wave +beep. + +## What it does + +- All 35 CHIP-8 opcodes. +- 4 KB memory, 16 V registers, index register, program counter, 16-level stack. +- 64x32 monochrome display with XOR sprite drawing and collision (VF). +- 16-key hex keypad, including `FX0A` wait-for-key with release semantics. +- Delay and sound timers at 60 Hz; beep while the sound timer is non-zero. +- Built-in 4x5 hex font at 0x50. +- Selectable interpreter quirks (`modern`, `cosmac`, `superchip`) for the + ambiguous instructions (shift source, `BNNN` vs `BXNN`, `FX55/FX65` index + increment, logic-op VF reset). + +## Layout + + src/Chip8.Core pure emulator library (no frontend dependency) + Machine.cs state, reset, ROM loading, timers, step loop + Machine.Execute.cs opcode decode and execution + Quirks.cs per-platform behaviour toggles + FontSet.cs built-in hex font + AsciiScreen.cs framebuffer to ASCII (used by CLI and tests) + src/Chip8.Cli Raylib window + headless ASCII runner + tests/Chip8.Tests xUnit: per-opcode unit tests + ROM framebuffer goldens + roms/ standard test ROMs (see Sources below) + +## Build and run + + dotnet build + dotnet test + +Run a ROM in a window: + + dotnet run --project src/Chip8.Cli -- roms/2-ibm-logo.ch8 + +Run headless and dump the framebuffer as ASCII (no display needed): + + dotnet run --project src/Chip8.Cli -- roms/2-ibm-logo.ch8 --headless --cycles 40 + +Options: + + --headless run without a window, print the framebuffer as ASCII + --cycles N instructions to run in headless mode (default 2000) + --ipf N instructions per 60 Hz frame (default 11, ~660 Hz) + --scale N window pixel scale (default 14) + --frames N window mode: auto-close after N frames + --shot PATH window mode: save a PNG screenshot before closing + --seed N deterministic RNG seed for CXNN + --quirks NAME modern (default), cosmac, or superchip + +## Key mapping + + CHIP-8 Keyboard + 1 2 3 C 1 2 3 4 + 4 5 6 D Q W E R + 7 8 9 E A S D F + A 0 B F Z X C V + +## Verification + +`dotnet test` runs 40 tests: + +- Per-opcode unit tests with hand-computed expected values for every instruction + group, including the flag semantics of `8XY4/5/6/7/E` and the quirk variants. +- Full 64x32 framebuffer golden comparisons for the standard test ROMs. The IBM + golden is produced by an independent decoder; the corax+, flags and corax89 + goldens are derived from the test authors' own reference screenshots. + +ROM results (all pass under the default `modern` profile): + +| ROM | Result | +|--------------------|---------------------------------| +| 2-ibm-logo.ch8 | IBM logo renders (230 pixels) | +| 3-corax+.ch8 | all opcode groups pass | +| 4-flags.ch8 | all flag cases pass | +| test_opcode.ch8 | every cell reads OK | +| BC_test.ch8 | displays BON (all good) | +| 7-beep.ch8 | sound timer activates | + +IBM logo, rendered headless (`# ` = lit pixel). The horizontal striping is +inherent to the ROM's sprite data, not an artifact: + +``` + ######## ######### ##### ##### # # + ######## ########### ###### ###### # + + #### ### ### ##### ##### # # + ### + #### ####### ####### ####### # + # + #### ####### ### ####### ### + # + #### ### ### ### ##### ### + ### + ######## ########### ##### ### ##### # + ## + ######## ######### ##### # ##### ### +``` + +## Quirk profiles + +CHIP-8 interpreters disagree on a handful of instructions. The profile selects +the behaviour: + +| Behaviour | modern | cosmac | superchip | +|------------------------------|--------|--------|-----------| +| `8XY6/8XYE` shift source | Vx | Vy | Vx | +| `BNNN` offset register | V0 | V0 | Vx | +| `FX55/FX65` increment I | no | yes | no | +| `8XY1/2/3` reset VF | no | yes | no | + +`modern` passes every ROM listed above, including BC_test. `cosmac` matches the +original COSMAC VIP behaviour and also passes the corax opcode tests. + +## Sources for the ROMs + +- `1-chip8-logo` .. `8-scrolling`: Timendus CHIP-8 test suite + (https://github.com/Timendus/chip8-test-suite, MIT). +- `test_opcode.ch8`: corax89 opcode test + (https://github.com/corax89/chip8-test-rom). +- `BC_test.ch8`: BestCoder's opcode test (widely mirrored). + +## Not in this version + +SUPER-CHIP high-res mode and its extra opcodes, XO-CHIP, and save states. +The quirk plumbing and a `superChip` profile are already in place as the +starting point for that work.