# dgdiniz/bsnes-plus architecture

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

- Interactive diagram: https://gitdiagram.com/dgdiniz/bsnes-plus
- Repository: https://github.com/dgdiniz/bsnes-plus

## Overview

##### Project type and purpose
- bsnes-plus is an open-source SNES emulator fork (C++, Makefiles) with a heavy focus on debugging and extensibility.
- Core emulation (“bsnes/snes”), multiple frontend UIs (Qt-based “bsnes/ui-qt” and a simple launcher), and optional plugin binaries (snesfilter, snesreader, snesmusic, supergameboy).

##### High-level architecture derived from the file tree
- Top-level components:
- Core emulator engine (bsnes/snes)
- Frontend/UI (bsnes/ui-qt + launcher)
- Shared/common libraries (common/nall, common/zlib)
- Co-routine support (bsnes/libco)
- Plugins (snesfilter, snesreader, snesmusic, supergameboy)
- External dependencies (Qt5, SDL, OpenAL, zlib)
- Build system: platform-agnostic Makefiles (mingw, Linux, macOS) and per-component cc.bat/cc.sh scripts.

##### Core interactions and data flows
- UI layer (Qt) ←→ Core emulator API (“libsnes” interface in bsnes/snes/libsnes)
- Launcher / command-line parser initializes emulator, selects profile (accuracy/compatibility/performance), loads cartridges or satellite data.
- Core engine modules: CPU, SMP (audio CPU), PPU (graphics), DSP (audio DSP), scheduler, memory, cartridges, config & serialization.
- libco provides lightweight threading/co-routines used by the scheduler to interleave CPU, SMP, PPU, DSP execution.
- Common library (common/nall) provides platform abstraction (file I/O, threading, endian conversions, data structures) used across core, frontends, and plugins.
- Plugins interfaces: loaded at runtime alongside the core; each exposes a shared-library API to register filters (snesfilter), file extraction (snesreader), music playback (snesmusic), or alternate emulation core (supergameboy).

##### Architectural patterns & design principles
- Layered separation:
1. Platform/utility layer (common/nall, zlib)
2. Emulation core (bsnes/snes, libco)
3. Plugin layer (dynamically loaded .dll/.so/.dylib)
4. Frontend/UI (Qt UI controls, views, debugger panels)
- Modular plugin architecture for extensibility—each plugin resides in its own directory with a Makefile and hooks into a standard plugin loader in the core.
- MVC within the UI: UI-Qt components (views, controllers) call the “libsnes” API (the model) and update widgets (registers view, memory editors, PPU viewers).
- Single responsibility per component: audio, video, input, serialization, config are all distinct modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Platform & Utilities Layer
    subgraph "Platform & Utilities"
        Nall["common/nall"]:::platform
        Zlib["common/zlib"]:::platform,static
    end
    Libco["bsnes/libco"]:::platform,shared

    %% Core Emulator Layer
    subgraph "bsnes Core (Engine)"
        subgraph "Core Modules"
            CPU["CPU Module (bsnes/snes/cpu)"]:::core
            SMP["SMP Module (bsnes/snes/smp)"]:::core
            PPU["PPU Module (bsnes/snes/ppu)"]:::core
            DSP["DSP Module (bsnes/snes/dsp)"]:::core
            Scheduler["Scheduler (bsnes/snes/scheduler)"]:::core
            Memory["Memory Subsystem (bsnes/snes/memory)"]:::core
            Cartridge["Cartridge Handling (bsnes/snes/cartridge)"]:::core
            Config["Config & Serialization (bsnes/snes/config)"]:::core
        end
        Libsnes["libsnes API"]:::core,shared
    end

    %% Frontend Layer
    subgraph "Frontends"
        Launcher["Launcher (bsnes/launcher/launcher.cpp)"]:::ui
        UIQt["Qt Frontend (bsnes/ui-qt)"]:::ui
    end

    %% Plugin Layer
    subgraph "Plugins"
        Filter["snesfilter"]:::plugin
        Reader["snesreader"]:::plugin
        Music["snesmusic"]:::plugin
        SGB["supergameboy"]:::plugin
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Qt5["Qt5"]:::platform
        SDL["SDL/OpenAL"]:::platform
        FS["File System"]:::platform
    end

    %% Interactions
    UIQt -->|"calls API"| Libsnes
    Launcher -->|"initializes core"| Libsnes
    Libsnes -->|"schedules via"| Scheduler
    Scheduler -->|"yields to"| CPU
    Scheduler -->|"yields to"| SMP
    Scheduler -->|"yields to"| PPU
    Scheduler -->|"yields to"| DSP
    CPU -->|"abstraction"| Nall
    SMP -->|"abstraction"| Nall
    PPU -->|"abstraction"| Nall
    DSP -->|"abstraction"| Nall
    Memory -->|"storage via"| Nall
    Cartridge -->|"I/O via"| Nall
    Config -->|"serialize via"| Nall
    Libsnes -->|"plugin loader"| Filter
    Libsnes -->|"plugin loader"| Reader
    Libsnes -->|"plugin loader"| Music
    Libsnes -->|"plugin loader"| SGB
    UIQt -->|"integrates"| Filter
    Libsnes -->|"video/input via"| SDL
    Libsnes -->|"audio via"| SDL
    Libsnes -->|"file system"| FS
    Scheduler -->|"uses co-routines"| Libco

    %% Click Events
    click CPU "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/snes/cpu"
    click SMP "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/snes/smp"
    click PPU "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/snes/ppu"
    click DSP "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/snes/dsp"
    click Scheduler "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/snes/scheduler"
    click Memory "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/snes/memory"
    click Cartridge "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/snes/cartridge"
    click Config "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/snes/config"
    click Libsnes "https://github.com/dgdiniz/bsnes-plus/blob/master/bsnes/snes/libsnes/libsnes.cpp"
    click Libsnes "https://github.com/dgdiniz/bsnes-plus/blob/master/bsnes/snes/libsnes/libsnes.hpp"
    click Launcher "https://github.com/dgdiniz/bsnes-plus/blob/master/bsnes/launcher/launcher.cpp"
    click UIQt "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/ui-qt"
    click Nall "https://github.com/dgdiniz/bsnes-plus/tree/master/common/nall"
    click Zlib "https://github.com/dgdiniz/bsnes-plus/tree/master/common/zlib"
    click Libco "https://github.com/dgdiniz/bsnes-plus/tree/master/bsnes/libco"
    click Filter "https://github.com/dgdiniz/bsnes-plus/tree/master/snesfilter"
    click Reader "https://github.com/dgdiniz/bsnes-plus/tree/master/snesreader"
    click Music "https://github.com/dgdiniz/bsnes-plus/tree/master/snesmusic"
    click SGB "https://github.com/dgdiniz/bsnes-plus/tree/master/supergameboy"

    %% Styles
    classDef platform fill:#eeeeee,stroke:#999;
    classDef core fill:#bbdefb,stroke:#1e88e5;
    classDef ui fill:#c8e6c9,stroke:#388e3c;
    classDef plugin fill:#ffe0b2,stroke:#fb8c00;
    classDef static stroke-dasharray:5 5;
    classDef shared stroke-width:2px,stroke-dasharray: 0,0,0,0,0,0,0,0,0;  
    class Libsnes shared;
```
