Skip to content

Project Structure

Jump to bottom
Maxim Gorin (Troidem) edited this page Dec 15, 2025 · 15 revisions

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 VM

Implements the pure CHIP-8 virtual machine.

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/ (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.

Responsibilities:

  • ROM descriptions
  • Platform descriptions
  • Default configuration per ROM and platform

Characteristics:

  • Data-oriented
  • No emulator logic

cmd/* — Applications

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

Clone this wiki locally