CHIP-8 Interpreter

A CHIP-8 interpreter written in C with SDL3. Plays classic CHIP-8 games with sound and graphics, includes a terminal debugger for development. Works with all original COSMAC VIP games and handles the quirks properly.

Demonstration

demonstration.mp4

Installation

0. Ensure CMake 3.10+ and C compiler are installed.

1. Clone and navigate to the repository:

   git clone --recurse-submodules https://github.com/nikijaz/chip-8.git  
   cd chip-8

2. Create a build directory and set up the project:

   mkdir build && cd build  
   cmake ..

3. Build the interpreter:

   make

4. Run with a CHIP-8 ROM file:

   ./chip-8 path/to/rom.ch8

Controls

CHIP-8 uses a 16-key hexadecimal keypad mapped to your keyboard:

CHIP-8 Keypad      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

Press Escape to quit the program.

Debugging

Run with the --debug flag to enable the terminal-based debugger:

./chip-8 path/to/rom.ch8 --debug

The debugger provides two views:

• Overview: Shows all 16 registers (V0-VF), stack contents, program counter, index register and timers.
• Memory Dump: Displays memory contents in hexadecimal format with paging support.

Debug controls:

• P - Pause/resume execution
• N - Execute next instruction (when paused)
• M - Switch between different views
• ,/. - Navigate memory dump pages (previous/next)