DOCSEARCHbyAlgolia
Submit Docs

mGBA Documentation

repository·master·Indexed 27 days ago

https://github.com/mgba-emu/mgba

mGBA is a high-accuracy emulator for Game Boy Advance, Game Boy, and Game Boy Color games, featuring Lua scripting and debugging. This documentation covers building the emulator on Unix-based systems, macOS, Windows (via MSYS2), and handheld platforms like 3DS, Wii, Switch, and PS Vita. It also includes details on third-party components such as Discord RPC integration for Unity and Unreal Engine, the inih INI parser, and the mingw-std-threads library.

Tokens
18.8K
Snippets
32
Records
121
Agent score
90%

What's inside mGBA

  1. Overview of mGBA features

    master

    mGBA is a high-accuracy Game Boy Advance emulator that also supports Game Boy and Game Boy Color. Key features include:

    • Hardware Support: High-accuracy GBA, GB, and GBC hardware; support for RTC (Real Time Clock), solar sensors (for Solaris series), Game Boy Camera, and Printer.
    • Performance: Fast emulation capable of running on low-end hardware.
    • Advanced Emulation: Support for Lua scripting, Turbo/Fast-forward (hold Tab), Rewind (hold `), and frame skipping (up to 10 levels).
    • Media & Saves: Video/GIF/WebP/APNG recording, screenshot support, and 9 instant-save slots with screenshot previews.
    • Debugging: Command-line interface and GDB remote support (compatible with Ghidra and IDA Pro).
    • Compatibility: Supports IPS, UPS, and BPS patches; loads ROMs from ZIP and 7z files; supports e-Reader.

  2. Overview of mGBA Emulator

    master

    mGBA is a high-speed and high-accuracy emulator for Game Boy Advance (GBA) games. It also provides compatibility for Game Boy and Game Boy Color. Key features include:

    • High Accuracy: Highly precise GBA hardware support.
    • Performance: Fast emulation capable of running on low-end hardware.
    • Graphics/Audio: SDL and Qt interfaces, support for Game Boy Camera and Printer, and real-time clock support.
    • Advanced Features: Turbo mode (hold Tab), rewind (press `), frame skipping (up to 10 frames), cheat code support, and video/GIF/WebP/APNG recording.
    • Memory/Save Support: Detection of save types (flash memory), support for IPS/UPS/BPS patches, and GameShark/Action Replay snapshot export/import.
    • Mappers: Full support for MBC1, MBC1M, MBC2, MBC3, MBC3+RTC, MBC5, MBC5+Rumble, MBC7, Wisdom Tree, Pokémon Jade/Diamond, BBD, and Hitek. Partial support for MBC6, MMM01, Pocket Cam, TAMA5, HuC-1, and HuC-3.

  5. Build libpng using Microsoft Developer Studio 7.10

    master

    To build libpng binaries using the Visual Studio 7.10 project files, follow these steps in the IDE:

    1. Open the Solution: Select File | Open Solution and open libpng.sln.
    2. View Projects: Open the Solution Explorer view using Ctrl+Alt+L.
    3. Set Startup Project:
      • To build only binaries: Select the libpng tree view item and choose Project | Set as StartUp project.
      • To build and test binaries: Select the pngtest tree view item and choose Project | Set as StartUp project.
    4. Configure Build: Select Build | Configuration Manager... to choose your desired configuration.
    5. Clean: Select Build | Clean Solution.
    6. Build: Select Build | Build Solution or use Ctrl-Shift-B.

    Assumptions for successful build:

    • libpng source files must be located in .. s.. relative to the project file.
    • zlib source files must be located in .. s.. s.. s.. slib.
    • The zlib project file must be in ./.
    1) On the main menu, select "File | Open Solution".
   Open "libpng.sln".

2) Display the Solution Explorer view (Ctrl+Alt+L)

3) Set one of the project as the StartUp project. If you just want to build the
   binaries set "libpng" as the startup project (Select "libpng" tree view
   item + Project | Set as StartUp project). If you want to build and test the
   binaries set it to "pngtest" (Select "pngtest" tree view item +
   Project | Set as StartUp project).

4) Select "Build | Configuration Manager...".
   Choose the configuration you wish to build.

5) Select "Build | Clean Solution".

6) Select "Build | Build Solution (Ctrl-Shift-B)"

  6. Build mGBA for specific handheld platforms

    master

    If you have the appropriate toolchains installed (devkitARM, devkitPPC, devkitA64, or vitasdk), you can build for 3DS, Wii, Switch, or PS Vita by passing the specific platform CMake toolchain file to the cmake command.

    mkdir build
cd build
# Example for 3DS
cmake -DCMAKE_TOOLCHAIN_FILE=../src/platform/3ds/CMakeToolchain.txt ..
make

  7. Port mGBA to a new platform

    master

    To port mGBA to a new platform, follow these architectural guidelines to ensure compatibility with the upstream codebase:

    1. Directory Structure: Place all port-specific code within the src/platform folder.
    2. Minimize Core Changes: Make minimally invasive changes to the rest of the repository. If core changes are required, attempt to make them generic and portable so they can be integrated into the main codebase later.
    3. Workflow:
      • Branch from master to begin development.
      • Once the port is mature and does not negatively impact other ports, merge it into the port/crucible branch.
      • The port/crucible branch serves as an integration area for multiple upcoming ports to test stability against periodic merges from master.
      • Note: If you intend to merge a port into master, ensure all changes are first applied to the port-specific branch and then merged into port/crucible before attempting the final merge to master.

  8. Build mGBA using Visual Studio

    master

    Building with Visual Studio requires vcpkg and Qt.

    1. Install dependencies via vcpkg: vcpkg install ffmpeg[vpx,x264] libepoxy libpng libzip sdl2 sqlite3 (Note: For Nvidia hardware acceleration, use ffmpeg[vpx,x264,nvcodec] after installing CUDA).
    2. Install Qt (offline or online installer).
    3. In Visual Studio, select "Clone Repository" and use https://github.com/mgba-emu/mgba.git.
    4. Open the CMakeLists.txt file from the checked-out repository to begin development.
    vcpkg install ffmpeg[vpx,x264] libepoxy libpng libzip sdl2 sqlite3

  9. Use PngMinus utilities png2pnm and pnm2png

    master

    PngMinus provides two basic utilities for converting between PNG and Netpbm formats (PGM/PPM). The utilities are named png2pnm and pnm2png to distinguish them from the full-featured pnmtopng and PngPlus packages.

    Input and output files can be provided as command-line parameters or via standard input/output redirection (piping).

    Key Capabilities:

    • Supports alpha-channels: When reading PNGs, transparency chunks are converted to an alpha-channel. When creating RGB+A PNGs, combine a PPM file with a corresponding PGM file containing the alpha-channel.
    • Format support: Handles PGM and PPM files. Note that it does not handle B&W PBM files (use PGM with bit-depth 1 instead).
    • Output options: Supports both ASCII and binary PGM/PPM files (16-bit depth always uses ASCII).
    • Limitations: Does not perform gamma correction. For larger images, the DOS version may encounter out-of-memory errors if memory blocks exceed 64k.

  10. Set the target Windows version for mingw-std-threads

    master

    The library automatically detects the target Windows version at compile time. If you need to manually specify the target Windows version in MinGW GCC, use the -D _WIN32_WINNT=... command-line option.

    Common values:

    • 0x0600 for Windows Vista
    • 0x0601 for Windows 7

    This implementation is compatible with Windows XP (all service packs) and newer.

  11. Compile mGBA on *nix systems

    master

    To compile using CMake on a Unix-like system, use the following sequence of commands. Dependencies are detected automatically; features requiring missing dependencies will be disabled and warnings will be shown during the cmake step.

    mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
make
sudo make install

    This installs mGBA to /usr/bin and /usr/lib.

  12. Compile mGBA for specific platforms using Toolchains

    master
    If you have the appropriate development kits installed (devkitARM, devkitPPC, devkitA64, or vitasdk), you can compile for target platforms by providing the specific CMake toolchain file path.