-
Notifications
You must be signed in to change notification settings - Fork 0
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.
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
This package implements a pure, self-contained CHIP-8 virtual machine. All emulation logic is isolated from application and platform concerns, ensuring that the VM is responsible only for correct and deterministic emulation behavior.
By avoiding any dependency on rendering, audio backends, operating system APIs, or configuration mechanisms, the VM remains portable and reusable across all host environments. This strict separation prevents frontend requirements from influencing emulation correctness and keeps the core easy to reason about.
- Instruction decoding and execution
- Memory and registers
- Timers (delay and sound)
- Display representation
- Sound output generation
- Input state
This design allows the same emulation core to be reused across multiple frontends (WASM, SDL, CLI) while keeping host applications thin and focused on platform-specific responsibilities. The VM remains straightforward to test, deterministic in behavior, and easier to maintain over time.
This package contains reusable, platform-facing code shared across all host applications. It depends on pkg/chip8 (guest VM) and pkg/db, and acts as the integration layer between the pure emulation core and concrete frontends.
- VM configuration and lifecycle management
- Execution control (timing, stepping, pause/resume)
- Video and display utilities
- ROM loading and filesystem helpers
By centralizing common host-side functionality in this package, frontend applications under cmd/* remain thin and focused on platform-specific concerns (UI, input, audio backends). This avoids code duplication, enforces consistent behavior across frontends, and simplifies maintenance.
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.
- ROM metadata (quirks, tick rate, color palette, variant)
- Platform and variant definitions
- Metadata lookup and querying by ROM hash or identifier
By isolating metadata into a dedicated package, configuration decisions are driven by declarative data rather than hardcoded logic. This keeps the emulation core and host code simpler, improves extensibility, and allows new ROMs or variants to be supported without modifying emulator behavior.
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.
- CLI flag parsing and argument handling
- Loading ROM and platform metadata
- Sound output, video presentation, and input handling
- Orchestrating execution flow
- 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.