# berkio3x/pychip8 architecture

> Architecture diagram of the GitHub repository berkio3x/pychip8, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/berkio3x/pychip8
- Repository: https://github.com/berkio3x/pychip8

## Overview

##### Project Type and Purpose
- This is a Python-based CHIP-8 emulator (“pyChip8”). Its goal is to load CHIP-8 ROMs (e.g., pong.rom, ibmlogo.ch8), emulate the CHIP-8 virtual CPU, memory, timers, input and graphics, and render the output (and play sound) on the host machine.

##### File-Structure Analysis
- Top-level files:
- main.py       – entry point: initializes emulator, loads ROM, runs fetch-decode-execute loop
- font.py       – defines the built-in CHIP-8 font sprite data
- timers.py     – implements delay and sound timers (60 Hz tick)
- *.rom files   – CHIP-8 programs to be loaded
- env/ and __pycache__/ are support folders for Python virtual environment and caching. They’re not part of emulator logic.

##### Core Components
a. CPU Core
– Fetch-Decode-Execute Loop (in main.py)
– Opcode decoder and dispatcher
– 16 general-purpose V-registers, I register, program counter, stack pointer
b. Memory
– 4 KB RAM (addresses 0x000–0xFFF)
– Font data loaded at 0x050–0x0A0 (via font.py)
– ROM loaded starting at 0x200
c. Timers
– Delay timer and sound timer (timers.py), tick at 60 Hz
d. / Graphics
– 64×32 monochrome screen buffer in memory
– Draws via XOR, sets VF register on collision
e. Input
– Hex-key keypad (0x0–0xF) mapped to host keyboard
f. Sound
– Generates a beep when sound timer > 0
g. ROM Loader
– Reads .rom file bytes into memory space

##### Interactions and Data Flow
- main.py initializes all modules, loads ROM
- In each cycle:
1. CPU fetches 2-byte opcode from Memory at PC
2. Opcode is decoded and executed:
- May read/write registers, memory, PC, stack
- May modify display buffer, set timers, poll input
3. After executing one or more instructions, Timers are decremented (timers.py)
4. Is refreshed (host window update)
5. Sound subsystem checks sound timer to emit beep
- Input handling is polled/interrupt-style each loop

##### Architectural Patterns and Principles
- Monolithic emulator core, but cleanly separated into modules:
- main.py orchestrator (composition over inheritance)
- font.py pure data provider
- timers.py single-responsibility timers
- Separation of concerns:
- CPU logic vs. display logic vs. input vs. timers
- Data-driven design:
- Memory holds both ROM and runtime state (stack, registers, display)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Engine
    subgraph "Core Engine"
        CPU["CPU Core\n(Fetch-Decode-Execute Loop,\nOpcode Decoder,\nRegisters, Stack)"]:::core
        ROMLOADER["ROM Loader\n(Read .rom/.ch8)"]:::core
    end

    %% Data Stores
    MEM["Memory\n(4KB RAM,\nROM @0x200)"]:::data
    FONT["Font Data\n(0x050–0x0A0)"]:::data

    %% Peripherals
    TIMERS["Timers\n(Delay & Sound,\n60Hz tick)"]:::peripheral
    DISPLAY["Display\n(64×32 Buffer,\nDraw XOR)"]:::peripheral
    INPUT["Input\n(Hex-key Keypad,\nPolling)"]:::peripheral
    SOUND["Sound\n(Beep when timer>0)"]:::peripheral

    %% External
    ROM["Example ROMs\n(pong.rom, ibmlogo.ch8)"]:::external

    %% Connections
    ROM -->|"loaded by"| ROMLOADER
    ROMLOADER -->|"load"| MEM
    FONT -->|"font data"| MEM
    CPU -->|"fetch/read/write"| MEM
    CPU -->|"draw"| DISPLAY
    CPU -->|"set timers"| TIMERS
    TIMERS -->|"decrement (60Hz)"| CPU
    TIMERS -->|"emit beep trigger"| SOUND
    INPUT -->|"key press"| CPU
    CPU -->|"poll input"| INPUT

    %% Click Events
    click CPU "https://github.com/berkio3x/pychip8/blob/main/main.py"
    click ROMLOADER "https://github.com/berkio3x/pychip8/blob/main/main.py"
    click MEM "https://github.com/berkio3x/pychip8/blob/main/main.py"
    click FONT "https://github.com/berkio3x/pychip8/blob/main/font.py"
    click TIMERS "https://github.com/berkio3x/pychip8/blob/main/timers.py"
    click DISPLAY "https://github.com/berkio3x/pychip8/blob/main/main.py"
    click INPUT "https://github.com/berkio3x/pychip8/blob/main/main.py"
    click SOUND "https://github.com/berkio3x/pychip8/blob/main/main.py"
    click ROM "https://github.com/berkio3x/pychip8/blob/main/pong.rom"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9,stroke-width:2px
    classDef data fill:#D5F5E3,stroke:#27AE60,stroke-width:2px
    classDef peripheral fill:#FADBD8,stroke:#C0392B,stroke-width:2px
    classDef external fill:#F5CBA7,stroke:#B9770E,stroke-width:2px
```
