CHIP-8pp

A simple CHIP-8 emulator written in C++

Passed all the tests from the Timendus chip8-test-suite.

Table of content

• Getting started - Installation
• Build and Run
  • Classical way (local)
    • Build
    • Run
  • Docker container
    • Docker compose
    • Bash script
• Miscellaneous
• Acknowledgement

Getting started

First clone this repository

git clone <repository_url>

Build and Run

Classical way (local)

Build

You can create a build folder and execute the following commands:

mkdir build
cd build
cmake ..
make

The generated executable is called emulator.

Run

There are 3 options required to correctly run the emulator:

• ROM path
• Resolution scale factor
• CPU cycle delay

Here's an example command to properly use the binary:

./emulator roms/pong.ch8 10 1

Docker container

You can build the project's container by running this command:

docker build -t chip8pp .

Then, two options can be considered to run the container.

Docker compose & .env file

To run the container this way, you have to create a .env file following the .env.example template.

Granting access to X11 (Linux only)

On Linux, you need to grant access to the X11 server for Docker, because SDL needs to open a graphical window. If you choose to use the Docker Compose command, you must first run the following command:

xhost +local:docker

Note: This is required only if you are using the X11 display server. On systems running Wayland (e.g., recent Ubuntu, Fedora), additional configuration may be needed, as xhost might not be sufficient.

Then just run the following command:

docker compose run --rm chip8pp

Note that you can also specify one or more arguments to override the values in .env. Here's an example

ROM_PATH=roms/superpong.ch8 docker compose run --rm chip8pp

Bash script

There's also a script that you can use to run the container. It requires 3 arguments (same as before) to run properly. You can use it like this:

./run_container.sh -r roms/pong.ch8 -s 10 -d 1

Miscellaneous

Here are some bonus features/modes

Key	function
m	Mute emulator sound

Acknowledgement

I would like to thank Cowgod's for the amazing Chip-8 Technical Reference and Timendus for the CHIP-8 test suite repository.

These resources allowed me to precisely understand how Chip-8 works and test/debug the emulator properly !