# zbkm/chip8-ts architecture

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

- Interactive diagram: https://gitdiagram.com/zbkm/chip8-ts
- Repository: https://github.com/zbkm/chip8-ts

## Overview

This project is a TypeScript implementation of a CHIP-8 interpreter, meaning its main role is to emulate CHIP-8 programs (ROMs) by mimicking the behavior of the original CHIP-8 hardware. It is designed to run in both the browser and console, which implies a clear separation between the emulator core and its presentation layers.

##### Main Components
- Emulator Core: At the heart is the CHIP-8 emulator (src/Emulator.ts), which drives the execution of instructions and manages CPU state, memory (src/Memory.ts), variable registers (src/VariableRegisters.ts), and the stack (src/Stack.ts).
- Instruction Set: The interpreter supports all canonical CHIP-8 instructions. Each instruction resides in its own file under src/Instructions. The main Instruction type and base class (src/Instruction.ts and src/Instructions/BaseInstruction.ts) serve as an entry point, with each concrete instruction (e.g., Jump, DrawSprite, ClearScreen) handling a specific opcode.
- Subsystem: Managed in src/Displays, with implementations such as CanvasDisplay (for browsers), ConsoleDisplay (for CLI), and NoDisplay for scenarios without UI. This component is responsible for rendering the graphics as dictated by the CHIP-8 programs.
- Input (Keypad) Module: Found under src/Keypad, with different implementations such as BrowserKeypad (for web use), ConsoleKeypad (for terminal input), and Mock/NoKeypad options for testing. This handles user keypresses mapped to CHIP-8 input.
- Sound Module: Located under src/Sounds, this component provides sound functionalities. It includes BrowserSound for web-based sound and ConsoleSound for console output, as well as a NoSound implementation when sound is not needed.
- Timers: In src/Timers, managing the Delay and Sound timers which are essential for proper CHIP-8 timing behavior.
- Fonts: Within src/Fonts, handling the default CHIP-8 font used to render sprites corresponding to characters.

##### User Interfaces (Frontend)
- Browser UI: Under app/web, which includes a server (server.ts), build script (build.ts), and web entry point (script.ts and index.html). This layer integrates with the emulator core by setting up a canvas (CanvasDisplay) and handling browser events.
- Console/CLI UI: In app/console.ts, tailored for command-line usage. This interacts with the emulator core via ConsoleDisplay, ConsoleKeypad, and ConsoleSound to facilitate a terminal-based CHIP-8 experience.

##### Establish the Relationships and Data Flows
- The Emulator Core coordinates the fetching and decoding of opcodes using the Instruction classes, updating the system state (memory, registers, stack, timers) accordingly.
- For each instruction execution, it communicates with the Display, Keypad, and Sound components to reflect the changes (for instance, drawing sprites, reading key inputs, or playing sounds).
- The UI components (web and console) serve as the entry point for user interactions (ROM input, key events) and display the output coming from the emulator.
- ROM files (like those in tests/ROM and externally provided ROMs) are read and loaded into memory by the core, initiating the emulation process.

##### Architectural Patterns/Design Principles
- Modular Design: Separate directories for each concern (Emulator logic, Instructions, Displays, Keypad, Sound, Timers) ensure high cohesion within modules and loose coupling between them.
- Pluggable Interfaces: The use of base classes (e.g., BaseDisplay, BaseKeypad, BaseSound) allows different implementations (browser vs. console) to be swapped based on the execution environment.
- Test-Driven: A comprehensive tests directory indicates a focus on unit and integration testing, verifying each component (instructions, displays, etc.) individually.
- Dual Execution Environments: The separation of app/web and app/console components emphasizes a design that cleanly separates UI logic from the emulator core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    ROMInput["ROM Input"]:::external
    EmulatorCore["Emulator Core: Manages execution and CPU state"]:::core
    InstructionSet["Instruction Set: Implements CHIP-8 opcodes"]:::core
    DisplaySubsystem["Display Subsystem: Renders graphics via CanvasDisplay/ConsoleDisplay"]:::display
    InputModule["Input (Keypad) Module: Handles key events via BrowserKeypad/ConsoleKeypad"]:::input
    SoundModule["Sound Module: Provides audio via BrowserSound/ConsoleSound"]:::sound
    Timers["Timers: Delay & Sound timers"]:::timer
    Fonts["Fonts: Default CHIP-8 fonts"]:::fonts
    BrowserUI["Browser UI"]:::ui
    ConsoleUI["Console/CLI UI"]:::ui

    %% Core Data Flow
    ROMInput -->|"loadsROM"| EmulatorCore
    EmulatorCore -->|"fetch_decode"| InstructionSet
    EmulatorCore -->|"updatesDisplay"| DisplaySubsystem
    EmulatorCore -->|"readsInput"| InputModule
    EmulatorCore -->|"triggersSound"| SoundModule
    EmulatorCore -->|"syncsWith"| Timers
    EmulatorCore -->|"rendersFonts"| Fonts

    %% UI Interactions
    BrowserUI -->|"usesCanvasDisplay"| DisplaySubsystem
    BrowserUI -->|"capturesEvents"| InputModule
    BrowserUI -->|"playsAudio"| SoundModule
    ConsoleUI -->|"usesConsoleDisplay"| DisplaySubsystem
    ConsoleUI -->|"readsConsoleInput"| InputModule
    ConsoleUI -->|"playsAudio"| SoundModule

    %% Click Events
    click EmulatorCore "https://github.com/zbkm/chip8-ts/blob/master/src/Emulator.ts"
    click InstructionSet "https://github.com/zbkm/chip8-ts/blob/master/src/Instruction.ts"
    click DisplaySubsystem "https://github.com/zbkm/chip8-ts/tree/master/src/Displays/"
    click InputModule "https://github.com/zbkm/chip8-ts/tree/master/src/Keypad/"
    click SoundModule "https://github.com/zbkm/chip8-ts/tree/master/src/Sounds/"
    click Timers "https://github.com/zbkm/chip8-ts/tree/master/src/Timers/"
    click Fonts "https://github.com/zbkm/chip8-ts/tree/master/src/Fonts/"
    click BrowserUI "https://github.com/zbkm/chip8-ts/tree/master/app/web/"
    click ConsoleUI "https://github.com/zbkm/chip8-ts/blob/master/app/console.ts"

    %% Styles
    classDef external fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef core fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef display fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef input fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef sound fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef timer fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;
    classDef fonts fill:#F9E79F,stroke:#D35400,stroke-width:2px;
    classDef ui fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
```
