Rust8

A small CHIP‑8 emulator written and tested in Rust. Great for learning emulator internals while using modern Rust tooling.

Overview

Rust8 is a toy project of mine to get more into the world of emulating. It implements the classic CHIP‑8 instruction set and provides a simple command-line interface to load and run .ch8 ROMs. The code is organized to make experimenting with features (step debugging, display scaling, timers, and the input layer).

Requirements

1. Rust toolchain (stable). Install from https://rustup.rs if you don’t already have it.
2. SDL2. See Cargo.toml for exact dependencies.

Getting started

1. Build

# clone the repo
git clone https://github.com/<your-username>/chip8-rs.git
cd rust8


# build in release mode for best performance
cargo build --release

2. Run a ROM

# run a ROM (release)
cargo run --release -- roms/PONG.ch8

Key mapping

CHIP‑8 original keypad layout (hex) is usually mapped to the PC keyboard as follows (common mapping used by many emulators):

CHIP-8 Key	PC Key
1	1
2	2
3	3
C	4
4	Q
5	W
6	E
D	R
7	A
8	S
9	D
E	F
A	Z
0	X
B	C
F	V

You can modify the mapping in src/input.rs.

Implemented operations

All implemented operations (as well as their quirks) are based on Octo IDE instruction set: https://johnearnest.github.io/Octo/docs/chip8ref.pdf

Codebase structure

The codebase is structured roughly as:

src/ 
    cpu/
        mod.rs #interpreter: fetch-decode-execute
    frontend/
        display.rs # framebuffer and renderer
        input.rs # keyboard mapping and event pump
    main.rs # CLI args and game loop

Testing

To run tests simply run:

cargo test