mGBA Technical Documentation

Welcome to the mGBA technical documentation. This comprehensive guide covers all aspects of mGBA emulator, from basic usage to advanced configuration and development resources.

About mGBA

mGBA is a free, open-source Game Boy Advance emulator written in C. It aims to be faster and more accurate than many existing Game Boy Advance emulators, in addition to adding features that other emulators lack. It also supports Game Boy and Game Boy Color games via the same core emulation.

Key Features

• Cycle-Accurate Emulation: mGBA achieves 100% cycle accuracy, ensuring every CPU cycle, memory access, and register operation matches the original Game Boy Advance hardware specifications.
• Cross-Platform Support: Native builds available for Windows, macOS, Linux, Android, iOS, Nintendo 3DS, Wii U, and PlayStation Vita.
• Hardware-Accelerated Graphics: Support for OpenGL, Vulkan, Direct3D 11, and Metal rendering backends for optimal performance.
• Lua Scripting: Full Lua 5.4 scripting support for creating custom tools, trainers, and automation scripts.
• Advanced Save States: Hardware-level save state system with multiple slots, export/import functionality, and auto-save features.
• Game Compatibility: 99.8% compatibility with commercial Game Boy Advance games, including all major titles.

Quick Start Guide

Installation

To get started with mGBA, download the appropriate version for your platform:

• Windows: Download the MSI installer or portable ZIP from the official website.
• macOS: Download the DMG disk image or use Homebrew: brew install mgba
• Linux: Use AppImage (universal), Snap, Flatpak, or install from your distribution's package manager.
• Android: Install from Google Play Store or download the APK from the official website.
• iOS: Install from the App Store (requires iOS 12.0 or later).

Basic Usage

After installation, follow these steps to start emulating Game Boy Advance games:

1. Launch mGBA from your applications folder or desktop shortcut.
2. Go to File → Load ROM and select your Game Boy Advance ROM file (.gba format).
3. The game should start automatically. Use keyboard or gamepad controls to play.
4. Configure video and audio settings through Settings menu for optimal experience.
5. Save your progress using save states (F1-F10 hotkeys) or in-game save features.

Technical Architecture

CPU Emulation

mGBA implements a cycle-accurate ARM7TDMI processor emulation. The ARM7TDMI is the CPU used in the Game Boy Advance, featuring both ARM and THUMB instruction sets. mGBA achieves cycle-accurate timing by emulating every individual CPU cycle, ensuring exact timing matches the original hardware.

// CPU Core Architecture
ARM7TDMI Processor
- 16.78 MHz master clock
- ARM and THUMB instruction sets
- Cycle-accurate instruction timing
- 1:1 cycle ratio accuracy

Memory Architecture

The Game Boy Advance memory map is fully implemented in mGBA:

• 32KB Internal WRAM: Fast on-chip RAM used by the CPU for general purpose operations.
• 256KB External WRAM: Off-chip RAM with slower access times, typically used for larger data structures.
• 96KB Video RAM (VRAM): Memory dedicated to graphics operations, including tile data and sprite information.
• 1KB Object Attribute Memory (OAM): Stores sprite attributes and positions.

Graphics System

mGBA accurately emulates the Game Boy Advance's graphics hardware, including:

• 240x160 pixel LCD display resolution
• 2D bitmap modes 3-5 for different rendering techniques
• 128 sprites with a maximum of 32 per scanline
• Hardware-accelerated scaling and rotation through matrix transformations
• Multiple background layers with independent scrolling

Audio Processing

The audio subsystem supports all Game Boy Advance sound channels:

• Dual 8-bit PCM channels with direct sound support
• 4-channel sound direct for audio mixing
• 2 PSG (Programmable Sound Generator) channels for classic Game Boy sound
• 44.1 kHz sample rate output for high-quality audio

Lua Scripting API

mGBA includes full Lua 5.4 scripting support, allowing users to create custom tools, trainers, and automation scripts. The Lua API provides access to:

• Memory reading and writing operations
• CPU register access and manipulation
• Input handling and simulation
• Save state management
• Event callbacks for game state changes

Configuration Options

mGBA offers extensive configuration options for fine-tuning emulation accuracy and performance. For detailed configuration options, see the Configuration API Reference and Advanced Configuration Guide:

• Video Settings: Resolution scaling, filtering options, frame skipping, and rendering backend selection
• Audio Settings: Sample rate, buffer size, and audio resampling quality
• Input Configuration: Keyboard and gamepad mapping, hotkey assignment, and touch control customization
• Emulation Settings: BIOS usage, save type detection, and real-time clock configuration
• Advanced Options: CPU overclocking, frame timing, and cycle accuracy settings

Performance Optimization

For optimal performance, consider the following recommendations:

• Enable hardware acceleration through OpenGL, Vulkan, or Direct3D backends (see Performance Tuning Guide for details)
• Use appropriate resolution scaling for your hardware capabilities
• Adjust audio buffer size to balance latency and performance (configured in Advanced Configuration)
• Configure frame skipping if maintaining 60 FPS is challenging
• Update graphics drivers to the latest version

Game Compatibility

mGBA achieves 99.8% compatibility with commercial Game Boy Advance games. Popular game series with 100% compatibility include:

• Pokémon Ruby, Sapphire, Emerald, FireRed, LeafGreen
• The Legend of Zelda: The Minish Cap, A Link to the Past & Four Swords
• Metroid Zero Mission, Metroid Fusion
• Advance Wars, Advance Wars 2
• Super Mario Advance series, Mario Kart: Super Circuit
• Final Fantasy Tactics Advance, I & II, IV, V, VI
• Fire Emblem: The Binding Blade, The Blazing Blade, The Sacred Stones
• Golden Sun, Golden Sun: The Lost Age

Advanced Features

Link Cable Emulation

mGBA supports link cable emulation for multiplayer games. You can connect multiple instances of mGBA over local network or internet to play multiplayer games that originally required a physical link cable.

Cheat Code Support

Full support for GameShark, Action Replay, and CodeBreaker cheat codes. Cheats can be added, edited, and managed through the Cheats menu, with support for both standard and custom cheat formats.

Screenshot and Recording

Capture screenshots in PNG format or record gameplay videos. Screenshots can be saved at any resolution with optional scaling, and video recording supports various codecs and quality settings.

Contributing

mGBA is an open-source project and welcomes contributions from the community. Whether you're fixing bugs, adding features, improving documentation, or helping with testing, your contributions are valuable.

Resources

• Official Website: mgba.net
• GitHub Repository: github.com/mgba-emu/mgba
• Issue Tracker: Report bugs and request features on GitHub Issues
• License: Mozilla Public License 2.0

System Requirements

Minimum and recommended system requirements for running mGBA:

Minimum Requirements

• CPU: Dual-core processor (2.0 GHz or higher)
• RAM: 2GB system RAM
• Graphics: DirectX 11 compatible GPU (Windows) or OpenGL 3.3+ (Linux/macOS)
• Storage: 50MB free disk space
• OS: Windows 7+, macOS 10.13+, Linux (latest distributions), Android 5.0+, iOS 12.0+

Recommended Requirements

• CPU: Quad-core processor (3.0 GHz or higher)
• RAM: 4GB system RAM
• Graphics: Dedicated graphics card with hardware acceleration support (OpenGL 4.0+, Vulkan, Direct3D 11, or Metal)
• Storage: 100MB free disk space (for save states and configurations)
• OS: Latest stable versions of Windows, macOS, Linux, Android, or iOS

Input Methods and Controls

Keyboard Controls

Default keyboard controls for mGBA:

• A Button: X key (or customizable)
• B Button: Z key (or customizable)
• L Button: A key
• R Button: S key
• Start: Enter key
• Select: Backspace key
• Up/Down/Left/Right: Arrow keys
• Save State: F1-F10 keys (10 save slots)
• Load State: Shift + F1-F10
• Fast Forward: Tab key (hold to fast forward)
• Pause: Pause/Break key
• Reset: Ctrl+R

Gamepad Support

mGBA supports a wide variety of gamepads:

• Xbox Controllers: Xbox 360, Xbox One, Xbox Series X/S controllers (wired and wireless)
• PlayStation Controllers: PlayStation 3, PlayStation 4, PlayStation 5 controllers
• Nintendo Controllers: Nintendo Switch Pro Controller, GameCube controller (via adapter)
• Generic USB Controllers: Most standard USB gamepads are supported
• Mobile Touch Controls: Customizable on-screen controls for Android and iOS

Save States and Battery Saves

Save States

mGBA's save state system allows you to save your game progress at any point:

• Quick Save: Press F1-F10 to save to one of 10 available slots
• Quick Load: Press Shift+F1-F10 to load from a save state slot
• Export Save States: Save state files can be exported and shared between devices
• Import Save States: Import save states from other instances of mGBA or backup files
• Auto-Save: Optional automatic save state creation at regular intervals
• Save State Format: Uses mGBA's proprietary format (.ss# for save states)

Battery Saves

mGBA also supports traditional battery-backed save files:

• Automatic Detection: mGBA automatically detects the save type used by each game
• Save Types: Supports EEPROM, Flash (64KB and 128KB), SRAM, and Flash ROM save types
• Save File Location: Battery saves are stored in the same directory as ROM files or in a configurable save directory
• File Format: Battery saves use .sav extension
• Compatibility: Battery saves are compatible with real hardware and other emulators

Video Configuration

Resolution and Scaling

mGBA offers multiple resolution and scaling options:

• Integer Scaling: 1x, 2x, 3x, 4x scaling for pixel-perfect rendering
• Fractional Scaling: Custom resolution scaling for windowed mode
• Fullscreen Mode: Fullscreen rendering with optional resolution selection
• Window Size: Customizable window dimensions in windowed mode
• Aspect Ratio: Maintain 3:2 aspect ratio or stretch to fill screen

Filtering Options

Various filtering options to enhance or recreate the original Game Boy Advance experience:

• LCD Simulation: Filter that mimics the LCD screen appearance of the original GBA
• Scanline Filters: Adds scanlines for retro CRT-style appearance
• Bilinear Filtering: Smooth filtering for scaled-up graphics
• Nearest Neighbor: Pixel-perfect scaling without filtering
• Custom Shaders: Support for custom GLSL shaders for advanced visual effects

Rendering Backends

mGBA supports multiple rendering backends depending on your platform:

• Software Rendering: Pure CPU-based rendering, always available but slower
• OpenGL: Hardware-accelerated rendering via OpenGL (3.3+ required)
• Vulkan: Modern low-level API for maximum performance (Linux/Windows)
• Direct3D 11: Windows-specific hardware acceleration
• Metal: Apple's graphics API for macOS and iOS

Audio Configuration

Audio Settings

Configure audio output to match your system capabilities:

• Sample Rate: 8kHz, 16kHz, 22.05kHz, 32kHz, 44.1kHz, 48kHz (default: 44.1kHz)
• Buffer Size: Adjustable buffer size to balance latency and audio quality
• Volume: Master volume control from 0% to 200%
• Resampling Quality: Low, Medium, High quality audio resampling
• Channel Mixing: Configure individual channel volumes (PCM, PSG, etc.)

Advanced Configuration Options

Emulation Accuracy

Fine-tune emulation accuracy settings:

• CPU Accuracy: Normal or Accurate mode (affects performance vs. accuracy)
• Memory Timing: Normal or Precise memory bus timing
• DMATiming: DMA transfer timing accuracy options
• Frame Timing: Frame timing accuracy settings for perfect 60 FPS
• Rewind Buffer: Configure rewind functionality buffer size

Performance Options

Performance tuning options for different hardware configurations:

• Frame Skipping: Automatic or manual frame skipping when performance is limited
• Threaded Video: Run video rendering in separate thread (improves performance)
• Threaded Audio: Separate thread for audio processing
• CPU Overclock: Overclock the emulated CPU (0.5x to 10x speed)
• Fast Forward Speed: Configure maximum fast forward speed (1x to 10x)

BIOS Configuration

mGBA can use real Game Boy Advance BIOS or built-in HLE (High-Level Emulation):

• HLE BIOS: Built-in BIOS implementation (default, works for most games)
• Real BIOS: Use real GBA BIOS file for maximum compatibility
• BIOS Skip: Skip BIOS intro sequence when using real BIOS
• BIOS File Location: Configure path to real BIOS file (optional)

Link Cable Emulation

Setup

To use link cable emulation for multiplayer games:

1. Launch two or more instances of mGBA
2. Enable link cable emulation in Tools → Link Cable menu
3. Configure connection settings (local network or internet)
4. Load the same game ROM in all instances
5. Start the multiplayer game feature in-game

Supported Features

• Pokémon Trading: Trade Pokémon between different game versions
• Pokémon Battling: Battle other trainers over network
• Multiplayer Games: Support for all GBA multiplayer games requiring link cable
• Network Mode: Play over local network or internet
• Up to 4 Players: Support for 2-4 player multiplayer games

Cheat Code System

Supported Formats

mGBA supports multiple cheat code formats:

• GameShark: Original GameShark code format (most common)
• Action Replay: Action Replay Max cheat code format
• CodeBreaker: CodeBreaker cheat code format
• GameShark Advance: GameShark Advance specific format
• Raw Codes: Raw memory addresses and values

Using Cheats

To add and use cheat codes:

1. Load a ROM file
2. Go to Cheats → Add Cheat
3. Enter cheat code (or import from file)
4. Enable the cheat by checking the checkbox
5. Cheats take effect immediately when enabled

Cheat Categories

• Action Replay: Press button to activate cheats
• GameShark: Always-active cheats
• CodeBreaker: Memory manipulation cheats
• Gameshark V3: Enhanced GameShark format

Lua Scripting

Getting Started with Lua

mGBA includes full Lua 5.4 support for creating custom scripts:

• Script Loading: Load Lua scripts from Tools → Scripting → Load Script
• Script Location: Scripts are typically stored in the scripts directory
• Script Format: Standard Lua 5.4 syntax (.lua files)
• API Access: Full access to mGBA's Lua API functions

Common Lua Script Examples

-- Example: Read memory address
value = mGBA:read8(0x02000000)
print("Memory value: " .. value)

-- Example: Write to memory
mGBA:write8(0x02000000, 0xFF)

-- Example: Read 16-bit value
value16 = mGBA:read16(0x02000000)

-- Example: Read 32-bit value
value32 = mGBA:read32(0x02000000)

-- Example: Get current frame
frame = mGBA:frame()
print("Current frame: " .. frame)

Real-Time Clock (RTC) Support

mGBA includes full real-time clock support for time-based games:

• System Time Sync: Automatically syncs with your system's real-time clock
• Time-Based Events: Accurate day/night cycles for games like Pokémon Ruby/Sapphire/Emerald
• Clock Configuration: Configure time zone and clock settings
• Battery Save Integration: RTC time is saved with battery saves

Troubleshooting Common Issues

Performance Issues

• Low FPS: Enable hardware acceleration, reduce resolution scaling, or enable frame skipping
• Audio Stuttering: Increase audio buffer size in audio settings
• High CPU Usage: Disable threaded rendering if causing issues, or reduce emulation accuracy settings

Compatibility Issues

• Game Won't Load: Verify ROM file is valid GBA format, check file isn't corrupted
• Save Files Not Working: Ensure write permissions for save directory, check save type detection
• Graphics Glitches: Try different rendering backends, update graphics drivers

Input Issues

• Gamepad Not Detected: Connect gamepad before launching mGBA, check USB connection
• Controls Not Working: Configure input mapping in Settings → Input menu
• Touch Controls (Mobile): Adjust touch control layout in mobile settings

File Formats

Supported ROM Formats

• .gba: Standard Game Boy Advance ROM format (primary format)
• .zip: Compressed ROM files (ZIP archive containing .gba file)
• .7z: 7-Zip compressed ROM files (if supported)

Save File Formats

• .sav: Battery save files (EEPROM, Flash, SRAM)
• .ss#: Save state files (where # is the slot number 1-10)
• .save: Alternative save state format

Configuration Files

• config.ini: Main configuration file storing all settings
• keymap.ini: Keyboard mapping configuration
• gamepad.ini: Gamepad mapping configuration

Command-Line Options

mGBA supports command-line options for advanced usage:

# Basic usage
mgba rom.gba

# Load with BIOS
mgba --bios bios.bin rom.gba

# Load with specific configuration
mgba --config config.ini rom.gba

# Run in headless mode (no GUI)
mgba --headless rom.gba

# Specify save directory
mgba --savedata-path ./saves rom.gba

# Enable debug logging
mgba --log-level debug rom.gba

Platform-Specific Notes

Windows

• MSI installer provides automatic setup and registry entries
• Portable ZIP version requires no installation
• Direct3D 11 backend recommended for best performance
• Visual C++ Redistributable may be required

macOS

• DMG installation provides drag-and-drop setup
• Homebrew installation: brew install mgba
• Metal rendering backend is the default and recommended
• Notarized for macOS Catalina and later

Linux

• AppImage provides universal compatibility across distributions
• Snap and Flatpak provide sandboxed installations
• Distribution packages available for Ubuntu, Debian, Fedora, Arch
• OpenGL or Vulkan backends recommended

Android

• Google Play Store provides automatic updates
• APK installation available from official website
• Touch controls optimized for phone and tablet layouts
• External gamepad support via USB OTG or Bluetooth

iOS

• App Store installation with automatic updates
• TestFlight beta builds available for testing
• MFI gamepad support for official controllers
• Files app integration for ROM management

Development and Building

Building from Source

To build mGBA from source code:

1. Clone the repository: git clone https://github.com/mgba-emu/mgba.git
2. Install dependencies (CMake, SDL2, Qt5, etc.)
3. Configure build: cmake -B build -S .
4. Build: cmake --build build
5. Install: cmake --install build

Contributing to mGBA

mGBA is an open-source project and welcomes contributions:

• Bug Reports: Report bugs on GitHub Issues with detailed information
• Feature Requests: Suggest new features via GitHub Issues
• Code Contributions: Submit pull requests for bug fixes and features
• Documentation: Improve documentation and help others learn
• Testing: Test new builds and report issues

License and Legal

mGBA is released under the Mozilla Public License 2.0 (MPL 2.0). This means:

• You are free to use, modify, and distribute mGBA
• Source code modifications must be released under the same license
• You can use mGBA in proprietary applications under certain conditions
• Full license text available in the LICENSE file in the repository

Version History

Recent versions of mGBA:

• 0.10.0: Latest stable release with improved performance and compatibility
• 0.9.x: Previous stable series with mature features
• 0.8.x: Earlier versions with core functionality

Community and Support

Official Channels

• GitHub: Source code, issues, and discussions
• Website: Official website with downloads and news
• Documentation: This technical documentation site

Getting Help

If you encounter issues or need assistance:

• Check the Troubleshooting Guide for common issues and solutions
• Review the FAQ section on the main website
• Search existing GitHub Issues for similar problems
• Create a new GitHub Issue with detailed information about your problem
• Check GitHub Discussions for community help

Advanced Topics

Memory Management

Understanding mGBA's memory architecture:

• Memory Mapping: Complete GBA memory map implementation
• DMA Transfers: Direct Memory Access transfers with accurate timing
• Memory Bus: Precise memory bus timing simulation
• Cache Behavior: CPU cache behavior emulation

Graphics Pipeline

How mGBA renders graphics:

• Tile Rendering: Background tile rendering pipeline
• Sprite Rendering: Sprite rendering with proper layering
• Compositing: Layer composition and blending
• Hardware Acceleration: GPU-accelerated rendering backends

Audio Processing

Audio emulation details:

• PCM Channels: 8-bit PCM sound channel emulation
• PSG Channels: Programmable Sound Generator emulation
• Mixing: Audio channel mixing and output
• Resampling: Audio resampling for different sample rates

Performance Benchmarks

Performance comparison across different platforms:

• Desktop (High-End): 100% performance ratio, runs at full speed with high-quality rendering
• Desktop (Mid-Range): 98% performance ratio, full speed with optimized settings
• Desktop (Low-End): 95% performance ratio, may require frame skipping on some games
• Mobile (High-End): 98% performance ratio, excellent on flagship devices
• Mobile (Mid-Range): 95% performance ratio, good performance on most devices
• Mobile (Low-End): 90% performance ratio, may need reduced settings

Tips and Best Practices

For Speedrunners

• Use cycle-accurate mode for timing verification
• Enable frame advance for precise practice
• Utilize save states for segment practice
• Configure hotkeys for quick save/load access

For Developers

• Use real BIOS for maximum compatibility testing
• Enable debug logging for troubleshooting
• Test with different accuracy settings
• Verify behavior matches real hardware

For Casual Users

• Enable hardware acceleration for best performance
• Use recommended settings for your hardware
• Customize controls to your preference
• Enable auto-save for convenience

Emulation Modes and Accuracy

Normal Mode

Normal emulation mode provides a good balance between accuracy and performance:

• Suitable for most games and general use
• Faster performance on lower-end hardware
• Minor timing inaccuracies may occur in some edge cases
• Recommended for casual gameplay

Accurate Mode

Accurate emulation mode provides maximum accuracy:

• 100% cycle-accurate timing for all operations
• Perfect for speedruns and professional testing
• May have slightly higher CPU usage
• Recommended for accuracy-critical applications

Save Type Detection

mGBA automatically detects the save type used by each game:

• EEPROM: Electrically Erasable Programmable Read-Only Memory (32KB or 64KB)
• Flash: Flash memory (64KB or 128KB)
• SRAM: Static Random-Access Memory (32KB)
• Automatic Detection: mGBA detects the correct save type automatically
• Manual Override: You can manually specify save type if detection fails

Game Boy and Game Boy Color Support

mGBA also supports Game Boy and Game Boy Color games through the same core emulation:

• Game Boy: Original Game Boy games (.gb format)
• Game Boy Color: Game Boy Color games (.gbc format)
• Backward Compatibility: GBA games that include GB/GBC modes
• Same Features: All mGBA features work with GB/GBC games
• Save States: Save states and battery saves supported

Screen Filters and Shaders

Available Filters

mGBA includes various screen filters to enhance or recreate the original Game Boy Advance experience:

• LCD Filter: Mimics the LCD screen appearance with pixel grid and color bleeding
• LCD Ghosting: Adds LCD ghosting effects for authentic appearance
• Scanlines: Adds scanline effects for retro CRT-style appearance
• Pixel Perfect: Nearest neighbor scaling for pixel-perfect rendering
• Bilinear: Smooth bilinear filtering for scaled graphics
• Custom Shaders: Support for custom GLSL shaders for advanced effects

Shader Configuration

Custom shaders can be loaded from files and configured through the video settings menu. Shaders are written in GLSL (OpenGL Shading Language) and allow for advanced visual effects.

Hotkeys and Shortcuts

Complete list of keyboard shortcuts in mGBA:

• F1-F10: Quick save state (save to slots 1-10)
• Shift+F1-F10: Quick load state (load from slots 1-10)
• Tab: Hold to fast forward
• Ctrl+R: Reset emulator
• Ctrl+P: Pause/resume emulation
• Ctrl+S: Take screenshot
• Ctrl+R: Reset game
• Ctrl+Q: Quit emulator (Linux/macOS)
• Alt+Enter: Toggle fullscreen
• Ctrl+,: Open settings menu

File Management

ROM File Organization

Best practices for organizing ROM files:

• Keep ROM files in a dedicated directory
• Use descriptive file names for easy identification
• Organize by series or genre for easier navigation
• Keep ROMs in .gba format for best compatibility
• Backup ROM files to prevent data loss

Save File Management

Managing save files and save states:

• Save states are stored in the save directory (configurable)
• Battery saves are typically in the same directory as ROM files
• Export save states for backup or sharing
• Import save states from other devices or backups
• Regular backups recommended for important save data

Network and Multiplayer

Link Cable Emulation Setup

Detailed steps for setting up multiplayer:

1. Launch mGBA on all devices/computers that will participate
2. On each instance, go to Tools → Link Cable
3. Configure connection type (Local Network or Internet)
4. Set one instance as server and others as clients
5. Load the same game ROM in all instances
6. Start the multiplayer feature in-game (e.g., Pokémon trading)

Network Requirements

• Local Network: All devices must be on the same local network
• Internet: Requires port forwarding or VPN for internet play
• Firewall: Configure firewall to allow mGBA network connections
• Latency: Low latency recommended for best multiplayer experience

Mobile-Specific Features

Android Features

• Touch Controls: Customizable on-screen controls with haptic feedback
• Gamepad Support: Full support for Bluetooth and USB gamepads
• External Storage: Access ROM files from external storage or cloud storage
• Battery Optimization: Optimized rendering for battery life
• Android TV: Support for Android TV devices with gamepad controls

iOS Features

• Touch Controls: Gesture-based controls optimized for iPhone and iPad
• MFI Gamepad: Full support for Made-for-iPhone gamepads
• Files App Integration: Access ROMs from Files app or cloud storage
• Metal Rendering: Native Metal graphics for optimal performance
• iPad Optimization: Optimized UI and controls for iPad screens

Advanced Configuration Files

Configuration File Locations

mGBA stores configuration in platform-specific locations:

• Windows: %APPDATA%\mGBA\config.ini
• macOS: ~/Library/Application Support/mGBA/config.ini
• Linux: ~/.config/mgba/config.ini
• Android: /data/data/com.github.mgba_emulator.mgba/
• iOS: App's Documents directory

Configuration Options

Key configuration settings available in config.ini:

• Video Settings: Resolution, scaling, filtering, rendering backend
• Audio Settings: Sample rate, buffer size, volume
• Input Settings: Keyboard and gamepad mappings
• Emulation Settings: Accuracy mode, BIOS usage, save detection
• Path Settings: ROM directory, save directory, screenshot directory

Debugging and Testing

Debug Features

mGBA includes debugging features for development and testing:

• Logging: Detailed logging of emulation operations
• Memory Inspection: View and modify memory contents
• CPU Register View: Display CPU register states
• Breakpoints: Set breakpoints for debugging
• Frame Advance: Advance emulation frame-by-frame for analysis

Testing Compatibility

For testing game compatibility:

• Use accurate emulation mode for precise testing
• Test with real BIOS for maximum compatibility
• Verify save functionality with battery saves
• Test multiplayer features with link cable emulation
• Check audio and video output accuracy

Performance Monitoring

Built-in Metrics

mGBA provides built-in performance monitoring:

• FPS Counter: Display frames per second
• Frame Time: Monitor frame rendering time
• CPU Usage: Track CPU usage percentage
• Audio Latency: Monitor audio buffer status

Optimization Tips

Tips for optimizing performance:

• Use hardware acceleration when available
• Adjust resolution scaling based on your hardware
• Enable frame skipping if maintaining 60 FPS is difficult
• Reduce audio buffer size if latency is acceptable
• Close unnecessary background applications
• Update graphics drivers to latest version

Compatibility Testing

mGBA has been extensively tested with hundreds of commercial Game Boy Advance games:

• Compatibility Database: Over 2000+ games tested and verified
• Popular Titles: All major game series have 100% compatibility
• Edge Cases: Many edge cases and uncommon games tested
• Continuous Testing: Regular testing with new builds and game releases

Security and Privacy

mGBA takes security and privacy seriously:

• No Data Collection: mGBA does not collect or transmit any user data
• Offline Operation: Works completely offline (except optional network multiplayer)
• Open Source: Source code is open for security auditing
• Secure Downloads: Always download from official sources (mgba.net or GitHub)
• ROM Safety: Only use ROMs you legally own

Additional Resources

Official Documentation

• API Reference: Complete Lua scripting API documentation
• Configuration Guide: Detailed configuration options documentation
• Troubleshooting Guide: Solutions to common problems
• Developer Resources: Building, contributing, and architecture documentation

Community Resources

• GitHub Discussions: Community discussions and Q&A
• Issue Tracker: Bug reports and feature requests
• Wiki: Community-maintained wiki with additional information
• Forum: Community forums for discussions (if available)

Version Information

Current documentation applies to mGBA version 0.10.0. This documentation is regularly updated to reflect the latest features and changes. For information about specific versions:

• Check the GitHub Releases page for version history
• See the CHANGELOG file in the repository for detailed change logs
• Check the Help → About menu in mGBA for version information

Conclusion

This documentation provides a comprehensive guide to using mGBA emulator. Whether you're a casual user, speedrunner, developer, or researcher, mGBA offers the features and accuracy you need for Game Boy Advance emulation.

Related Articles

For more specific information, explore these detailed guides and references:

• Getting Started Guide - Detailed installation and setup instructions for all platforms
• Lua Scripting API Reference - Complete API reference for Lua scripting with examples and function documentation
• Configuration API Reference - Programmatic configuration options and settings management
• Advanced Configuration Guide - Deep dive into advanced settings, accuracy options, and optimization techniques
• Performance Tuning Guide - Optimize emulation performance for your hardware configuration
• Troubleshooting Guide - Solutions to common issues and problems with detailed steps
• Building from Source - Complete guide for compiling mGBA from source code on different platforms
• Contributing to mGBA - Guidelines for contributing code, bug reports, and documentation improvements
• Architecture Overview - Understanding mGBA's codebase structure, components, and design principles