How zbkm/chip8-ts works
This project is a TypeScript implementation of a CHIP-8 interpreter, meaning its main role is to emulate CHIP-8 programs (ROMs) by mimicking the behavior of the original CHIP-8 hardware. It is designed to run in both the browser and console, which implies a clear separation between the emulator core and its presentation layers.
Main Components
• Emulator Core: At the heart is the CHIP-8 emulator (src/Emulator.ts), which drives the execution of instructions and manages CPU state, memory (src/Memory.ts), variable registers (src/VariableRegisters.ts), and the stack (src/Stack.ts).
• Instruction Set: The interpreter supports all canonical CHIP-8 instructions. Each instruction resides in its own file under src/Instructions. The main Instruction type and base class (src/Instruction.ts and src/Instructions/BaseInstruction.ts) serve as an entry point, with each concrete instruction (e.g., Jump, DrawSprite, ClearScreen) handling a specific opcode.
• Subsystem: Managed in src/Displays, with implementations such as CanvasDisplay (for browsers), ConsoleDisplay (for CLI), and NoDisplay for scenarios without UI. This component is responsible for rendering the graphics as dictated by the CHIP-8 programs.
• Input (Keypad) Module: Found under src/Keypad, with different implementations such as BrowserKeypad (for web use), ConsoleKeypad (for terminal input), and Mock/NoKeypad options for testing. This handles user keypresses mapped to CHIP-8 input.
• Sound Module: Located under src/Sounds, this component provides sound functionalities. It includes BrowserSound for web-based sound and ConsoleSound for console output, as well as a NoSound implementation when sound is not needed.
• Timers: In src/Timers, managing the Delay and Sound timers which are essential for proper CHIP-8 timing behavior.
• Fonts: Within src/Fonts, handling the default CHIP-8 font used to render sprites corresponding to characters.
User Interfaces (Frontend)
• Browser UI: Under app/web, which includes a server (server.ts), build script (build.ts), and web entry point (script.ts and index.html). This layer integrates with the emulator core by setting up a canvas (CanvasDisplay) and handling browser events.
• Console/CLI UI: In app/console.ts, tailored for command-line usage. This interacts with the emulator core via ConsoleDisplay, ConsoleKeypad, and ConsoleSound to facilitate a terminal-based CHIP-8 experience.
Establish the Relationships and Data Flows
• The Emulator Core coordinates the fetching and decoding of opcodes using the Instruction classes, updating the system state (memory, registers, stack, timers) accordingly.
• For each instruction execution, it communicates with the Display, Keypad, and Sound components to reflect the changes (for instance, drawing sprites, reading key inputs, or playing sounds).
• The UI components (web and console) serve as the entry point for user interactions (ROM input, key events) and display the output coming from the emulator.
• ROM files (like those in tests/ROM and externally provided ROMs) are read and loaded into memory by the core, initiating the emulation process.
Architectural Patterns/Design Principles
• Modular Design: Separate directories for each concern (Emulator logic, Instructions, Displays, Keypad, Sound, Timers) ensure high cohesion within modules and loose coupling between them.
• Pluggable Interfaces: The use of base classes (e.g., BaseDisplay, BaseKeypad, BaseSound) allows different implementations (browser vs. console) to be swapped based on the execution environment.
• Test-Driven: A comprehensive tests directory indicates a focus on unit and integration testing, verifying each component (instructions, displays, etc.) individually.
• Dual Execution Environments: The separation of app/web and app/console components emphasizes a design that cleanly separates UI logic from the emulator core.