mGBA Logo mGBA

配置 API

mGBA 通过各种 API 提供对配置设置的编程访问。本文档介绍如何使用命令行选项、配置文件和 Lua 脚本以编程方式配置 mGBA 设置。

配置文件

mGBA 将配置存储在特定于平台的位置：

  • 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： 应用程序的 Documents 目录

配置文件格式

mGBA 使用 INI 格式作为配置文件：

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

[audio]
sampleRate = 44100
bufferSize = 2048

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

命令行配置

可用选项

mgba [options] [ROM file]

选项:
  --bios FILE          使用真实 BIOS 文件
  --config FILE        从文件加载配置
  --savedata-path DIR  设置存档数据目录
  --savestate-path DIR 设置存档状态目录
  --screenshot-path DIR 设置截图目录
  --log-level LEVEL    设置日志级别 (error, warn, info, debug)
  --headless           无 GUI 运行
  --version            显示版本信息
  --help               显示帮助消息

视频配置

分辨率缩放

  • scale： 分辨率缩放的整数值（1-10）
  • 1x： 原始 240x160 分辨率
  • 2x： 480x320 分辨率
  • 3x： 720x480 分辨率
  • 4x： 960x640 分辨率

过滤选项

  • none： 无过滤
  • bilinear： 双线性过滤
  • lcd： LCD 模拟过滤器
  • scanlines： 扫描线过滤器

渲染后端

  • software： 软件渲染
  • opengl： OpenGL 渲染
  • vulkan： Vulkan 渲染
  • direct3d11： Direct3D 11 渲染（Windows）
  • metal： Metal 渲染（macOS/iOS）

音频配置

采样率

  • 8000： 8 kHz 采样率
  • 16000： 16 kHz 采样率
  • 22050： 22.05 kHz 采样率
  • 32000： 32 kHz 采样率
  • 44100： 44.1 kHz 采样率（默认，推荐）
  • 48000： 48 kHz 采样率

缓冲区大小

音频缓冲区大小影响延迟和音频质量：

  • 小缓冲区（512-1024）： 低延迟，可能导致音频故障
  • 中等缓冲区（2048-4096）： 平衡的延迟和稳定性（默认）
  • 大缓冲区（8192+）： 高延迟，稳定的音频

输入配置

键盘映射

键盘控制可以在配置中映射：

  • keyA： A 按钮键（默认：X）
  • keyB： B 按钮键（默认：Z）
  • keyL： L 按钮键（默认：A）
  • keyR： R 按钮键（默认：S）
  • keyStart： Start 按钮键（默认：Enter）
  • keySelect： Select 按钮键（默认：Backspace）
  • keyUp/Down/Left/Right： 方向键（默认：箭头键）

模拟配置

精度设置

  • cpuAccuracy： normal 或 accurate
  • memoryTiming： normal 或 precise
  • dmaTiming： normal 或 accurate
  • frameTiming： normal 或 accurate

BIOS 配置

  • useBios： 使用真实 BIOS（true/false）
  • biosPath： BIOS 文件路径
  • skipBios： 跳过 BIOS 介绍（true/false）

存档配置

存档路径

  • savedataPath： 电池存档目录（.sav 文件）
  • savestatePath： 存档状态目录（.ss# 文件）
  • screenshotPath： 截图目录

性能配置

跳帧

  • frameSkip： 跳帧模式（none、manual、automatic）
  • maxFrameSkip： 最大跳帧数（0-10）

快进

  • fastForward： 启用快进（true/false）
  • fastForwardSpeed： 快进倍数（1x-10x）

通过 Lua API 配置

某些配置选项可以通过 Lua 脚本访问：

-- 示例：获取配置值
local scale = mGBA:getConfig("video.scale")
print("视频缩放: " .. scale)

-- 示例：设置配置值
mGBA:setConfig("video.scale", 3)
mGBA:setConfig("audio.sampleRate", 44100)

环境变量

某些配置可以通过环境变量设置：

  • MGBA_CONFIG_PATH： config.ini 的自定义路径
  • MGBA_SAVEDATA_PATH： 自定义存档数据目录
  • MGBA_LOG_LEVEL： 设置日志级别（error、warn、info、debug）

配置最佳实践

  • 在进行手动更改之前备份您的 config.ini 文件
  • 在重要游戏中使用之前测试配置更改
  • 对大多数配置使用 GUI 设置菜单（设置会自动保存）
  • 仅在 GUI 不提供对设置的访问时编辑 config.ini
  • 如果配置导致问题，请重置为默认值

相关文章

有关 mGBA 配置和使用的更多信息：