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 (pkg/chip8) Pure virtual machine implementation

Host (pkg/host) Reusable platform-facing code shared by multiple executables

App (cmd/*) Thin composition layer that binds guest and host together

Metadata (pkg/db) Information about ROMs and platforms used for configuration

pkg/chip8/ — CHIP-8 Virtual machine Core (Guest)

Responsibilities: Instruction decoding and execution Memory and registers Timers Display representation Sound producer Input state

Does not depend on: OS APIs Rendering, audio, or filesystem CLI or configuration parsing

pkg/host/ — 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 exists to avoid duplication across cmd/*.

cmd/ — Applications

Each subdirectory under cmd/ produces a standalone executable. No emulation logic. Minimal logic beyond orchestration.

This keeps executables thin and predictable.

pkg/db/ — Metadata and Configuration

Stores metadata used to configure execution.

Responsibilities: ROM descriptions Platform descriptions Default cogfiguration per ROM and platform

Characteristics: Data-oriented No emulator logic