A CHIP-8 interpreter/emulator written in Rust with SDL2 for graphics and input handling.
CHIP-8 is an interpreted programming language developed in the 1970s for early microcomputers. This project implements a complete CHIP-8 interpreter with a desktop frontend using SDL2 for rendering and input.
The project is organized into two main components:
The core emulator library containing:
- Complete CHIP-8 instruction set implementation
- Memory management (4KB RAM)
- 16 general-purpose registers (V0-VF)
- Timer systems (delay and sound timers)
- Display buffer (64x32 pixels)
- Keypad input handling
- Built-in font set for hexadecimal digits
The SDL2-based desktop frontend providing:
- Window management and rendering
- Real-time display updates
- Keyboard input mapping
- Game loop implementation
- Memory operations (load, store, copy)
- Arithmetic operations (add, subtract, bitwise operations)
- Control flow (jumps, subroutines, conditionals)
- Graphics rendering with collision detection
- Timer operations
- Random number generation
- Keyboard input handling
- 64x32 monochrome display
- Configurable scaling (currently 15x)
- Real-time rendering with SDL2
- Sprite drawing with XOR pixel operations
- 16-key hexadecimal keypad mapping:
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
- 0x000-0x1FF: Reserved for interpreter
- 0x050-0x0A0: Built-in font set
- 0x200-0xFFF: Program memory (3584 bytes)
- V0-VE: General purpose 8-bit registers
- VF: Flag register (used for carry, borrow, collision)
- I: 16-bit index register
- PC: Program counter
- SP: Stack pointer
- Delay Timer: Decrements at 60Hz, used for timing events
- Sound Timer: Decrements at 60Hz, beeps when non-zero
- Rust (latest stable version)
- SDL2 development libraries
- Download SDL2 development libraries from libsdl.org
- Extract and place
SDL2.dllin the project directory (already included)
sudo apt-get install libsdl2-devbrew install sdl2# Build the project
cd desktop
cargo build
# Build with optimizations
cargo build --release# Run with a ROM file
cargo run /path/to/rom.ch8
# Example with included ROMs
cargo run "../IBM Logo.ch8"
cargo run "../Tetris [Fran Dachille, 1991].ch8"The project includes several test ROMs:
- IBM Logo.ch8: Displays the IBM logo (classic test ROM)
- Tetris [Fran Dachille, 1991].ch8: Tetris game implementation
- test_opcode.ch8: Instruction set test ROM
- OK.ch8: Simple test program
The CHIP-8 keypad is mapped to your keyboard as follows:
| CHIP-8 Key | Keyboard Key |
|---|---|
| 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 |
- Fetch: Read instruction from memory at program counter
- Decode: Parse the 16-bit instruction
- Execute: Perform the corresponding operation
- Update: Decrement timers and update display
CHIP-8 instructions are 16-bit (2 bytes) with the following format:
- nnn: 12-bit address
- nn or kk: 8-bit constant
- n: 4-bit constant
- x and y: 4-bit register identifiers
rand = "0.8.5"- Random number generation
sdl2 = "^0.34.3"- Graphics and input handlingchip8_core- Local core library
- lib.rs: Core CHIP-8 implementation with complete instruction set
- main.rs: SDL2 frontend with rendering and input handling
DISPLAY_WIDTH: 64 pixelsDISPLAY_HEIGHT: 32 pixelsSCALE: 15x scaling factorTICKS_PER_FRAME: 10 (controls emulation speed)
Potential improvements for the emulator:
- Audio support for the sound timer
- Configurable key mappings
- Save states
- Debugger interface
- Support for CHIP-8 variants (SUPER-CHIP, XO-CHIP)
- ROM compatibility testing suite
This project is open source. Please check individual ROM files for their respective licenses.