How n1ark/gbc-emulator works
Main Components
• Frontend: Represented by the src/frontend folder. This includes:
• The application’s entry point and React components (GameInput, Screen, Drawer, etc.).
• Helpers such as the AudioPlayer, ConfigContext, and ImageFilter utilities.
• Emulator Core: Found in src/emulator.
• The central emulation system (System.ts) that likely ties together the CPU, Memory, Timer, Interrupts, and I/O.
• CPU (CPU.ts) and peripheral components (Memory, Timer, Interrupts).
• PPU (with submodules like ColorController, VRAMController, OAM) which handle graphics and display.
• APU (with its SoundChannel classes) to emulate audio.
• MBC modules (MBC.ts, MBC1, MBC2, MBC3, MBC5, and NoMBC) and support for game cartridges.
• Testing Assets and ROMs: The public/tests directory contains a rich set of test ROMs categorized by functionality (acid tests, CPU, APU, etc.), which support emulator verification.
• Build & Configuration: The root-level configuration files (package.json, vite.config.ts, tsconfig.json) and index.html instantiate the web app’s environment.
Relationships and Interactions
• Frontend-to-Emulator Integration:
• The frontend collects user inputs (via GameInput, KeybindingInput, etc.) and forwards these to the emulator core.
• It also receives output data (video, audio) generated by the emulator.
• Emulator Core Interactions:
• The System.ts module acts as the conductor, coordinating between the CPU, PPU, APU, and other components like Memory.
• The CPU drives the instruction cycles and uses the MBC implementations to handle different cartridge memory schemes.
• The PPU and its controllers (VRAMController, ColorController, OAM) collaborate to render video output.
• The APU (with distinct sound channels) manages audio processing.
• Testing & Validation:
• The public/tests directory serves as a collection of ROM-based test cases that trigger specific paths within the emulator (e.g., testing CPU instructions, interrupt timings, DMA routines, etc.).
Architectural Patterns and Design Principles
• Modularity and Separation of Concerns:
• The clear separation between emulator subsystems (CPU, PPU, APU, memory management) aids in isolated development and testing.
• The frontend, as a distinct layer, communicates with the emulator core via defined interfaces or callbacks.
• Layered Architecture:
• With the hardware emulation logic in a “backend-like” layer (even though it runs in the browser) and UI components in the frontend, the system adheres to design principles similar to MVC or MVVM.
• Use of Typescript and React:
• Type safety across modules supports clear contracts between components.
• React-based state management in the frontend ensures that user interactions are handled efficiently.
Relevant Technologies, Frameworks, and Libraries
• TypeScript for type safety across emulator and frontend modules.
• React (TSX) for the user interface.
• Vite as the build tool enabling fast development cycles.