CHIP-8 Emulator

This repository contains a CHIP-8 emulator, which emulates the CHIP-8 virtual machine architecture used in the 1970s and 1980s for programming simple games. The emulator can load and execute CHIP-8 games, offering a window into early low-level programming and emulator development.

The project is based on the work of Austin Morlan from October 2024, whose guide and codebase were instrumental in building this emulator.

Table of Contents

• CHIP-8 Emulator
  • CHIP-8 Overview
    • CHIP-8 Specifications
  • Project Structure
    • Key Files
  • Setup and Installation
    • Prerequisites
      • On Ubuntu
    • Building the Emulator
  • Usage
    • Controls
  • Running Tests
    • New tests
  • Acknowledgments
  • License

---

CHIP-8 Overview

The CHIP-8 is a simple, interpreted programming language used on early computers such as the COSMAC VIP and the Telmac 1800. Although primitive by modern standards, CHIP-8 was designed for writing games, with a limited instruction set that still allows for creative projects.

CHIP-8 Specifications

• Memory: 4KB (4096 bytes)
• Registers: 16 general-purpose 8-bit registers
• Graphics: Monochrome display with a resolution of 64x32 pixels
• Input: 16-key hexadecimal keypad

For more information, see Austin Morlan's blog.

Project Structure

This repository is organized as follows:

CHIP-8_emulator/
├── .github/           # Handles GitHub CI/CD
├── .gitlab-ci.yml     # Handles GitLab CI/CD
├── refs/              # Reference for the project development
├── docs/              # Documentation of the project
├── include/           # Header files (e.g., Chip8.h, Chip8Constants.h)
├── src/               # Source files (e.g., Chip8.cpp, main.cpp)
├── tests/             # Unit tests using GoogleTest
├── build/             # Compiled binary and object files (generated by Makefile)
├── Makefile/CMakeList # Build instructions for the project
└── README.md          # Project documentation

Key Files

• Chip8.h: Header file defining the Chip8 class, which contains the core emulator components.
• Chip8.cpp: Implements the functionality of the Chip8 class.
• main.cpp: Entry point for the emulator, initializing and running the emulator loop.
• Makefile: Build instructions for the project.

Setup and Installation

This emulator is built using C++20 and requires the SDL2 library for rendering and input handling.

Prerequisites

• C++20 compiler (e.g., g++)
• SDL2 library installed on your system

On Ubuntu

sudo apt update
sudo apt-get install -y g++ make cmake ninja-build libsdl2-dev doxygen doxygen-gui doxygen-latex graphviz gcov lcov gcovr
sudo apt autoremove

Building the Emulator

Clone this repository and run the Makefile to build the project:

git clone https://github.com/n2oblife/CHIP-8_emulator.git
cd CHIP-8_emulator
make all

If successful, the compiled binary will be located in build/bin/chip8.

Usage

Once built, you can load and run a CHIP-8 game ROM (like this one) by providing the ROM file as a command-line argument:

make run path/to/romfile.ch8

Controls

Most CHIP-8 programs are designed for a 16-key hexadecimal keypad:

1 2 3 C
4 5 6 D
7 8 9 E
A 0 B F

These keys map to your keyboard, typically as follows:

1 2 3 4
Q W E R
A S D F
Z X C V

Running Tests

To run all tests and display failures, use:

make tests

This will execute all test cases and show detailed output if any test fails. The results are saved in log/report, with a unique ID consisting of the commit hash and timestamp.

New tests

Create a New Test File Test files should be placed in the tests/ directory and named with the Test*.cpp prefix.

For example:

tests/
 ├── TestChip8.cpp
 ├── TestOpcodes.cpp
 ├── TestPlatform.cpp

Include Google Test: In your test file, include gtest/gtest.h and any required headers from the project.

Acknowledgments

Special thanks to Austin Morlan for his CHIP-8 emulator guide, which inspired and guided this project.

License

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