Lua Scripting API

mGBA includes full Lua 5.4 scripting support, allowing you to create custom tools, trainers, automation scripts, and game modifications. This documentation provides a complete reference for the Lua scripting API.

Getting Started with Lua Scripting

Loading Scripts

To load a Lua script in mGBA:

1. Go to Tools → Scripting → Load Script
2. Navigate to your Lua script file (.lua format)
3. Select the script file and click Open
4. The script will be loaded and executed automatically

Memory Access Functions

-- Example: Read 8-bit value from memory
value = mGBA:read8(0x02000000)
print("Value at 0x02000000: " .. value)

-- Example: Read 16-bit value
value = mGBA:read16(0x02000000)
print("16-bit value: " .. value)

-- Example: Read 32-bit value
value = mGBA:read32(0x02000000)
print("32-bit value: " .. value)

-- Example: Write 8-bit value
mGBA:write8(0x02000000, 0xFF)

CPU and Register Functions

-- Example: Get PC (Program Counter) value
pc = mGBA:getRegister("pc")
print("Program Counter: " .. string.format("0x%08X", pc))

Frame and Timing Functions

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

-- Example: Reset emulator
mGBA:reset()

Save State Functions

Input Functions

-- Example: Press A button
mGBA:pressButton("A")

Event Callbacks

mGBA Lua API supports event callbacks for game state changes:

-- Example: Frame callback
function onFrame()
    -- This function is called every frame
    local frame = mGBA:frame()
    if frame % 60 == 0 then
        print("Frame: " .. frame)
    end
end

-- Register callback
mGBA:onFrame(onFrame)

Common Script Examples

Health Trainer

-- Health trainer example
local healthAddress = 0x02000000  -- Replace with actual address

function infiniteHealth()
    mGBA:write16(healthAddress, 999)
end

-- Run every frame
mGBA:onFrame(infiniteHealth)

Frame Counter

-- Frame counter script
local startFrame = mGBA:frame()

function countFrames()
    local current = mGBA:frame()
    local elapsed = current - startFrame
    print("Elapsed frames: " .. elapsed)
end

mGBA:onFrame(countFrames)

Memory Addresses

Common memory addresses for Game Boy Advance games:

• Internal WRAM: 0x03000000 - 0x03007FFF (32KB)
• External WRAM: 0x02000000 - 0x0203FFFF (256KB)
• Video RAM: 0x06000000 - 0x06017FFF (96KB)
• Game Pak ROM: 0x08000000 - 0x0DFFFFFF (varies by game)
• Game Pak SRAM: 0x0E000000 - 0x0E00FFFF (varies by game)

Best Practices

• Always validate memory addresses before reading/writing
• Use appropriate data types (8-bit, 16-bit, 32-bit) for memory operations
• Be careful with frame callbacks to avoid performance issues
• Test scripts thoroughly before using in important gameplay
• Backup save files before using scripts that modify game state

Limitations

• Lua scripts run in the emulator's main thread (may affect performance)
• Some operations may not be available depending on emulator state
• Memory addresses may change between game versions or regions

Related Articles

For more information about mGBA configuration and development:

• Configuration API Reference - Programmatic configuration options and settings management
• Advanced Configuration Guide - Deep dive into advanced settings and optimization techniques
• Architecture Overview - Understanding mGBA's codebase structure and design principles
• Getting Started Guide - Installation and basic setup instructions