How sacckey/rubyboy works
Main Components
• Emulator Core – This is the central engine that ties all subcomponents together (found in lib/rubyboy/emulator.rb, emulator_headless.rb, and emulator_wasm.rb).
• CPU & Registers – Represented by lib/rubyboy/cpu.rb and lib/rubyboy/registers.rb, this module emulates the processor’s behavior, fetching and executing instructions.
• Memory & Bus – The bus (lib/rubyboy/bus.rb) connects the CPU with RAM (lib/rubyboy/ram.rb), cartridge memory (lib/rubyboy/cartridge directory), and I/O components.
• Cartridge & ROM Management – With components under lib/rubyboy/cartridge and lib/roms, including a factory pattern (lib/rubyboy/cartridge/factory.rb) to load ROM files.
• Graphics (PPU & LCD) – Handled by lib/rubyboy/ppu.rb and lib/rubyboy/lcd.rb, possibly with additional abstraction for SDL (lib/rubyboy/sdl.rb) or via raylib (lib/rubyboy/raylib).
• Audio (APU & Channels) – Emulated by lib/rubyboy/apu.rb along with its channel submodules (e.g., channel1.rb – channel4.rb).
• Timer & Interrupts – Managed by lib/rubyboy/timer.rb and lib/rubyboy/interrupt.rb, ensuring correct timing of operations and event handling.
• Input Handling – Through lib/rubyboy/joypad.rb to map keyboard input (as described in the README) to emulator controls.
Diagramming the Relationships and Interactions
• The CPU, which in turn connects to the Bus.
• The Bus that facilitates communication with Memory (RAM) and Cartridge (ROM) components.
• The Timer/Interrupt system that interacts with the CPU to manage synchronization.
• Separate branches from the core indicate I/O:
• One branch leads to the Graphics subsystem (PPU, LCD) which may utilize external libraries (SDL2 and/or raylib).
• Another branch routes to the Audio subsystem (APU and associated channels).
• Input subsystem (Joypad) that feeds into the core for user commands.
• Cartridge & ROM loader as the entry point for loading game data. Show how the ROM is parsed and its data injected into the Memory subsystem via the Bus.
Architectural Patterns and Design Principles
• Modularity: Each hardware component (e.g., CPU, GPU, APU) is encapsulated in its own module, allowing easier maintenance and potential reuse.
• Clear Data/Control Flow: The CPU fetches instructions from memory (often involving Cartridge ROMe) and coordinates with peripherals (Graphics, Audio, Input).
• Use of Factory Pattern: For cartridge management (the Cartridge Factory module), indicating a layer of abstraction when loading different ROMs.
• Separation of Concerns especially shown by having distinct implementations for headless running, WebAssembly, and standard execution modes.
Final Recommendations
• Every component and interaction is clearly labeled.