# baekalfen/pyboy architecture

> Architecture diagram of the GitHub repository baekalfen/pyboy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baekalfen/pyboy
- Repository: https://github.com/baekalfen/pyboy

## Overview

##### Main Components
- Emulation Engine (Core):
– This includes the “pyboy/core” package with modules for CPU emulation (cpu.py), memory (ram.py, mb.py), timer (timer.py), LCD processing (lcd.py), and sound (sound.py).
– The cartridge subsystem (under “pyboy/core/cartridge”) handles different Memory Bank Controllers (MBC1, MBC2, etc.) and bootrom initialization.
- API Layer:
– Found under “pyboy/api”, this layer exposes functionality (e.g., gameshark, memory scanners, screen, sound) to external scripts.
– It’s responsible for bridging the lower-level core emulation with user commands, such as setting emulation speed, capturing screenshots, or processing input.
- Plugin Framework:
– The “pyboy/plugins” directory shows multiple plugins already implemented (e.g., for auto pause, debugging, game wrappers, rewind, screen and screenshot recorders).
– This should be shown as an extensibility point where external modules can hook into or modify the emulation process.
- Entry Point/Facade:
– The “pyboy/pyboy.py” and “pyboy/__main__.py” serve as the primary entry points for command-line and script-based launches.
– They initialize the PyBoy instance, load a ROM, and enter the emulation loop (via “tick” iterations).
- External Components:
– ROM Files and Boot ROMs (found in “extras” and the root of “pyboy”) which feed into the cartridge/bootrom subsystem.
– Testing and Documentation artifacts (under “tests” and “docs”) that are not part of the runtime, but indicate how the system is used and validated.
– Configuration/build tooling like setup.py, Makefile, and CI workflows (in “.github”) to support development and deployment.

##### Relationships & Data Flow
- The high-level flow begins with the PyBoy entry point (e.g., command-line input), which instantiates the emulator.
- The emulator initializes the Core Engine components – the CPU, RAM, timers, and registers are set up as part of bootrom initialization (with ROM data loaded from the cartridge system).
- The main loop calls “tick()”, advancing the emulation. Each tick advances the CPU, updates memory, refreshes the LCD output, processes sound channels, and triggers timer events.
- The API layer is used either by internal components (e.g., plugins) or by user code invoking commands like “pyboy.button(‘a’)” to push inputs.
- Plugins register through the “pyboy/plugins/manager” to intercept or extend functionality. For example, a “rewind” plugin may capture emulator states, or a “screen_recorder” plugin grabs image buffers.
- Performance controls such as frame skipping are handled by parameters in the “tick” method, allowing users to bypass rendering when not needed, which is explained in the README.

##### Architectural Patterns/Design Principles
- Modular Design: The separation into “core”, “api”, and “plugins” underscores a modular architecture where each functional aspect is isolated.
- Plugin/Extension Pattern: The integration of plugins shows an extensible design. Represent this as a plug-in module that interacts with the core loop.
- Facade Pattern: The PyBoy class (and its command-line entry points) provides a simplified interface for interacting with the complex underlying emulation system.
- Test-Driven/CI-Compatible: Extensive “tests” directories and `.github` workflows point to a design that encourages robust testing and continuous integration.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Entry Point/Facade
    subgraph "Entry Point/Facade"
        EP1["PyBoy Class"]:::facade
        EP2["Main Entry"]:::facade
    end

    %% Core Emulation Engine
    subgraph "Core Emulation Engine"
        CE1["CPU Emulation"]:::core
        CE2["RAM"]:::core
        CE3["Memory Bank"]:::core
        CE4["Timer Module"]:::core
        CE5["LCD Processing"]:::core
        CE6["Sound Emulation"]:::core
        subgraph "Cartridge Subsystem"
            CB1["Cartridge Loader"]:::core
            CB2["MBC1"]:::core
            CB3["MBC2"]:::core
            CB4["MBC3"]:::core
            CB5["MBC5"]:::core
            CB6["RTC"]:::core
            CB7["Bootrom Support"]:::core
        end
    end

    %% API Layer
    subgraph "API Layer"
        API1["API Interfaces"]:::api
        API2["Gameshark"]:::api
        API3["Screen"]:::api
        API4["Sound API"]:::api
        API5["Sprite"]:::api
        API6["Tile"]:::api
        API7["Tilemap"]:::api
        API8["Memory Scanner"]:::api
    end

    %% Plugin Framework
    subgraph "Plugin Framework"
        PF1["Plugin Manager"]:::plugin
        PF2["Auto Pause Plugin"]:::plugin
        PF3["Debug Plugin"]:::plugin
        PF4["Game Wrapper Plugin"]:::plugin
        PF5["Rewind Plugin"]:::plugin
        PF6["Screen Recorder Plugin"]:::plugin
        PF7["Screenshot Recorder Plugin"]:::plugin
        PF8["Window OpenGL Plugin"]:::plugin
        PF9["Window SDL2 Plugin"]:::plugin
    end

    %% External Components
    subgraph "External Components"
        EX1["Boot ROM Files"]:::external
        EX2["Default ROM (GameBoy)"]:::external
        EX3["Default ROM (CGB)"]:::external
    end

    %% Development/Testing and Build
    subgraph "Development/Testing"
        DT1["Tests"]:::dev
        DT2["CI & Build Tooling"]:::dev
    end

    %% Relationships
    EP2 -->|"instantiates"| EP1

    EP1 -->|"init"| CE1
    EP1 -->|"init"| CE2
    EP1 -->|"init"| CE3
    EP1 -->|"init"| CE4
    EP1 -->|"init"| CE5
    EP1 -->|"init"| CE6
    EP1 -->|"init"| CB1

    EX2 -->|"ROM"| CB1
    EX3 -->|"ROM"| CB1
    EX1 -->|"bootrom"| CB7

    EP1 -->|"tick()"| CE1
    EP1 -->|"hook"| PF1
    EP1 -->|"exposes"| API1
    PF1 -->|"hooks"| CE1

    %% Styles
    classDef facade fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#f96,stroke:#333,stroke-width:2px;
    classDef api fill:#9cf,stroke:#333,stroke-width:2px;
    classDef plugin fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fc9,stroke:#333,stroke-width:2px;
    classDef dev fill:#ccc,stroke:#333,stroke-width:2px;

    %% Click Events
    click EP1 "https://github.com/baekalfen/pyboy/blob/master/pyboy/pyboy.py"
    click EP2 "https://github.com/baekalfen/pyboy/blob/master/pyboy/__main__.py"
    click CE1 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/cpu.py"
    click CE2 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/ram.py"
    click CE3 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/mb.py"
    click CE4 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/timer.py"
    click CE5 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/lcd.py"
    click CE6 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/sound.py"
    click CB1 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/cartridge/cartridge.py"
    click CB2 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/cartridge/mbc1.py"
    click CB3 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/cartridge/mbc2.py"
    click CB4 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/cartridge/mbc3.py"
    click CB5 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/cartridge/mbc5.py"
    click CB6 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/cartridge/rtc.py"
    click CB7 "https://github.com/baekalfen/pyboy/blob/master/pyboy/core/bootrom.py"
    click API1 "https://github.com/baekalfen/pyboy/tree/master/pyboy/api"
    click API2 "https://github.com/baekalfen/pyboy/blob/master/pyboy/api/gameshark.py"
    click API3 "https://github.com/baekalfen/pyboy/blob/master/pyboy/api/screen.py"
    click API4 "https://github.com/baekalfen/pyboy/blob/master/pyboy/api/sound.py"
    click API5 "https://github.com/baekalfen/pyboy/blob/master/pyboy/api/sprite.py"
    click API6 "https://github.com/baekalfen/pyboy/blob/master/pyboy/api/tile.py"
    click API7 "https://github.com/baekalfen/pyboy/blob/master/pyboy/api/tilemap.py"
    click API8 "https://github.com/baekalfen/pyboy/blob/master/pyboy/api/memory_scanner.py"
    click PF1 "https://github.com/baekalfen/pyboy/blob/master/pyboy/plugins/manager.py"
    click PF2 "https://github.com/baekalfen/pyboy/blob/master/pyboy/plugins/auto_pause.py"
    click PF3 "https://github.com/baekalfen/pyboy/blob/master/pyboy/plugins/debug.py"
    click PF4 "https://github.com/baekalfen/pyboy/tree/master/pyboy/plugins/game_wrapper_*"
    click PF5 "https://github.com/baekalfen/pyboy/blob/master/pyboy/plugins/rewind.py"
    click PF6 "https://github.com/baekalfen/pyboy/blob/master/pyboy/plugins/screen_recorder.py"
    click PF7 "https://github.com/baekalfen/pyboy/blob/master/pyboy/plugins/screenshot_recorder.py"
    click PF8 "https://github.com/baekalfen/pyboy/blob/master/pyboy/plugins/window_open_gl.py"
    click PF9 "https://github.com/baekalfen/pyboy/blob/master/pyboy/plugins/window_sdl2.py"
    click EX1 "https://github.com/baekalfen/pyboy/tree/master/extras/bootrom"
    click EX2 "https://github.com/baekalfen/pyboy/blob/master/pyboy/default_rom.gb"
    click EX3 "https://github.com/baekalfen/pyboy/blob/master/pyboy/default_rom_cgb.gb"
    click DT1 "https://github.com/baekalfen/pyboy/tree/master/tests"
    click DT2 "https://github.com/baekalfen/pyboy/blob/master/.github"
```
