A minimal Chip-8 interpreter written in C# with NativeAOT compilation support. Runs entirely in the console using ASCII rendering and Windows API keyboard polling. Built as a learning project to understand CPU emulation, memory management, and ahead-of-time compilation in .NET.
- Language: C# / .NET 10
- Runtime: NativeAOT (Ahead-of-Time compilation)
- Platform: Windows (uses
user32.dllfor non-blocking key input) - Dependencies: None
The emulator is split into four core components under the Chip8Emulator.Chip8 namespace, with a single entry point in Program.cs.
Chip8Emulator/
├── Chip8Emulator.csproj # NativeAOT publishing enabled
├── Program.cs # Entry point, game loop, rendering
└── Chip8/
├── Memory.cs # 4KB RAM + fontset
├── Display.cs # 64×32 pixel framebuffer
├── Keyboard.cs # 16-key hex keypad state
└── CPU.cs # Full instruction decoder & ALU
- Manages the 4096 bytes of addressable RAM
- Loads ROMs starting at address
0x200(the Chip-8 convention) - Stores the 16-character fontset at
0x050for the built-inF029instruction - Provides array-style indexing with automatic address masking (
& 0xFFF)
- 64×32 pixel framebuffer stored as a
bool[,] - Wraps coordinates on both axes (
x % 64,y % 32) - Used by the
DXYNdraw instruction to XOR sprite pixels onto the screen - The
00E0clear instruction resets the entire buffer
- Maps the 16-key hex keypad (
0–F) to internal boolean state - Supports two input modes:
- Polled:
EX9E/EXA1skip instructions based on whether a key is held - Blocking:
FX0Awaits until any key is pressed, then returns its index
- Polled:
- Keys are polled every frame via
GetAsyncKeyStatefromuser32.dll
- 35-instruction decoder covering the full Chip-8 opcode set
- 16 general-purpose registers (
V0–VF) plus the 16-bit index registerI - 16-level call stack for subroutine support (
2NNN/00EE) - 8-bit delay and sound timers decremented at 60Hz
- Built-in stack overflow/underflow guards for debugging
┌─────────────────────────────────────────────────────────────┐
│ Program.cs │
│ │
│ 1. Load ROM file into Memory at 0x200 │
│ │
│ 2. Initialize CPU, Display, Keyboard │
│ │
│ 3. Start Game Loop ─────────────────────────────────────► │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│ │ Poll Keys │ │ Run CPU │ │ Update │ │
│ │ (60+ Hz) │ │ Cycles │ │ Timers │ │
│ │ │ │ (~700 Hz) │ │ (60 Hz) │ │
│ │ user32.dll │ │ Decode + │ │ Delay & │ │
│ │ GetAsyncKey │ │ Execute │ │ Sound │ │
│ │ State │ │ opcodes │ │ countdown │ │
│ └──────┬──────┘ └──────┬──────┘ └─────┬─────┘ │
│ │ │ │ │
│ └───────────────────┼────────────────────┘ │
│ ▼ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Render: 64×32 ASCII frame to Console │ │
│ │ (█ = pixel on, space = pixel off) │ │
│ └───────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 4. Repeat until ESC pressed ─────────────────────────────► │
│ │
└─────────────────────────────────────────────────────────────┘
- Fetch — Read two bytes from RAM at
PCandPC + 1, combine into a 16-bit opcode - Decode — Extract bitfields:
X=(opcode & 0x0F00) >> 8(register index)Y=(opcode & 0x00F0) >> 4(register index)N=opcode & 0x000F(nibble)NN=opcode & 0x00FF(byte)NNN=opcode & 0x0FFF(address)
- Execute — Switch on the top nibble (
0xF000) and perform the operation - Advance — Increment
PCby 2 (unless the instruction itself jumps or calls)
| Feature | Implementation |
|---|---|
| NativeAOT | Publishes as a self-contained .exe with zero runtime dependencies |
| Console Rendering | StringBuilder batch-writes 64×32 ASCII characters per frame |
| Non-blocking Input | GetAsyncKeyState detects held keys, critical for paddle games |
| Instruction History | Debug queue tracks last 20 opcodes for crash diagnostics |
| Sound Timer | Console.Beep fires when SoundTimer > 0 |
dotnet run -- <rom-file>dotnet publish -c Release -r win-x64Output: bin/Release/net8.0/win-x64/publish/Chip8Emulator.exe
# Run the classic IBM logo test
Chip8Emulator.exe "IBM Logo.ch8"
# Play a game
Chip8Emulator.exe "Pong.ch8"
# Exit any time by pressing ESC| Chip-8 | Keyboard |
|---|---|
1 |
1 |
2 |
2 |
3 |
3 |
C |
4 |
4 |
Q |
5 |
W |
6 |
E |
D |
R |
7 |
A |
8 |
S |
9 |
D |
E |
F |
A |
Z |
0 |
X |
B |
C |
F |
V |
- Console over GUI: Zero dependencies and instant NativeAOT compatibility
- ASCII rendering:
StringBuilderbatches all 2048 characters into a singleConsole.Writecall per frame - Windows API for input:
Console.ReadKey()only fires on key press, not hold;GetAsyncKeyStatecorrectly detects held keys for paddle movement - Modern shift behavior:
8XY6and8XYEoperate onVXdirectly (post-CHIP-48 standard) - 'I' register not incremented on FX55/FX65: Matches the behavior modern test ROMs expect
Check out this guide by Austin Morlan for an in-depth guide on how to build your own