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 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 across host applications. This package may depend on pkg/chip8 and pkg/db.

Responsibilities:

  • VM configuration and execution
  • Video and display utilities
  • ROM loading and filesystem helpers

Purpose

This package exists to avoid duplication across cmd/* by centralizing common host-side functionality.

pkg/db/ — Metadata database

Stores metadata about ROMs and platforms used to configure execution and to present information to the user. This package contains no emulator or application logic and is limited to data definition and querying.

Responsibilities:

  • Stores ROM descriptions and metadata
  • Stores platform descriptions and its quirks
  • Stores default configuration per ROM and platform
  • Querying and filtering metadata

cmd/* — Applications

Each subdirectory under cmd/ produces a standalone executable or build target. These packages act as application frontends, wiring together the emulation core, host infrastructure, and metadata database.

Responsibilities:

  • CLI flag parsing and argument handling
  • Loading ROM and platform metadata
  • Sound output, video presentation, and input handling
  • Orchestrating execution flow

Frontends:

  • CLI: Headless or terminal-based execution
  • SDL2: Desktop application with native windowing and input
  • Ebiten: Portable Go-based graphical frontend
  • WASM: Web-based build target (browser / PWA)

Each application reuses shared functionality from pkg/host, pkg/chip8, and pkg/db.

Clone this wiki locally