How mgba-emu/mgba works
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.