Starting with version 0.10, mGBA has built-in scripting capabilities. To use the scripting capabilities, click on the “Scripting…” item from the Tools menu. Currently, only Lua scripting is supported.

Most of the following documentation is automatically generated from version 0.10-7701-9adad40b1.

Top-level objects

By default, the following objects are available at the top level. When a game is loaded, the additional emu object is also available, and is an instance of CoreAdapter.

C

A table containing the exported constants

callbacks

Singleton instance of CallbackManager

console

Singleton instance of Console

util

Basic utility library

Functions

expandBitmask(mask : u64): list

Expand a bitmask into a list of bit indices

makeBitmask(bits : list): u64

Compile a list of bit indices into a bitmask

Classes

Core

An instance of an emulator core.

Methods

addKey(key : s32)

Add a single key to the currently active key list

addKeys(keys : u32)

Add a bitmask of keys to the currently active key list

autoloadSave(): bool

Load the save data associated with the currently loaded ROM file

checksum(type : s32 = 0): string

Get the checksum of the loaded ROM

clearKey(key : s32)

Remove a single key from the currently active key list

clearKeys(keys : u32)

Remove a bitmask of keys from the currently active key list

currentFrame(): u32

Get the number of the current frame

frameCycles(): s32

Get the number of cycles per frame

frequency(): s32

Get the number of cycles per second

getGameCode(): string

Get internal product code for the game from the ROM header, if available

getGameTitle(): string

Get internal title of the game from the ROM header

getKey(key : s32): s32

Get the active state of a given key

getKeys(): u32

Get the currently active keys as a bitmask

loadFile(path : string): bool

Load a ROM file into the current state of this core

loadSaveFile(path : stringtemporary : bool): bool

Load save data from the given path. If the temporary flag is set, the given save data will not be written back to disk

loadStateBuffer(buffer : stringflags : s32 = 29): bool

Load state from a buffer. See C.SAVESTATE for possible values for flags

loadStateFile(path : stringflags : s32 = 29): bool

Load state from the given path. See C.SAVESTATE for possible values for flags

loadStateSlot(slot : s32flags : s32 = 29): bool

Load state from the slot number. See C.SAVESTATE for possible values for flags

platform(): s32

Get which platform is being emulated. See C.PLATFORM for possible values

read16(address : u32): u32

Read a 16-bit value from the given bus address

read32(address : u32): u32

Read a 32-bit value from the given bus address

read8(address : u32): u32

Read an 8-bit value from the given bus address

readRange(address : u32length : u32): string

Read byte range from the given offset

readRegister(regName : string): string

Read the value of the register with the given name

reset()

Reset the emulation. This does not invoke the reset callback

romSize(): s64

Get the size of the loaded ROM

runFrame()

Run until the next frame

saveStateBuffer(flags : s32 = 31): string

Save state and return as a buffer. See C.SAVESTATE for possible values for flags

saveStateFile(path : stringflags : s32 = 31): bool

Save state to the given path. See C.SAVESTATE for possible values for flags

saveStateSlot(slot : s32flags : s32 = 31): bool

Save state to the slot number. See C.SAVESTATE for possible values for flags

screenshot(filename : string = nil)

Save a screenshot

setKeys(keys : u32)

Set the currently active key list

step()

Run a single instruction

write16(address : u32value : u16)

Write a 16-bit value from the given bus address

write32(address : u32value : u32)

Write a 32-bit value from the given bus address

write8(address : u32value : u8)

Write an 8-bit value from the given bus address

writeRegister(regName : stringvalue : s32)

Write the value of the register with the given name

CallbackManager

A global singleton object callbacks used for managing callbacks. The following callbacks are defined:

  • alarm: An in-game alarm went off
  • crashed: The emulation crashed
  • frame: The emulation finished a frame
  • keysRead: The emulation is about to read the key input
  • reset: The emulation has been reset
  • savedataUpdated: The emulation has just finished modifying save data
  • sleep: The emulation has used the sleep feature to enter a low-power mode
  • shutdown: The emulation has been powered off
  • start: The emulation has started
  • stop: The emulation has voluntarily shut down

Methods

add(callback : stringfunction : wrapper): u32

Add a callback of the named type. The returned id can be used to remove it later

remove(cbid : u32)

Remove a callback with the previously retuned id

Console

A global singleton object console that can be used for presenting textual information to the user via a console.

Methods

createBuffer(name : string = nil): TextBuffer

Create a text buffer that can be used to display custom information

error(msg : string)

Print an error to the console

log(msg : string)

Print a log to the console

warn(msg : string)

Print a warning to the console

CoreAdapter

A wrapper around a Core object that exposes more functionality. It can be implicity cast to a Core object, and exposes the same methods. Please see the documentation on Core for details on those methods.

Methods

reset()

Reset the emulation. As opposed to Core.reset, this version calls the reset callback

Members

memory : table

A table containing a platform-specific set of MemoryDomain objects

MemoryDomain

An object used for access directly to a memory domain, e.g. the cartridge, instead of through a whole address space, as with the functions directly on Core.

Methods

base(): u32

Get the address of the base of this memory domain

bound(): u32

Get the address of the end bound of this memory domain. Note that this address is not in the domain itself, and is the address of the first byte past it

name(): string

Get a short, human-readable name for this memory domain

read16(address : u32): u32

Read a 16-bit value from the given offset

read32(address : u32): u32

Read a 32-bit value from the given offset

read8(address : u32): u32

Read an 8-bit value from the given offset

readRange(address : u32length : u32): string

Read byte range from the given offset

size(): u32

Get the size of this memory domain in bytes

write16(address : u32value : u16)

Write a 16-bit value from the given offset

write32(address : u32value : u32)

Write a 32-bit value from the given offset

write8(address : u32value : u8)

Write an 8-bit value from the given offset

TextBuffer

An object that can be used to present texual data to the user. It is displayed monospaced, and text can be edited after sending by moving the cursor or clearing the buffer.

Methods

advance(adv : s32)

Advance the cursor a number of columns

clear()

Clear the buffer

cols(): u32

Get number of columns in the buffer

getX(): u32

Get the current x position of the cursor

getY(): u32

Get the current y position of the cursor

moveCursor(x : u32y : u32)

Set the position of the cursor

print(text : string)

Print a string to the buffer

rows(): u32

Get number of rows in the buffer

setName(name : string)

Set the user-visible name of this buffer

setSize(cols : u32rows : u32)

Set the number of rows and columns

Lua-specific features

These objects and classes are designed to be used exclusively with the Lua bindings to provide a more natural interface for the language.

Top-level objects

socket

A basic TCP socket library

Functions
bind(address : stringport : u16): lua::socket

Create and bind a new socket to a specific interface and port. Use nil for address to bind to all interfaces

connect(address : stringport : u16): lua::socket

Create and return a new TCP socket with a connection to the specified address and port.

Caution: This is a blocking call. The emulator will not respond until the connection either succeeds or fails

tcp(): lua::socket

Create a new TCP socket, for use with either lua::socket.bind or lua::socket.connect later

Members
ERRORS : table

Error strings corresponding to the C.SOCKERR error codes, indexed both by name and by value

Classes

socket

An instance of a TCP socket. Most of these functions will return two values if an error occurs; the first value is nil and the second value is an error string from socket.ERRORS

Methods
accept(): lua::socket

Creates a new socket for an incoming connection from a listening server socket

add(event : stringcallback : function): s64

Add a callback for a named event. The returned id can be used to remove it later. Events get checked once per frame but can be checked manually using lua::socket.poll. The following callbacks are defined:

  • received: New data has been received and can be read
  • error: An error has occurred on the socket
bind(address : stringport : u16): s32

Bind the socket to a specific interface and port. Use nil for address to bind to all interfaces

connect(address : stringport : u16): s32

Opens a TCP connection to the specified address and port.

Caution: This is a blocking call. The emulator will not respond until the connection either succeeds or fails

hasdata(): bool

Check if a socket has data ready to receive, and return true if so

listen(backlog : s32 = 1): s32

Begins listening for incoming connections. The socket must have first been bound with the lua::socket.bind function

poll()

Manually check for events on this socket and dispatch associated callbacks

receive(maxBytes : s64): string

Read up to maxBytes bytes from the socket and return them. If the socket has been disconnected or an error occurs, it will return nil, error instead

remove(cbid : s64)

Remove a callback with the previously returned id

send(data : stringi : s64 = 0j : s64 = 0): s32

Writes a string to the socket. If i and j are provided, they have the same semantics as the parameters to string.sub to write a substring. Returns the last index written

Constants

CHECKSUM

CRC32 0

GBA_KEY

A 0
B 1
SELECT 2
START 3
RIGHT 4
LEFT 5
UP 6
DOWN 7
R 8
L 9

GB_KEY

A 0
B 1
SELECT 2
START 3
RIGHT 4
LEFT 5
UP 6
DOWN 7

PLATFORM

NONE -1
GBA 0
GB 1

SAVESTATE

SCREENSHOT 1
SAVEDATA 2
CHEATS 4
RTC 8
METADATA 16
ALL 31

SOCKERR

UNKNOWN_ERROR -1
OK 0
AGAIN 1
ADDRESS_IN_USE 2
CONNECTION_REFUSED 3
DENIED 4
FAILED 5
NETWORK_UNREACHABLE 6
NOT_FOUND 7
NO_DATA 8
OUT_OF_MEMORY 9
TIMEOUT 10
UNSUPPORTED 11

Memory domains

GBA

Key Name Base
bios BIOS 0x00000000
wram EWRAM 0x02000000
iwram IWRAM 0x03000000
io MMIO 0x04000000
palette Palette 0x05000000
vram VRAM 0x06000000
oam OAM 0x07000000
cart0 ROM 0x08000000
cart1 ROM WS1 0x0a000000
cart2 ROM WS2 0x0c000000

GB

Key Name Base
cart0 ROM Bank $0000
vram VRAM $8000
sram SRAM $a000
wram WRAM $c000
oam OAM $fe00
io MMIO $ff00
hram HRAM $ff80

Registers

GBA

Name WidthAlias
r0 4
r1 4
r2 4
r3 4
r4 4
r5 4
r6 4
r7 4
r8 4
r9 4
r10 4
r11 4
r12 4ip
sp 4r13
lr 4r14
pc 4r15
cpsr 4

GB

Name Width
b 1
c 1
d 1
e 1
h 1
l 1
a 1
f 1
bc 2
de 2
hl 2
af 2
pc 2
sp 2