# emh-spec/chip-8 architecture

> Architecture diagram of the GitHub repository emh-spec/chip-8, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/emh-spec/chip-8
- Repository: https://github.com/emh-spec/chip-8

## Overview

This is a no_std CHIP-8 emulator library. A host calls `run` with a mutable emulator and platform implementation; the loop polls keys, advances CPU instructions and timers, updates sound and display, and paces frames until the emulated program quits. The core owns opcode execution and emulated state, using the display renderer and RNG internally. The excerpts show this main workflow, but the README is empty and no additional product capabilities are documented.

Main entry points: [`src/lib.rs`](https://github.com/emh-spec/chip-8/blob/main/src/lib.rs) (Frame loop), [`src/chip8/core.rs`](https://github.com/emh-spec/chip-8/blob/main/src/chip8/core.rs) (Opcode engine), [`src/chip8/platform.rs`](https://github.com/emh-spec/chip-8/blob/main/src/chip8/platform.rs) (Platform API), [`src/chip8/display.rs`](https://github.com/emh-spec/chip-8/blob/main/src/chip8/display.rs) (Display renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Emulation runtime"]
  node_run_loop["Frame loop<br/>[lib.rs]"]
end

subgraph group_machine["Virtual machine"]
  node_chip8["CHIP-8 core<br/>[core.rs]"]
  node_opcode_engine["Opcode engine<br/>[core.rs]"]
  node_display["Display renderer<br/>[display.rs]"]
  node_rng["Xorshift RNG<br/>[xorshift32.rs]"]
end

subgraph group_host["Host interface"]
  node_platform_api["Platform API<br/>[platform.rs]"]
  node_key_events["Key events<br/>[platform.rs]"]
end

node_host_app(("Host application"))

node_host_app -->|"calls"| node_run_loop
node_run_loop -->|"uses"| node_platform_api
node_run_loop -->|"polls"| node_key_events
node_run_loop -->|"ticks"| node_chip8
node_run_loop -->|"reads state"| node_chip8
node_chip8 -->|"executes"| node_opcode_engine
node_opcode_engine -->|"draws sprites"| node_display
node_opcode_engine -->|"generates values"| node_rng
node_run_loop -->|"draws and beeps"| node_platform_api

click node_run_loop "https://github.com/emh-spec/chip-8/blob/main/src/lib.rs"
click node_platform_api "https://github.com/emh-spec/chip-8/blob/main/src/chip8/platform.rs"
click node_key_events "https://github.com/emh-spec/chip-8/blob/main/src/chip8/platform.rs"
click node_chip8 "https://github.com/emh-spec/chip-8/blob/main/src/chip8/core.rs"
click node_opcode_engine "https://github.com/emh-spec/chip-8/blob/main/src/chip8/core.rs"
click node_display "https://github.com/emh-spec/chip-8/blob/main/src/chip8/display.rs"
click node_rng "https://github.com/emh-spec/chip-8/blob/main/src/chip8/xorshift32.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_run_loop toneBlue
class node_chip8,node_opcode_engine,node_display,node_rng toneAmber
class node_platform_api,node_key_events toneMint
class node_host_app toneIndigo
```

## Components

### Emulation runtime

- [Frame loop](https://github.com/emh-spec/chip-8/blob/main/src/lib.rs): `src/lib.rs`

### Virtual machine

- [CHIP-8 core](https://github.com/emh-spec/chip-8/blob/main/src/chip8/core.rs): `src/chip8/core.rs`
- [Opcode engine](https://github.com/emh-spec/chip-8/blob/main/src/chip8/core.rs): `src/chip8/core.rs`
- [Display renderer](https://github.com/emh-spec/chip-8/blob/main/src/chip8/display.rs): `src/chip8/display.rs`
- [Xorshift RNG](https://github.com/emh-spec/chip-8/blob/main/src/chip8/xorshift32.rs): `src/chip8/xorshift32.rs`

### Host interface

- [Platform API](https://github.com/emh-spec/chip-8/blob/main/src/chip8/platform.rs): `src/chip8/platform.rs`
- [Key events](https://github.com/emh-spec/chip-8/blob/main/src/chip8/platform.rs): `src/chip8/platform.rs`

### Other components

- **Host application**

## Connections

- Host application → Frame loop: calls (evidence: `src/lib.rs`)
- Frame loop → Platform API: uses (evidence: `src/lib.rs`)
- Frame loop → Key events: polls (evidence: `src/lib.rs`)
- Frame loop → CHIP-8 core: ticks (evidence: `src/lib.rs`)
- Frame loop → CHIP-8 core: reads state (evidence: `src/lib.rs`)
- CHIP-8 core → Opcode engine: executes (evidence: `src/chip8/core.rs`)
- Opcode engine → Display renderer: draws sprites (evidence: `src/chip8/core.rs`)
- Opcode engine → Xorshift RNG: generates values (evidence: `src/chip8/core.rs`)
- Frame loop → Platform API: draws and beeps (evidence: `src/lib.rs`)
