How scoldev/canes works
Main Components
• Emulator Core (nes/core)
• CPU: Located under src/nes/core/cpu, including constants (clock, flags, registers, state), the CPU implementation, and integration with instructions.
• ALU: Under src/nes/core/alu, handling arithmetic and logic operations.
• Memory: Under src/nes/core/memory, with related constants defining the memory map and mirrors.
• Addressing Modes: Found in nes/core/addressing-modes, which plays a key role in CPU instruction decoding.
• Instructions: The instructions implementation is separated further into a table of instructions (each instruction in its own file) and related error handling.
• Debugger and Disassembler
• Debugger: Both in the emulator’s core (src/nes/debugger) and on the UI side (src/ui/debugger) with context providers, hooks, and adapters. This indicates a separation of concerns between the debugging logic and its presentation.
• Disassembler: Implemented in both core (src/nes/disasm) and app-level folders (src/app/disasm), handling the parsing and conversion of binary opcodes into human-readable assembly code.
• UI Layer
• The interface is implemented using components (src/ui/debugger/components, src/ui/main.tsx, etc.). This layer includes debugger windows, layout components, and adapters (such as the ROM file loader).
• ROM and Services
• ROM Loader: Located in the nes/rom directory (and its constants, types, and service in nes/services).
• Services: nes-service and rom-service to serve as higher-level abstractions for interactions between ROM data and emulator state.
• Additional Supporting Components
• Benchmark: Contains specific scripts (in benchmark/) that test and measure instruction implementation performance.
• Testing: There is a comprehensive tests directory, including unit, integration, and UI tests that support TDD.
• Configuration/Build: Files such as package.json, tsconfig.json, vite.config.js, and linting/commit hooks are part of the project’s infrastructure.
Relationships and Interactions
• The Emulator Core interacts internally via data flow from:
• Memory ↔ CPU (ALU, addressing, and instructions).
• The CPU uses instructions, and these interact with the addressing modes and memory.
• The Debugger/Disassembler components sit on top of the Core:
• They request state and disassembled code from the emulator’s core.
• Errors generated by core components (like unknown instructions or missing ROM) are handled and surfaced.
• User Interface Components:
• The UI layer (written in React) communicates with the core debugger via hooks, adapters, and context providers, creating an interactive debugging experience.
• The UI sends commands (via defined debugger commands and state) back to the core to control emulation.
• ROM Loading and Service Modules:
• The ROM Service loads, validates, and prepares ROM files.
• This service interacts with the emulator core and also the debugger/adapters in the UI.
Architectural Patterns and Design Principles
• Layered Architecture – Separation among core emulation (business logic), debugging/disassembly (auxiliary services), and UI (presentation layer).
• Modularization – Each major function (CPU, ALU, memory, instructions, etc.) is broken into multiple files for maintainability.
• Use of TDD – As suggested by the extensive tests and integration directories, the system’s design has been influenced by TDD principles to reduce bugs.
• Dependency Direction – The core components (emulator, modules) should be independent, while UI and debugging modules act as layers that communicate with these core services.