Lua 脚本 API
mGBA 包含完整的 Lua 5.4 脚本支持，允许您创建自定义工具、训练器、自动化脚本和游戏修改。本文档提供了 Lua 脚本 API 的完整参考。
Lua 脚本入门
加载脚本
在 mGBA 中加载 Lua 脚本：
- 转到 工具 → 脚本 → 加载脚本
- 导航到您的 Lua 脚本文件（.lua 格式）
- 选择脚本文件并点击打开
- 脚本将自动加载并执行
脚本位置： Lua 脚本通常存储在 mGBA 配置文件夹内的 scripts 目录中。您也可以从系统上的任何位置加载脚本。
内存访问函数
read8(address)
从内存读取 8 位值。
参数：
address(number): 内存地址（0x00000000 到 0xFFFFFFFF）
返回： 8 位值（0-255）
-- 示例：从内存读取 8 位值
value = mGBA:read8(0x02000000)
print("地址 0x02000000 的值: " .. value)
read16(address)
从内存读取 16 位值。
参数：
address(number): 内存地址
返回： 16 位值（0-65535）
-- 示例：读取 16 位值
value = mGBA:read16(0x02000000)
print("16 位值: " .. value)
read32(address)
从内存读取 32 位值。
参数：
address(number): 内存地址
返回： 32 位值
-- 示例：读取 32 位值
value = mGBA:read32(0x02000000)
print("32 位值: " .. value)
write8(address, value)
向内存写入 8 位值。
参数：
address(number): 内存地址value(number): 8 位值（0-255）
-- 示例：写入 8 位值 mGBA:write8(0x02000000, 0xFF)
write16(address, value)
向内存写入 16 位值。
参数：
address(number): 内存地址value(number): 16 位值（0-65535）
write32(address, value)
向内存写入 32 位值。
参数：
address(number): 内存地址value(number): 32 位值
CPU 和寄存器函数
getRegister(registerName)
获取 CPU 寄存器值。
参数：
registerName(string): 寄存器名称（例如："r0"、"r1"、"pc"、"sp"）
返回： 寄存器值（32 位）
-- 示例：获取 PC（程序计数器）值
pc = mGBA:getRegister("pc")
print("程序计数器: " .. string.format("0x%08X", pc))
setRegister(registerName, value)
设置 CPU 寄存器值。
参数：
registerName(string): 寄存器名称value(number): 32 位值
帧和计时函数
frame()
获取当前帧号。
返回： 当前帧号
-- 示例：获取当前帧
currentFrame = mGBA:frame()
print("当前帧: " .. currentFrame)
reset()
重置模拟器。
-- 示例：重置模拟器 mGBA:reset()
存档状态函数
saveState(slot)
将状态保存到插槽。
参数：
slot(number): 存档插槽号（1-10）
loadState(slot)
从插槽加载状态。
参数：
slot(number): 存档插槽号（1-10）
输入函数
pressButton(button)
以编程方式按下按钮。
参数：
button(string): 按钮名称（"A"、"B"、"L"、"R"、"Start"、"Select"、"Up"、 "Down"、"Left"、"Right"）
-- 示例：按下 A 按钮
mGBA:pressButton("A")
事件回调
mGBA Lua API 支持游戏状态变化的事件回调：
-- 示例：帧回调
function onFrame()
-- 此函数每帧调用
local frame = mGBA:frame()
if frame % 60 == 0 then
print("帧: " .. frame)
end
end
-- 注册回调
mGBA:onFrame(onFrame)
常见脚本示例
生命值训练器
-- 生命值训练器示例
local healthAddress = 0x02000000 -- 替换为实际地址
function infiniteHealth()
mGBA:write16(healthAddress, 999)
end
-- 每帧运行
mGBA:onFrame(infiniteHealth)
帧计数器
-- 帧计数器脚本
local startFrame = mGBA:frame()
function countFrames()
local current = mGBA:frame()
local elapsed = current - startFrame
print("已过帧数: " .. elapsed)
end
mGBA:onFrame(countFrames)
内存地址
Game Boy Advance 游戏的常见内存地址：
- 内部 WRAM： 0x03000000 - 0x03007FFF (32KB)
- 外部 WRAM： 0x02000000 - 0x0203FFFF (256KB)
- 视频 RAM： 0x06000000 - 0x06017FFF (96KB)
- 游戏卡 ROM： 0x08000000 - 0x0DFFFFFF（因游戏而异）
- 游戏卡 SRAM： 0x0E000000 - 0x0E00FFFF（因游戏而异）
注意： 内存地址因游戏而异。使用内存扫描器或调试器查找您游戏的具体地址。
最佳实践
- 在读取/写入之前始终验证内存地址
- 对内存操作使用适当的数据类型（8 位、16 位、32 位）
- 小心使用帧回调以避免性能问题
- 在重要游戏中使用之前彻底测试脚本
- 在使用修改游戏状态的脚本之前备份存档文件
限制
- Lua 脚本在模拟器的主线程中运行（可能影响性能）
- 某些操作可能根据模拟器状态而不可用
- 内存地址可能因游戏版本或地区而异
相关文章
有关 mGBA 配置和开发的更多信息：