mGBA Logo mGBA

Configuration API

mGBA provides programmatic access to configuration settings through various APIs. This documentation covers how to configure mGBA settings programmatically using command-line options, configuration files, and Lua scripting.

Configuration Files

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 File Format

mGBA uses INI format for configuration files:

[video]
scale = 3
filter = bilinear
backend = opengl

[audio]
sampleRate = 44100
bufferSize = 2048

[input]
keyA = X
keyB = Z
keyL = A
keyR = S

Command-Line Configuration

Available Options

mgba [options] [ROM file]

Options:
  --bios FILE          Use real BIOS file
  --config FILE        Load configuration from file
  --savedata-path DIR  Set save data directory
  --savestate-path DIR Set save state directory
  --screenshot-path DIR Set screenshot directory
  --log-level LEVEL    Set log level (error, warn, info, debug)
  --headless           Run without GUI
  --version            Show version information
  --help               Show help message

Video Configuration

Resolution Scaling

  • scale: Integer value (1-10) for resolution scaling
  • 1x: Original 240x160 resolution
  • 2x: 480x320 resolution
  • 3x: 720x480 resolution
  • 4x: 960x640 resolution

Filtering Options

  • none: No filtering
  • bilinear: Bilinear filtering
  • lcd: LCD simulation filter
  • scanlines: Scanline filter

Rendering Backends

  • software: Software rendering
  • opengl: OpenGL rendering
  • vulkan: Vulkan rendering
  • direct3d11: Direct3D 11 rendering (Windows)
  • metal: Metal rendering (macOS/iOS)

Audio Configuration

Sample Rates

  • 8000: 8 kHz sample rate
  • 16000: 16 kHz sample rate
  • 22050: 22.05 kHz sample rate
  • 32000: 32 kHz sample rate
  • 44100: 44.1 kHz sample rate (default, recommended)
  • 48000: 48 kHz sample rate

Buffer Size

Audio buffer size affects latency and audio quality:

  • Small Buffer (512-1024): Low latency, may cause audio glitches
  • Medium Buffer (2048-4096): Balanced latency and stability (default)
  • Large Buffer (8192+): High latency, stable audio

Input Configuration

Keyboard Mapping

Keyboard controls can be mapped in configuration:

  • keyA: A button key (default: X)
  • keyB: B button key (default: Z)
  • keyL: L button key (default: A)
  • keyR: R button key (default: S)
  • keyStart: Start button key (default: Enter)
  • keySelect: Select button key (default: Backspace)
  • keyUp/Down/Left/Right: D-pad keys (default: Arrow keys)

Emulation Configuration

Accuracy Settings

  • cpuAccuracy: normal or accurate
  • memoryTiming: normal or precise
  • dmaTiming: normal or accurate
  • frameTiming: normal or accurate

BIOS Configuration

  • useBios: Use real BIOS (true/false)
  • biosPath: Path to BIOS file
  • skipBios: Skip BIOS intro (true/false)

Save Configuration

Save Paths

  • savedataPath: Directory for battery saves (.sav files)
  • savestatePath: Directory for save states (.ss# files)
  • screenshotPath: Directory for screenshots

Performance Configuration

Frame Skipping

  • frameSkip: Frame skip mode (none, manual, automatic)
  • maxFrameSkip: Maximum frames to skip (0-10)

Fast Forward

  • fastForward: Enable fast forward (true/false)
  • fastForwardSpeed: Fast forward multiplier (1x-10x)

Configuration via Lua API

Some configuration options can be accessed through Lua scripting:

-- Example: Get configuration value
local scale = mGBA:getConfig("video.scale")
print("Video scale: " .. scale)

-- Example: Set configuration value
mGBA:setConfig("video.scale", 3)
mGBA:setConfig("audio.sampleRate", 44100)

Environment Variables

Some configuration can be set via environment variables:

  • MGBA_CONFIG_PATH: Custom path to config.ini
  • MGBA_SAVEDATA_PATH: Custom save data directory
  • MGBA_LOG_LEVEL: Set log level (error, warn, info, debug)

Configuration Best Practices

  • Backup your config.ini file before making manual changes
  • Test configuration changes before using in important gameplay
  • Use GUI settings menu for most configuration (settings are saved automatically)
  • Edit config.ini only when GUI doesn't provide access to a setting
  • Reset to defaults if configuration causes issues

Related Articles

For more information about mGBA configuration and usage: