buttery8/README.md

The buttery chip-8

Just a personal project for me to get the hang of emulator development.

Load a .ch8 rom with buttery8 filename.ch8.

TODO

Project Setup

• Initialize Rust project
• Set up Cargo.toml with dependencies
• Set up window/display library (I went with minifb)
• Set up audio library
• CLI ROM loading via command line argument

CPU / Core

• Define CPU struct (registers, memory, stack, timers, PC, I)
• Load ROM into memory at 0x200
• Load fontset into memory at 0x050
• Fetch / decode / execute loop
• Proper cycle timing

Opcodes

• 00E0 - CLS (clear display)
• 00EE - RET (return from subroutine)
• 1nnn - JP addr
• 2nnn - CALL addr
• 3xkk - SE Vx, byte
• 4xkk - SNE Vx, byte
• 5xy0 - SE Vx, Vy
• 6xkk - LD Vx, byte
• 7xkk - ADD Vx, byte
• 8xy0 - LD Vx, Vy
• 8xy1 - OR Vx, Vy
• 8xy2 - AND Vx, Vy
• 8xy3 - XOR Vx, Vy
• 8xy4 - ADD Vx, Vy (with carry)
• 8xy5 - SUB Vx, Vy (with borrow)
• 8xy6 - SHR Vx
• 8xy7 - SUBN Vx, Vy (with borrow)
• 8xyE - SHL Vx
• 9xy0 - SNE Vx, Vy
• Annn - LD I, addr
• Bnnn - JP V0, addr
• Cxkk - RND Vx, byte
• Dxyn - DRW Vx, Vy, nibble (draw sprite)
• Ex9E - SKP Vx (skip if key pressed)
• ExA1 - SKNP Vx (skip if key not pressed)
• Fx07 - LD Vx, DT (read delay timer)
• Fx0A - LD Vx, K (wait for key press)
• Fx15 - LD DT, Vx (set delay timer)
• Fx18 - LD ST, Vx (set sound timer)
• Fx1E - ADD I, Vx
• Fx29 - LD F, Vx (set I to font sprite)
• Fx33 - LD B, Vx (BCD conversion)
• Fx55 - LD [I], Vx (store registers to memory)
• Fx65 - LD Vx, [I] (read registers from memory)

Display

• 64x32 pixel framebuffer
• XOR sprite drawing
• Set VF on sprite collision
• Render framebuffer to window
• Correct draw timing / refresh rate

Input

• Map keyboard to CHIP-8 hex keypad (0x0-0xF)
• Key pressed state
• Key released state
• Blocking wait for keypress (Fx0A)

Timers

• Delay timer counts down at 60hz
• Sound timer counts down at 60hz
• Buzzer sounds while sound timer > 0

Audio

• Generate beep / tone while sound timer active

Testing & Compatibility

• Pass 1-chip8-logo.ch8
• Pass 2-ibm-logo.ch8
• Pass 3-corax+.ch8
• Pass 4-flags.ch8
• Pass 5-quirks.ch8
• Pass 6-keypad.ch8
• Pass 7-beep.ch8
• Pass 8-scrolling.ch8
• Test with real ROMs / games

Polish

• Configurable CPU speed / cycles per frame
• Configurable color palette
• Window scaling / resize support
• Pause / resume
• Reset / reload ROM
• SUPER-CHIP / CHIP-48 quirks mode (optional)
• XO-CHIP support (optional)