# mgba-emu/mgba architecture

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

- Interactive diagram: https://gitdiagram.com/mgba-emu/mgba
- Repository: https://github.com/mgba-emu/mgba

## Overview

##### Project type and purpose
- It provides multiple front‑ends (Qt GUI, SDL, CLI), feature modules (recording, scripting, debugging), a core emulation engine, and platform abstraction layers.

##### File structure to extract architectural layers
- Front‑end layer:
– src/platform/qt … (Qt GUI)
– src/platform/sdl … (SDL frontend)
– src/platform/python … (Python bindings)
– src/platform/example, src/platform/headless… (CLI/test executables)
- Feature layer:
– src/feature/* (command‑line parser, GUI runner, video‑backend, FFmpeg recorder, cheat management, scripting proxy, updater)
- Core emulation layer:
– src/arm, src/sm83 (CPU decoders/emitters: ARM7TDMI, SM83)
– src/gb, src/gba (system cores: memory, I/O, PPU, APU, DMA, timers, BIOS emulation)
– src/core (common subsystems: configuration, threading, lockstep, tile/memory caches, sync, rewind, scripting host)
– src/debugger (CLI debugger, GDB stub)
- Scripting layer:
– src/script (embedded Lua engine, scripting API: canvas, input, storage, console)
- Platform abstraction layer:
– src/platform/posix, windows, 3ds, switch, wii, psp2, libretro, opengl (file I/O/VFS, threading, graphics, audio, input drivers)
- Third‑party libraries:
– include/mgba‑util, src/third‑party/* (zlib, libpng, SQLite3, FFmpeg, rapidjson, ini parser, LZMA, Discord RPC)
- Test/ROM suites:
– cinema/… (automated compliance tests)
– src/*/test (unit tests for core, GB, GBA, util, debugger)
- Build system:
– CMakeLists.txt, CMakePresets.json, version.cmake

##### README for technical stack and interactions
- Core C/C++ emulator built with CMake.
- Optional features toggled by presence of Qt, SDL2, FFmpeg, libpng, zlib, SQLite3, Lua, libelf, json‑c.
- Docker, MSYS2, Visual Studio, native toolchain instructions indicate the build and deployment architecture.
- Scripting (Lua) hooks into core via src/core/scripting.c and exposes APIs under src/script.

– Front‑ends: Qt GUI, SDL frontend, Python bindings, CLI/Headless stub
– Feature modules: Command‑line parser, GUI runner, FFmpeg recorder, Video backend, Audio backend, Cheat manager, Updater, Scripting proxy
– Emulator Core: CPU cores (ARM7TDMI, SM83), System cores (GBA, GB), Memory/Tile caches, Lockstep & Sync, Rewind, Input, I/O, PPU, APU, DMA, Timers, BIOS
– Debugger: CLI debugger, GDB remote stub
– Scripting Engine: Lua host, script APIs (canvas, storage, input)
– Platform Abstraction: VFS, OS threads, OpenGL/SDL2, audio drivers, gamepad input, file dialogs
– Third‑party Libraries: zlib, libpng, SQLite3, FFmpeg, RapidJSON, ini‑parser, LZMA SDK, Discord RPC
– Test Harness & ROM loader (cinema)
– Front‑ends → Feature modules (user commands, UI events)
– Feature modules → Emulator Core (configuration, run/stop, hooking backends)
– Emulator Core → Platform Abstraction (render frame buffer via OpenGL/SDL2, output audio samples, read/write files, lock threads)
– Emulator Core ↔ Scripting Engine (script invokes emulator APIs; core calls script callbacks)
– Debugger ↔ Emulator Core (inspect/modify memory & registers; GDB stub sends packets over TCP)
– Feature modules → Third‑party libraries (FFmpeg recorder uses ffmpeg libs; SQLite3 for game DB; zlib/libpng for savestates; ini parser for configs)
– Test Harness uses Emulator Core and Platform Abstraction in headless mode, runs ROMs from cinema/

##### Architectural patterns and design principles
- Layered architecture: UI → Feature → Core → Platform.
- Plug‑in‑style feature modules: backends for audio/video, scripting, debugging.
- Abstraction and separation: CPU decoders, system cores, common core services.
- Dependency inversion: Core interfaces define behavior; API clients register as backends.
- Cross‑platform via thin platform layer and CMake toolchain files.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        QtGUI["Qt GUI Frontend"]:::frontend
        SDLFE["SDL Frontend"]:::frontend
        PyBind["Python Bindings"]:::frontend
        CLIHL["CLI/Headless Frontend"]:::frontend
    end

    %% Feature Layer
    subgraph "Feature Layer"
        CLParser["Command-line Parser"]:::feature
        GUIRunner["GUI Runner"]:::feature
        VideoBE["Video Backend"]:::feature
        FFRec["FFmpeg Recorder"]:::feature
        CheatMgr["Cheat Management"]:::feature
        ScriptProxy["Scripting Proxy"]:::feature
        ThreadProxy["Thread Proxy"]:::feature
        Updater["Updater"]:::feature
        VidLogger["Video Logger"]:::feature
        SQLiteDB["SQLite3 No-Intro DB"]:::feature
    end

    %% Core Layer
    subgraph "Core Layer"
        CoreSvc["Common Core Services"]:::core
        ARMCore["CPU Core: ARM7TDMI"]:::core
        SM83Core["CPU Core: SM83"]:::core
        GBCore["System Core: GB"]:::core
        GBACore["System Core: GBA"]:::core
        Debugger["Debugger (CLI & GDB Stub)"]:::core
        Scripting["Scripting Engine (Lua)"]:::core
    end

    %% Platform Layer
    subgraph "Platform Abstraction Layer"
        POSIX["POSIX Layer"]:::platform
        Windows["Windows Layer"]:::platform
        Port3DS["3DS Port"]:::platform
        PortSwitch["Switch Port"]:::platform
        PortWii["Wii Port"]:::platform
        PortPSP2["PSP2 Port"]:::platform
        Libretro["Libretro Frontend"]:::platform
        OpenGL["OpenGL Helper"]:::platform
    end

    %% Libraries Layer
    subgraph "Third-party Libraries"
        ThirdParty["Third-party Libraries"]:::lib
    end

    %% Test Layer
    subgraph "Test & CI"
        TestHarness["Test Harness & Cinema"]:::test
        CoreTests["Unit Tests: Core"]:::test
        DebugTests["Unit Tests: Debugger"]:::test
        GBTests["Unit Tests: GB"]:::test
        GbaTests["Unit Tests: GBA"]:::test
        ScriptTests["Unit Tests: Script"]:::test
        UtilTests["Unit Tests: Util"]:::test
        PyTests["Unit Tests: Platform (Python)"]:::test
    end

    %% Build System
    BuildSys["Build System (CMake)"]:::build

    %% Connections
    QtGUI -->|ui events| CLParser
    SDLFE -->|ui events| CLParser
    PyBind -->|bindings| CLParser
    CLIHL -->|commands| CLParser

    CLParser -->|runs| CoreSvc
    GUIRunner -->|controls| CoreSvc
    VideoBE -->|hooks| CoreSvc
    FFRec -->|records| CoreSvc
    CheatMgr -->|manages| CoreSvc
    ScriptProxy -->|forwards| CoreSvc
    ThreadProxy -->|manages threads| CoreSvc
    Updater -->|updates| CoreSvc
    VidLogger -->|logs frames| CoreSvc
    SQLiteDB -->|queries DB| CoreSvc

    CoreSvc -->|invoke| ARMCore
    CoreSvc -->|invoke| SM83Core
    CoreSvc -->|invoke| GBCore
    CoreSvc -->|invoke| GBACore

    CoreSvc -->|filesystem, threads, graphics, audio| POSIX
    CoreSvc --> POSIX
    CoreSvc --> Windows
    CoreSvc --> Port3DS
    CoreSvc --> PortSwitch
    CoreSvc --> PortWii
    CoreSvc --> PortPSP2
    CoreSvc --> Libretro
    CoreSvc --> OpenGL

    CoreSvc <-->|script API calls| Scripting
    Debugger <-->|inspect/mod| CoreSvc

    CLParser -->|uses| ThirdParty
    FFRec -->|uses| ThirdParty
    SQLiteDB -->|uses| ThirdParty
    VidLogger -->|uses| ThirdParty

    TestHarness -->|runs headless| CoreSvc
    TestHarness -->|uses| POSIX
    CoreTests --> CoreSvc
    DebugTests --> Debugger
    GBTests --> GBCore
    GbaTests --> GBACore
    ScriptTests --> Scripting
    UtilTests --> ThirdParty
    PyTests --> PyBind

    BuildSys --> QtGUI
    BuildSys --> SDLFE
    BuildSys --> CoreSvc
    BuildSys --> POSIX
    BuildSys --> ThirdParty

    %% Click Events
    click QtGUI "https://github.com/mgba-emu/mgba/tree/master/src/platform/qt"
    click SDLFE "https://github.com/mgba-emu/mgba/tree/master/src/platform/sdl"
    click PyBind "https://github.com/mgba-emu/mgba/tree/master/src/platform/python"
    click CLIHL "https://github.com/mgba-emu/mgba/tree/master/src/platform/example"
    click CLIHL "https://github.com/mgba-emu/mgba/blob/master/src/platform/headless-main.c"
    click CLParser "https://github.com/mgba-emu/mgba/blob/master/src/feature/commandline.c"
    click GUIRunner "https://github.com/mgba-emu/mgba/blob/master/src/feature/gui/gui-runner.c"
    click VideoBE "https://github.com/mgba-emu/mgba/blob/master/src/feature/video-backend.c"
    click FFRec "https://github.com/mgba-emu/mgba/blob/master/src/feature/ffmpeg/ffmpeg-recorder.c"
    click CheatMgr "https://github.com/mgba-emu/mgba/blob/master/src/feature/gui/cheats.c"
    click ScriptProxy "https://github.com/mgba-emu/mgba/blob/master/src/feature/proxy-backend.c"
    click ThreadProxy "https://github.com/mgba-emu/mgba/blob/master/src/feature/thread-proxy.c"
    click Updater "https://github.com/mgba-emu/mgba/blob/master/src/feature/updater.c"
    click VidLogger "https://github.com/mgba-emu/mgba/blob/master/src/feature/video-logger.c"
    click SQLiteDB "https://github.com/mgba-emu/mgba/blob/master/src/feature/sqlite3/no-intro.c"
    click CoreSvc "https://github.com/mgba-emu/mgba/tree/master/src/core"
    click ARMCore "https://github.com/mgba-emu/mgba/tree/master/src/arm"
    click SM83Core "https://github.com/mgba-emu/mgba/tree/master/src/sm83"
    click GBCore "https://github.com/mgba-emu/mgba/tree/master/src/gb"
    click GBACore "https://github.com/mgba-emu/mgba/tree/master/src/gba"
    click Debugger "https://github.com/mgba-emu/mgba/tree/master/src/debugger"
    click Scripting "https://github.com/mgba-emu/mgba/tree/master/src/script"
    click POSIX "https://github.com/mgba-emu/mgba/tree/master/src/platform/posix"
    click Windows "https://github.com/mgba-emu/mgba/tree/master/src/platform/windows"
    click Port3DS "https://github.com/mgba-emu/mgba/tree/master/src/platform/3ds"
    click PortSwitch "https://github.com/mgba-emu/mgba/tree/master/src/platform/switch"
    click PortWii "https://github.com/mgba-emu/mgba/tree/master/src/platform/wii"
    click PortPSP2 "https://github.com/mgba-emu/mgba/tree/master/src/platform/psp2"
    click Libretro "https://github.com/mgba-emu/mgba/tree/master/src/platform/libretro"
    click OpenGL "https://github.com/mgba-emu/mgba/tree/master/src/platform/opengl"
    click ThirdParty "https://github.com/mgba-emu/mgba/tree/master/src/third-party"
    click TestHarness "https://github.com/mgba-emu/mgba/tree/master/cinema/"
    click CoreTests "https://github.com/mgba-emu/mgba/tree/master/src/core/test"
    click DebugTests "https://github.com/mgba-emu/mgba/tree/master/src/debugger/test"
    click GBTests "https://github.com/mgba-emu/mgba/tree/master/src/gb/test"
    click GbaTests "https://github.com/mgba-emu/mgba/tree/master/src/gba/test"
    click ScriptTests "https://github.com/mgba-emu/mgba/tree/master/src/script/test"
    click UtilTests "https://github.com/mgba-emu/mgba/tree/master/src/util/test"
    click PyTests "https://github.com/mgba-emu/mgba/tree/master/src/platform/python/tests"
    click BuildSys "https://github.com/mgba-emu/mgba/blob/master/CMakeLists.txt"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef feature fill:#A9DFBF,stroke:#196F3D,color:#196F3D
    classDef core fill:#F5B7B1,stroke:#922B21,color:#922B21
    classDef platform fill:#FAD7A0,stroke:#B9770E,color:#B9770E
    classDef lib fill:#D7BDE2,stroke:#6C3483,color:#6C3483
    classDef test fill:#E5E7E9,stroke:#566573,color:#566573
    classDef build fill:#F2F3F4,stroke:#ABB2B9,color:#566573
```
