chipate

Space Invaders ROM by David Winter

A small CHIP-8 interpreter written in C++, rendered with SDL3. A hobby project for the fun of writing an emulator from scratch — complete with a Game Boy-style green color scheme for the nostalgic feel :)

Quick Start

Get a game running in four steps:

1. Clone the repository and enter it:

   git clone https://github.com/itsnotsherm/chipate.git
   cd chipate

2. Configure the build — this also pulls in Catch2 for the tests:

   cmake -B build

3. Build the interpreter:

   cmake --build build

4. Run a ROM:

   ./build/chipate <ROM file>

That's it — press Esc or close the window to quit. See Controls for the keypad layout and Tests for running the unit tests.

What's included

• src/ — the interpreter core (chip8.cpp/chip8.hpp) and the SDL frontend (main.cpp)
• tests/ — unit tests for the CPU core (Catch2)
• vendored/SDL — a bundled copy of SDL3, so there's nothing extra to install

Requirements

• A C++17 compiler
• CMake 3.22 or newer

SDL3 is vendored in vendored/SDL, so it builds along with the project — no separate install needed.

Building

cmake -B build
cmake --build build

The chipate executable is placed in build/.

Running

Pass a ROM file as the only argument:

./build/chipate roms/space_invaders.ch8

Press Esc (or close the window) to quit.

Controls

CHIP-8 uses a 16-key hex keypad, mapped to the left side of a QWERTY keyboard:

 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

The mapping is by physical key position, not by the letter printed on the key. chipate reads scancodes rather than characters, the layout above holds on a QWERTY board, and on other layouts (AZERTY, Dvorak, etc.) those same physical positions are used regardless of what letters they produce. Do refer to a keyboard layout comparison if needed! :)

Tests

Tests build by default. To run them:

cmake --build build
ctest --test-dir build

You can turn the test build off with -DCHIPATE_BUILD_TESTS=OFF. Catch2 is fetched automatically by CMake when tests are enabled.

Future Improvements

Ideas I'd like to explore in the future for this interpreter:

• Audio: the sound timer logic has already been written and ticking in the core; would do some audio programming in SDL3 to make this complete.
• ROM selection: a menu to browse and load ROMs from a directory instead of passing a path on the command line.
• Configurable speed: a way to tune the instructions-per-frame to the user's preference.
• Adjustable color themes: a way to add preset/custom color themes to switch between to the user's preference.
• Any other suggestions: I am open to any suggestions that could make this project more fun, do create an issue or reach out to me! :)

References

Guides and resources I found useful while building chipate:

• Cowgod's Chip-8 Technical Reference
• Guide to making a CHIP-8 emulator by Tobias V. Langhoff
• SDL3 Documentation

License

MIT — see LICENSE.