Python CHIP-8 Interpreter

Overview

A Python based GUI implementation of the CHIP-8 system. A project I developed with the intention of gaining knowledge about emulators and cross platform GUI libraries. For more specific information about the CHIP-8 system, please refer to the following technical reference article on CHIP-8 and the WIKI. Built using Python and other open source technologies.

Features

• Implementation of all 35 CHIP-8 opcodes
• Built-in debugger
• Custom pixel and background colours
• Saving and loading emulation state
• Sound effects

Debugger

The emulator includes a built-in debugger that can be opened from File > Debug.

The debugger provides:

• Current Program Counter (PC)
• Current Opcode (OP)
• Index Register (I)
• All CHIP-8 registers (V0–VF)
• Delay and Sound timers
• Stack inspection
• Full 4 KB memory view
• Highlighting of the currently executing instruction
• Single step execution
• Run / Stop controls for pausing and resuming execution

When the debugger is open, the emulator can be paused and advanced one instruction at a time, making it easier to understand program flow, troubleshoot ROMs, and verify opcode implementations.

Prerequisite Software

Software	Version
Python	3.11+

ROMs

ROMs for the CHIP-8 system can be obtained online for free at Internet Archive.

Getting Started

You will need to setup a python virtual environment and install the project's dependencies.

1. Skip this step if you're using Windows. If you're using Mac or Linux, you may need to install pip and virtualenv first:

sudo apt-get install python3-pip
sudo pip3 install virtualenv

2. Navigate to your CHIP-8 repo and create a new virtual environment with the following command:

# Windows
python -m venv venv

# Mac or Linux
virtualenv venv

3. Enable your virtual environment with the following command:

# Windows
source venv/Scripts/activate

# Mac or Linux
source venv/bin/activate

Your command line will be prefixed with (venv) which indicates that the virtual environment is enabled.

4. Install the project's dependencies with the following command:

pip install -r requirements.txt

If you have recently pulled changes from a remote branch, you should re-run the above command to obtain any new dependencies that may have been added to the project.

Running

1. Enable your virtual environment with the following command:

# Windows
source venv/Scripts/activate

# Mac or Linux
source venv/bin/activate

2. Launch the CHIP-8 interpreter app with the following command:

python app.py

Controls

The CHIP-8 system uses a hexadecimal keyboard that has 16 keys from 0 to 9 and A to F. Keys 2, 4, 6 and 8 are typically used for directional input.

The following keyboard layouts specify the CHIP-8 Keyboard and the Interpreter KeyBoard used in the application.

Running Tests

To run the CHIP-8 test suite, use the following command from the project root:

python -m chip8.tests.main

This will execute all available unit tests for the CHIP-8 implementation.

Contributing

Please see our Contributing Guide for more info.

Project Structure

.
├── app.py                    # Alternate entry point
├── debug_window.py           # CHIP-8 debugger
├── assets/                   # Assets (fonts, ROMs, etc)
├── chip8/                    # CHIP-8 Python package
│   ├── __init__.py           # Package init file
│   ├── chip8.py              # CHIP-8 CPU logic
│   ├── stack.py              # Stack data structure
│   └── ...                   # Other CHIP-8 core files
├── frame.py                  # Frame rendering logic
├── LICENSE.md                # License file
├── README.md                 # Project documentation
├── requirements.txt          # Dependencies to install with pip
├── SECURITY.md               # Security policy
├── settings.ini              # Application settings
├── settings.py               # Settings logic
├── utils.py                  # Utilities
├── window.py                 # Window management
└── __pycache__/              # Python bytecode cache