chipATE

A CHIP-8 emulator that runs in your terminal

Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
3. Usage
4. Controls
5. Roadmap
6. Contributing
7. Acknowledgments

About The Project

chipATE is a CHIP-8 emulator built in Rust that renders directly in your terminal using a TUI (Text User Interface). Play classic CHIP-8 games like Pong, Tetris, Space Invaders, and Tic-Tac-Toe without leaving the command line.

Built With

(back to top)

Getting Started

Prerequisites

• Rust toolchain (1.70+)
• A terminal with unicode support

Installation

1. Clone the repo

   git clone https://github.com/CK-7vn/chipATE.git
   cd chipATE

2. Build the project

   cargo build --release

(back to top)

Usage

Run a ROM:

cargo run --release roms/tictac.ch8

Optionally specify cycles per frame (default: 12):

cargo run --release roms/pong.ch8 20

Included ROMs

ROM	Description
tictac.ch8	Tic-Tac-Toe
pong.ch8	Classic Pong
tetris.ch8	Tetris
invaders.ch8	Space Invaders
br8kout.ch8	Breakout
maze.ch8	Random maze generator

(back to top)

Controls

CHIP-8 uses a 16-key hexadecimal keypad. The mapping is:

CHIP-8 Keypad        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 │
└───┴───┴───┴───┘    └───┴───┴───┴───┘

Press Esc to quit.

(back to top)

Roadmap

• Core CHIP-8 instruction set
• TUI display with ratatui
• Keyboard input
• Sound timer (terminal beep)
• SUPER-CHIP support
• Configurable color themes
• Save states

See the open issues for known issues and feature requests.

(back to top)

Contributing

Contributions are welcome! Fork the repo and submit a pull request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Acknowledgments

• Cowgod's CHIP-8 Technical Reference
• Ratatui
• CHIP-8 Test ROMs

(back to top)