135 lines
5.3 KiB
Markdown
135 lines
5.3 KiB
Markdown
# 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.
|