How frost-phoenix/chip-8 works
Project Type and Purpose
• This is a single-binary emulator/interpreter in C for the Chip-8 virtual machine.
• It supports two “frontends” (CLI or GUI), a core CPU+memory interpreter, basic debugger, timers, input handling, and uses Raylib for graphics in GUI mode.
Main Components
a. Core Emulator Module (“chip8”)
– Implements the Chip-8 fetch-decode-execute cycle
– Houses memory (4KB), registers (V0–VF), index register, PC, stack, timers
b. Common Utilities (“common”)
– Shared data structures, helper functions (e.g., buffer management)
c. Frontends
– CLI Frontend (“cli”): handles terminal I/O, keyboard mapping, ASCII display
– GUI Frontend (“gui”): uses Raylib to render pixel buffer, handle events, scaling, grid overlay
d. Application Launcher (“main”)
– Parses command-line args, selects CLI vs GUI vs Debug mode, sets IPS, loads ROM file
e. External Dependencies
– Raylib (graphics & input)
– GNU Make / Nix build environment
f. Resources
– ROM loader (reads .ch8 files from rom/ directory)
g. Debugger (in core or CLI mode)
Relationships & Data Flow
1. User → main: passes ROM path + options
2. main → common: allocate & initialize Chip-8 state
3. main → rom loader: load binary into memory
4. main → selected frontend (CLI or GUI): enter run loop
5. Frontend → core emulator: each cycle, call chip8_emulate()
6. Core → memory/registers/timers: update state
7. Core → display buffer in common
8. Frontend ← display buffer: render (terminal or Raylib window)
9. Frontend → input subsystem → core (key press/release)
10. Timers (delay & sound) tick at each cycle (part of core loop)
11. Debug mode: CLI monitors opcodes/state for logging or stepping
Architectural Patterns & Principles
• Layered Architecture
– Bottom layer: Chip-8 core (pure logic—no I/O calls)
– Middle layer: Common utilities & data structures
– Top layer: Frontends (CLI/GUI) and CLI-only debugger
• Separation of Concerns
– Core logic is decoupled from I/O (easy to add new frontends)
• Modular C Code
– src/chip8.c, src/common.c, src/cli.c, src/gui.c, src/main.c
– include/ headers define module APIs