Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Chip-8 Emulator

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.

Tech Stack

  • Language: C# / .NET 10
  • Runtime: NativeAOT (Ahead-of-Time compilation)
  • Platform: Windows (uses user32.dll for non-blocking key input)
  • Dependencies: None

Architecture

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

Components

Memory

  • Manages the 4096 bytes of addressable RAM
  • Loads ROMs starting at address 0x200 (the Chip-8 convention)
  • Stores the 16-character fontset at 0x050 for the built-in F029 instruction
  • Provides array-style indexing with automatic address masking (& 0xFFF)

Display

  • 64×32 pixel framebuffer stored as a bool[,]
  • Wraps coordinates on both axes (x % 64, y % 32)
  • Used by the DXYN draw instruction to XOR sprite pixels onto the screen
  • The 00E0 clear instruction resets the entire buffer

Keyboard

  • Maps the 16-key hex keypad (0–F) to internal boolean state
  • Supports two input modes:
    • Polled: EX9E / EXA1 skip instructions based on whether a key is held
    • Blocking: FX0A waits until any key is pressed, then returns its index
  • Keys are polled every frame via GetAsyncKeyState from user32.dll

CPU

  • 35-instruction decoder covering the full Chip-8 opcode set
  • 16 general-purpose registers (V0–VF) plus the 16-bit index register I
  • 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

Execution Flow

┌─────────────────────────────────────────────────────────────┐
│                        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 ─────────────────────────────►  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Instruction Fetch-Decode-Execute Cycle

  1. Fetch — Read two bytes from RAM at PC and PC + 1, combine into a 16-bit opcode
  2. 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)
  3. Execute — Switch on the top nibble (0xF000) and perform the operation
  4. Advance — Increment PC by 2 (unless the instruction itself jumps or calls)

Key Features

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

Build & Run

Standard (JIT)

dotnet run -- <rom-file>

NativeAOT (Recommended)

dotnet publish -c Release -r win-x64

Output: bin/Release/net8.0/win-x64/publish/Chip8Emulator.exe

Usage

# Run the classic IBM logo test
Chip8Emulator.exe "IBM Logo.ch8"

# Play a game
Chip8Emulator.exe "Pong.ch8"

# Exit any time by pressing ESC

Keyboard Mapping

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

Design Decisions

  • Console over GUI: Zero dependencies and instant NativeAOT compatibility
  • ASCII rendering: StringBuilder batches all 2048 characters into a single Console.Write call per frame
  • Windows API for input: Console.ReadKey() only fires on key press, not hold; GetAsyncKeyState correctly detects held keys for paddle movement
  • Modern shift behavior: 8XY6 and 8XYE operate on VX directly (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

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages