Skip to content

Project Structure

Jump to bottom
Maxim Gorin (Troidem) edited this page Dec 16, 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. It is designed to be self-contained and independent of any application or frontend code. This approach keeps the virtual machine focused solely on correct emulation behavior and avoids coupling it to rendering, audio backends, or platform-specific logic.

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

As a result:

  • The core can be reused across multiple frontends (WASM, SDL, CLI).
  • Application code remains free of emulation-specific complexity.
  • The emulator is easier to test, reason about, and maintain.

pkg/host/ — Host Infrastructure

Contains reusable, platform-facing code shared across host applications. This package depend on pkg/chip8 and pkg/db.

Responsibilities

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

This package allows 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.

Related Pages

Clone this wiki locally