docs: add project README

2026-08-28 23:10:48 +02:00
1 parent 152110188d
commit bafcec6831
@@ -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.