Scripting API

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 : string, temporary : 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 : string, flags : s32 = 29): bool: Load state from a buffer. See C.SAVESTATE for possible values for flags
loadStateFile(path : string, flags : s32 = 29): bool: Load state from the given path. See C.SAVESTATE for possible values for flags
loadStateSlot(slot : s32, flags : 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 : u32, length : 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 : string, flags : s32 = 31): bool: Save state to the given path. See C.SAVESTATE for possible values for flags
saveStateSlot(slot : s32, flags : 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 : u32, value : u16): Write a 16-bit value from the given bus address
write32(address : u32, value : u32): Write a 32-bit value from the given bus address
write8(address : u32, value : u8): Write an 8-bit value from the given bus address
writeRegister(regName : string, value : 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 : string, function : 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 : u32, length : u32): string: Read byte range from the given offset
size(): u32: Get the size of this memory domain in bytes
write16(address : u32, value : u16): Write a 16-bit value from the given offset
write32(address : u32, value : u32): Write a 32-bit value from the given offset
write8(address : u32, value : 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 : u32, y : 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 : u32, rows : 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 : string, port : 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 : string, port : 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 : string, callback : 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 : string, port : u16): s32

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

connect(address : string, port : 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 : string, i : s64 = 0, j : 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

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	Width	Alias
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	4	ip
sp	4	r13
lr	4	r14
pc	4	r15
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