CHIP-8 Emulator

A CHIP-8 interpreter written in C using SDL2 for graphics, input, and audio.

Features

• Full CHIP-8 instruction set (all 35 opcodes)
• SDL2-based display, keyboard input, and square-wave audio for the sound timer
• Configurable emulation speed (instructions per frame)
• A chipx command-line tool for launching ROMs from anywhere on your system, with fuzzy name matching and a numbered ROM browser
• Built-in test targets for validating opcode correctness against the Timendus CHIP-8 test suite and the IBM logo test ROM

Demo

https://github.com/user-attachments/assets/fcc2e3ee-be03-496d-ba1d-31d5049c34c7

Requirements

• gcc (or another C17-compatible compiler)
• make
• SDL2 development libraries

On Arch Linux:

sudo pacman -S sdl2

On Debian/Ubuntu:

sudo apt install libsdl2-dev

Building

make

This produces the emulator binary at build/program.

Running a ROM directly

make run ROM="rom/Tetris [Fran Dachille, 1991].ch8"

or by fuzzy name:

make run rom=tetris

Installing chipx (recommended)

To install the emulator as a global command, callable from any terminal or directory:

./install.sh

This will:

• Build the project
• Copy the compiled binary and ROM library to ~/.local/share/chip8
• Install a chipx command to ~/.local/bin
• Add ~/.local/bin to your shell's PATH if it isn't already there (fish, bash, and zsh are detected automatically)

Restart your terminal (or run exec fish / source ~/.bashrc, depending on your shell) after installing for the chipx command to become available.

Usage

chipx                # numbered menu of every ROM
chipx tetris          # fuzzy-match by name and launch directly
chipx space           # multiple matches -> prompts you to pick one
chipx -h              # help

Uninstalling

make uninstall

Controls

CHIP-8 uses a 16-key hexadecimal keypad, mapped to the following keys:

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

Controls vary per game — check each ROM's accompanying .txt file where available, since key bindings are not standardized across CHIP-8 programs.

Press Backspace to quit the emulator at any time.

Testing

Run the full opcode/quirks test suite:

make test

Run an individual numbered test (e.g. the flags test):

make test-4

List all available ROMs:

make list

Project Structure

.
├── main.c
├── src/                    # Core emulator implementation
│   ├── emulator_core.c
│   ├── emulator_operations.c
│   ├── emulator_display.c
│   └── emulator_audio.c
├── include/                # Headers
├── rom/                    # ROM library (see Credits)
├── install.sh              # One-step build + install script
├── emu-runner.sh           # The chipx command dispatcher (installed as `chipx`)
└── Makefile

Credits

ROMs included in the rom/ directory are sourced from kripod/chip8-roms, a public domain compilation of CHIP-8 programs originally assembled by Revival Studios. Original authorship of individual games belongs to their respective creators, credited where known in each ROM's filename or accompanying .txt file.

The Timendus CHIP-8 test suite and the IBM logo test ROM are used for opcode/quirks validation during development.

References

This emulator's instruction set and behavior were implemented primarily based on:

• Cowgod's CHIP-8 Technical Reference — the de facto standard opcode reference used by most CHIP-8 implementations
• Columbia University's CHIP-8 Design Specification — used as a secondary reference for architecture and timing behavior

License

This project is licensed under the MIT License — see LICENSE for details.

ROMs in the rom/ directory retain their own original licensing/public domain status as documented by their respective sources and are not covered by this project's license.