Rust CHIP-8 Emulator

A functional CHIP-8 interpreter/emulator written in Rust. It utilizes SDL2 for rendering, audio, and input handling.

⚠️ Prerequisites & Installation (Crucial)

This project relies on the SDL2 C library. You cannot simply run cargo build without installing the SDL2 development libraries on your operating system first. If you skip this step, the build will fail with linker errors.

1. Install SDL2Linux

sudo apt-get update
sudo apt-get install libsdl2-dev

sudo pacman -S sdl2_gfx --noconfirm # for arch

2. Build the Project

Once SDL2 is installed on your system:

# Clone the repository
git clone https://github.com/thehackersbrain/chip8.git
cd chip8

Build the project

cargo build

🚀 Usage

To run a game, pass the path to a CHIP-8 ROM file as an argument.

# Syntax
cargo run -- <path_to_rom>
# or
./chip8 <path_to_rom>

# Example (Running Tetris)
./chip8 games/TETRIS

🎮 Controls (Key Mapping)

The CHIP-8 uses a hexadecimal keypad (0–F). This emulator maps those keys to the left side of your QWERTY keyboard to preserve the original 4×4 grid layout.

CHIP-8 Keypad → QWERTY Mapping

CHIP-8   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

---

🎮 Common Game Controls

Different ROMs use different setups, but here are defaults for popular ones:

Tetris

• Rotate: W
• Left: Q
• Right: E
• Drop: S

Tic-Tac-Toe

Input corresponds directly to the keypad grid:

• Row 1: 1–3
• Row 2: Q–E
• Row 3: A–D

Space Invaders

• Start: W (Key 5)
• Shoot: W (Key 5)
• Left: Q (Key 4)
• Right: E (Key 6)

---

📂 Project Structure

src/main.rs

• Entry point: game loop, timing, drivers, initialization

src/processor.rs

• CPU core: fetch → decode → execute

src/constants.rs

• Screen size, memory size, and other global config

src/drivers/

• display_driver.rs — SDL2 drawing logic
• audio_driver.rs — square-wave beep generator
• input_driver.rs — keyboard scancode → CHIP-8 input mapper
• cartridge_driver.rs — loads ROM bytes into memory

src/font.rs

• Built-in 0-F hex sprite data

🔧 Configuration

To tweak emulation speed, modify this in src/main.rs:

// Increase or decrease this to adjust emulation speed
// 2 ms ≈ ~500 Hz
let sleep_duration = Duration::from_millis(2);

📜 License This project is open source. Feel free to fork and modify!