# 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.