How smparsons/retroboy works
Main Components
• Emulator Core (Rust):
• Contains modules for CPU (with opcodes, ALU, bit operations, interrupts, timers, etc. in src/cpu).
• APU for sound synthesis and envelope management (found in src/apu).
• GPU for graphics and scanline rendering (found in src/gpu).
• MMU for memory management, cartridge emulation (src/mmu with bank switching, MBC support, etc.).
• Other components such as DMA, serial, RTC/cheats, and miscellaneous utilities.
• WASM Interface:
• Located in src/wasm; responsible for providing JavaScript bindings for the emulator core. This is built using wasm-pack via build-wasm.sh.
• Web Frontend:
• A React/TypeScript application (frontends/web) that loads the generated WASM module.
• Contains UI components (menus, game screens, modals, form elements) and hooks for managing audio, key listeners, responsiveness, and settings.
• Utilizes the Web Audio API, HTML Canvas for graphics rendering, and saves cartridge data to browser local storage.
• Test Runner:
• A JSON-based test runner (frontends/json_test_runner) provides a mechanism to run and verify CPU emulation using established JSON test suites.
Relationships and Data Flow
• The Web Frontend interacts with the WASM module:
• When a user loads a ROM or starts the emulator, the React app calls the WASM API functions, which in turn invoke the corresponding routines in the emulator core.
• Data flows from the emulator core (e.g., GPU scanline rendering, audio samples from APU) to the Web Frontend where it is rendered or played.
• The WASM layer serves as the bridge between JavaScript/TypeScript and the native Rust emulator core.
• The JSON test runner component interacts directly with the emulator core (or a simplified version thereof) to run automated tests for accuracy.
• Internally, modules in the Emulator Core communicate through function calls and shared memory access (e.g., the CPU’s instructions triggering GPU updates or memory transfers via DMA).
Architectural Patterns & Technologies
• Modularity and Separation of Concerns:
• Clear separation between emulation logic (Rust modules) and presentation (React frontend).
• The WASM layer encapsulates the native logic and exposes only necessary interfaces to the web.
• Layered Architecture:
• Divide the system into three layers: the core emulation backend (Rust code), the integration layer (WASM bindings), and the web presentation layer.
• Use of Test-Driven Development:
• A heavy emphasis on testing with dedicated JSON CPU tests and a comprehensive test suite (invoked via cargo test).