CHIP-8 Emulator (C)

A Chip-8 emulator written in C with built-in debugger support.

---

📖 Table of Contents

• Features
• Build & Installation
• Run
• Test Status
• Notes
• Idea Board
• Contributing
• License

---

✨ Features

• Full Chip-8 instruction set
• Built-in debugger (step, breakpoints, inspect memory/registers)
• SDL2 display (texture-based rendering) with resizable windows
• GPU rendering with CPU fallback
• Keyboard input with customizable key mapping
• Monochrome pixel color selector
• Support for Legacy CHIP-8 and Modern CHIP-8
• Ambiguous opcode selection
• Safety ensured using compiler hardening
• POSIX supported

---

⚙️ Build & Installation

Clone the repository using:

git clone https://github.com/Afsan-z47/CHIP-8.git

Or Download the .zip file and extract

Run these instructions in the CHIP-8 directory:

Build

For normal build use the following instruction:

make

Rigorous Testing

Use this for testing

make debug

Includes additional tests from Compiler Hardening Guidelines

Clean Up

For removing built chip8 and chip8-debug.

make clean

---

▶️ Run

Run without options:

./chip8

will show the following help:

Usage: ./chip8 [options]
  -r <file>  -> rom <file>        ROM file to load
  -d 	     -> debug             Enable debugger
  -a <file>  -> audio <file.wav>  Audio file
  -k 	     -> Customize Keyboard
  -c <n>     -> color <value>     Set Pixel Color
  Values for <n> is [RED] [BLUE] [GREEN] [YELLOW] [CYAN] [MAGENTA] [WHITE](default) 
  -h 	     -> help              Show this help
  ==============================================
  Ambiguous instruction flags
  -S 	     -> Shift VY instead of Vx for [8XY6] and [8XYE]
  -F 	     -> Change value of I for [FX55] and [FX56]
  -J 	     -> Use VX instead of V0 for [BNNN]
  -D 	     -> Stop CPU when rendering DISPLAY
  -V 	     -> AND[8xy1], OR[8xy2], XOR[8xy3] resets VF to zero
  -O 	     -> Original CHIP-8 behaviour
  Using other ambigious instruction flags with "-O" will flip the optins

Too simply run use:

./chip8 -r <path_to_your_rom.ch8>

A more customiable command will look like this:

./chip8 -a <audio_file> -r <path_to_your_rom.ch8> -c <color> -h[help] -SFJDV[Alike ambiguous instruction flags] -k[this ones for keyboard]

Examples

Run with audio (default: beep.wav):

./chip8 -a beep.wav -r roms/Tests/2-ibm-logo.ch8

Run in Modern mode (default):

./chip8 -r roms/Tests/5-quirks.ch8

Run in Legacy mode:

./chip8 -r roms/Tests/5-quirks.ch8 -O

These had [ -c Yellow ] flags added

Modern CHIP-8	Legacy CHIP-8

---

✅ Test Status

Test ROMs from Timendus’ Chip-8 Test Suite

• IBM Logo
• Keypad test
• Buzzer test
• Delay timer test
• Instruction tests
• Super-CHIP
• XO-CHIP
• Debugger
• Miscellaneous behavior
• Complete test → Timendus CHIP-8 Test Suite

---

📝 Notes

Keyboard Layout Mapping

The CHIP-8 uses a 16-key hexadecimal keypad, mapped to your host keyboard as:

CHIP-8:      Host 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 display uses SDL2 and is scaled for visibility.
• Debugger UI (step, breakpoints, watch) is in progress.

---

🚀 Idea board

Ideas to be implemented

• JIT
• Super-CHIP support
• XO-CHIP support

---

🤝 Contributing

Contributions are welcome! Feel free to open issues, submit PRs. Please do not suggest improvements but if you have one implemented make a pull request. We will review it and accept it.

---

📜 License

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