CHIP-8 Emulator (C++ & React Web)

A dual-platform CHIP-8 interpreter featuring a high-performance C++ Desktop Application and a modern React + TypeScript Web Application. Both versions support dynamic instruction speed adjustment, compatibility quirks toggles, audio, and live register debug panel views.

🌐 Live Demo: shinnei.github.io/Chip-8-Emulator/

---

🚀 Key Features

• Dual Platform Execution: Play games and run test suites directly on the desktop (via C++/SDL2) or in a modern web browser (via React/Canvas).
• Live Register Debug Panel:
  • Web HUD: A transparent overlay displaying Program Counter (PC), Index Register (I), Timers (DT, ST), current Opcode, Registers (V0-VF), and execution Stack directly on top of the game screen (without shrinking/affecting game rendering aspect-ratio).
  • C++ Console HUD: An ANSI escape-sequence dashboard rendered in real-time in the terminal window (toggled with F4).
• Compatibility Quirks Configuration: Real-time toggles for standard quirks, including:
  • Shift Quirk (8xy6 / 8xyE): Choose whether to copy VY to VX before shifting.
  • Jump Quirk (Bnnn): Jump to nnn + V0 (standard CHIP-8) or nnn + VX (CHIP-48/SCHIP).
  • Memory Index Quirk (Fx55 / Fx65): Toggle automatic incrementing of the I register.
• Audio Feedback: Real-time buzzer sound support on both platforms.
• Preloaded ROM Library: Pre-bundled game and test ROMs (Pong, Tetris, Lunar Lander, Sierpinski Fractal, Quirks Test, etc.).

---

🛠 Tech Stack

• Core Interpreter: C++17 (for high execution speed and precision).
• Desktop App: SDL2 (Simple DirectMedia Layer) for graphics, input polling, and audio output. Build configuration managed via CMake.
• Web App: Built with React 18, TypeScript, and Vite. Leverages HTML5 <canvas> for pixel rendering and the Web Audio API for tone generation.

---

📚 CHIP-8 Instruction Set Reference

The emulator implements the standard CHIP-8 instruction set consisting of 35 two-byte opcodes. For full architectural details, refer to:

• CHIP-8 Instruction Set - Wikipedia
• Cowgod's CHIP-8 Technical Reference v1.0

---

🖥 How to Run

1. C++ Desktop App (Windows/macOS/Linux)

Prerequisites

• A C++17 compiler (e.g. GCC, Clang, MSVC)
• CMake (version 3.12+)
• SDL2 Development Library

Building and Running

# Configure the build system (using CMake)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

# Compile the executable
cmake --build build --config Release

# Run the emulator, passing the ROM path as an argument
./build/chip8.exe ROM/game/tetris.ch8

Key Mappings (C++ Desktop App)

• Hex Keypad (Input):
  • 1 2 3 4 ➔ mapping to CHIP-8 1 2 3 C
  • Q W E R ➔ mapping to CHIP-8 4 5 6 D
  • A S D F ➔ mapping to CHIP-8 7 8 9 E
  • Z X C V ➔ mapping to CHIP-8 A 0 B F
• Emulator Controls:
  • F1 ➔ Toggle Shift Quirk
  • F2 ➔ Toggle Jump Quirk
  • F3 ➔ Toggle Memory Index Quirk
  • F4 ➔ Toggle Live Register Debug Panel (printed in terminal)
  • F5 ➔ Reset ROM execution
  • P ➔ Play / Pause emulation
  • + / - ➔ Increase / Decrease speed ticks per frame

---

2. React Web App (Browser-Based)

Prerequisites

• Node.js (v18.0+)

Getting Started

# Navigate to the web project directory
cd chip8-web

# Install dependencies
npm install

# Run the local development server
npm run dev

Open http://localhost:5173/ in your web browser.

Building for Production

npm run build

Production assets will be built in the chip8-web/dist/ directory.

---

📬 Contact & Information

• Developer: Shinnei
• GitHub: github.com/Shinnei
• Email: dst15092004@gmail.com