Project Structure

This page documents the structure of the project and the responsibilities of each package. The layout is designed to separate emulation logic, reusable host code, and application entry points.

Architectural Model

The project follows a Guest / Host / App model:

• Guest: The system being recreated
• Host: The actual system that runs the emulator program
• App: Thin composition layer that binds guest and host together

Packages

pkg/chip8/ (Guest) — CHIP-8 virtual machine

Implements the pure CHIP-8 VM, encapsulating all core components: CPU, memory, timers, display, sound, and input state.

Responsibilities:

• Instruction decoding and execution
• Memory and registers
• Timers (delay and sound)
• Display representation
• Sound output generation
• Input state

Does not depend on:

• OS APIs
• Rendering, audio, or filesystem
• CLI or configuration parsing

pkg/host/ (Host) — Host Infrastructure

Contains reusable, platform-facing code shared host applications, depends on pkg/chip8 and pkg/db.

Responsibilities:

• VM configuration and execution timing
• Video rendering utilities
• ROM and Filesystem helpers

This package allows to avoid duplication across cmd/*.

pkg/db/ — Metadata database

Stores information about ROMs and platforms used to configure execution. Contains no emulator or app logic. Provides utilities to querying data.

Responsibilities:

• Stores ROM descriptions
• Stores Platform descriptions
• Stores default configuration per ROM and platform

cmd/* — Applications

Each subdirectory under cmd/ produces a standalone executable. No emulation logic. Minimal logic beyond orchestration. This keeps executables thin and predictable.