Scripting API (development version)

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

canvas ⬨

Singleton instance of CanvasContext

console ⬨

Singleton instance of Console

image ⬨

Methods for creating Image and Painter instances

Functions ⬨

load(path : string): Image⬨

Load an image from a path. Currently, only PNG format is supported

new(width : u32, height : u32): Image⬨

Create a new image with the given dimensions

newPainter(image : Image): Painter⬨

Create a new painter from an existing image

input ⬨

Singleton instance of InputContext

storage ⬨

Singleton instance of StorageContext

system ⬨

Information about the system the script is running under

Members ⬨

branch : string ⬨

The current git branch of this build of the program, if known

commit : string ⬨

The current git commit hash of this build of the program, if known

program : string ⬨

The name of the program. Generally this will be “mGBA”, but forks may change it to differentiate

revision : s32 ⬨

The current git revision number of this build of the program, or -1 if unknown

version : string ⬨

The current version of this build of the program

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

newRectangle(x : s32, y : s32, width : s32, height : s32): Rectangle⬨

Create a new mRectangle

newSize(width : s32, height : s32): Size⬨

Create a new mSize

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): wrapper⬨

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 to a file

screenshotToImage(): Image⬨

Get a screenshot in an Image

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

Image ⬨

A single, static image.

Methods ⬨

drawImage(image : Image, x : u32, y : u32, alpha : f32 = 1)⬨

Draw another image onto this image with alpha blending as needed, optionally specifying a coefficient for adjusting the opacity

drawImageOpaque(image : Image, x : u32, y : u32)⬨

Draw another image onto this image without any alpha blending, overwriting what was already there

getPixel(x : u32, y : u32): u32⬨

Get the ARGB value of the pixel at a given coordinate

save(path : string, format : string = PNG): bool⬨

Save the image to a file. Currently, only PNG format is supported

setPixel(x : u32, y : u32, color : u32)⬨

Set the ARGB value of the pixel at a given coordinate

Members ⬨

height : readonly u32 ⬨

The height of the image, in pixels

width : readonly u32 ⬨

The width of the image, in pixels

Painter ⬨

A stateful object useful for performing drawing operations on an Image.

Methods ⬨

drawCircle(x : s32, y : s32, diameter : s32)⬨

Draw a circle with the specified diameter with the given origin at the top-left corner of the bounding box

drawLine(x1 : s32, y1 : s32, x2 : s32, y2 : s32)⬨

Draw a line with the specified endpoints

drawMask(mask : Image, x : s32, y : s32)⬨

Draw a mask image with each color channel multiplied by the current fill color. This can be useful for displaying graphics with dynamic colors. By making a grayscale template image on a transparent background in advance, a script can set the fill color to a desired target color and use this function to draw it into a destination image.

drawRectangle(x : s32, y : s32, width : s32, height : s32)⬨

Draw a rectangle with the specified dimensions

drawText(text : string, x : s32, y : s32, alignment : s32 = 17)⬨

Draw text with the currently set font and fill color

loadFont(path : string)⬨

Load a font from a given filename

setBlend(enable : bool)⬨

Set whether or not alpha blending should be enabled when drawing

setFill(enable : bool)⬨

Set whether or not the fill color should be applied when drawing

setFillColor(color : u32)⬨

Set the fill color to be used when drawing

setFontSize(pt : f32)⬨

Set the font size

setStrokeColor(color : u32)⬨

Set the stroke color to be used when drawing

setStrokeWidth(width : u32)⬨

Set the stroke width to be used when drawing, or 0 to disable

textBoxSize(text : string): Size⬨

Get the bounding box size for the given string rendered in the current font. This will take into account line breaks, unlike Painter.textRunMetrics.

textRunMetrics(text : string): TextRunMetrics⬨

Get the TextRunMetrics for the first line of a given string rendered in the current font. If you want the bounding box for multiple lines, use Painter.textBoxSize instead.

Rectangle ⬨

A basic axis-aligned rectangle object

Methods ⬨

center(other : Rectangle)⬨

Center another rectangle inside this one

copy(): Rectangle⬨

Create a copy of this Rectangle

intersection(other : Rectangle): bool⬨

Find the intersection of this and another rectangle. Returns false if the rectangles don’t intersect

size(): Size⬨

Return the size of this Rectangle as a Size object

union(other : Rectangle)⬨

Find the bounding box of the union of this and another rectangle

Members ⬨

height : s32 ⬨

The height of the rectangle

width : s32 ⬨

The width of the rectangle

x : s32 ⬨

The x coordinate of the top-left corner

y : s32 ⬨

The y coordinate of the top-left corner

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
• rumble: The state of the rumble motor was changed. This callback is passed a single argument that specifies if it was turned on (true) or off (false)
• 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

oneshot(callback : string, function : wrapper): u32⬨

Add a one-shot callback of the named type that will be automatically removed after called. The returned id can be used to remove it early

remove(cbid : u32)⬨

Remove a callback with the previously retuned id

CanvasContext ⬨

A canvas that can be used for drawing images on or around the screen.

Methods ⬨

height(): u32⬨

Get the height of the canvas

newLayer(width : s32, height : s32): CanvasLayer⬨

Create a new layer of a given size. If multiple layers overlap, the most recently created one takes priority.

screenHeight(): s32⬨

Get the height of the emulated screen

screenWidth(): s32⬨

Get the width of the emulated screen

update()⬨

Update all layers marked as having pending changes

width(): u32⬨

Get the width of the canvas

CanvasLayer ⬨

An individual layer of a drawable canvas.

Methods ⬨

setPosition(x : s32, y : s32)⬨

Set the position of the layer in the canvas

update()⬨

Mark the contents of the layer as needed to be repainted

Members ⬨

image : Image ⬨

The image that has the pixel contents of the image

x : readonly s32 ⬨

The current x (horizontal) position of this layer

y : readonly s32 ⬨

The current y (vertical) position of this layer

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 ⬨

clearBreakpoint(cbid : s64): bool⬨

Clear a breakpoint or watchpoint for a given id returned by a previous call

currentCycle(): u64⬨

Get the current execution cycle

reset()⬨

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

setBreakpoint(callback : wrapper, address : u32, segment : s32 = -1): s64⬨

Set a breakpoint at a given address

setRangeWatchpoint(callback : wrapper, minAddress : u32, maxAddress : u32, type : s32, segment : s32 = -1): s64⬨

Set a watchpoint in a given range of a given type. Note that the range is exclusive on the end, as though you’ve added the size, i.e. a 4-byte watch would specify the maximum as the minimum address + 4

setRotationCallbacks(cbTable : table): table⬨

Sets the table of functions to be called when the game requests rotation data, for either a gyroscope or accelerometer. The following functions are supported, and if any isn’t set then then default implementation for that function is called instead:

• sample: Update (“sample”) the values returned by the other functions. The values returned shouldn’t change until the next time this is called
• readTiltX: Return a value between -1.0 and +1.0 representing the X (left/right axis) direction of the linear acceleration vector, as for an accelerometer.
• readTiltY: Return a value between -1.0 and +1.0 representing the Y (up/down axis) direction of the linear acceleration vector, as for an accelerometer.
• readGyroZ: Return a value between -1.0 and +1.0 representing the roll (front/back axis) value of the rotational acceleration vector, as for an gyroscope.

Optionally, you can also set a value context on the table that will be passed to the callbacks. This table is copied by value, so changes made to the table after being passed to this function will not be seen unless the function is called again. Therefore, the recommended usage of the context field is as an index or key into a separate table. Use cases may vary. If this function is called more than once, the previous value of the table is returned.

setSolarSensorCallback(callback : wrapper)⬨

Set a callback that will be used to get the current value of the solar sensors between 0 (darkest) and 255 (brightest). Note that the full range of values is not used by games, and the exact range depends on the calibration done by the game itself.

setWatchpoint(callback : wrapper, address : u32, type : s32, segment : s32 = -1): s64⬨

Set a watchpoint at a given address of a given type

Members ⬨

memory : table ⬨

A table containing a platform-specific set of MemoryDomain objects

Event ⬨

The base class for all event types. Different events have their own subclasses.

Members ⬨

seq : u64 ⬨

Sequence number of this event. This value increases monotinically.

type : s32 ⬨

The type of this event. See C.EV_TYPE for a list of possible types.

Gamepad ⬨

Members ⬨

axes : list ⬨

An indexed list of the current values of each axis

buttons : list ⬨

An indexed list of the current values of each button

hats : list ⬨

An indexed list of the current values of POV hat

internalName : string ⬨

The internal name of this gamepad, generally unique to the specific type of gamepad

visibleName : string ⬨

The human-readable name of this gamepad

GamepadButtonEvent ⬨

Inherits from Event

A gamepad button event.

Members ⬨

button : u16 ⬨

Which button this event pertains to. There is currently no guaranteed button mapping, and it might change between different controllers.

pad : u8 ⬨

Which gamepad this event pertains to. Currently, this will always be 0.

state : u8 ⬨

The state of the button, represented by a C.INPUT_STATE value

GamepadHatEvent ⬨

Inherits from Event

A gamepad POV hat event.

Members ⬨

direction : u8 ⬨

The current direction of the hat. See C.INPUT_DIR for possible values.

hat : u8 ⬨

Which hat this event pertains to. For most gamepads this will be 0.

pad : u8 ⬨

Which gamepad this event pertains to. Currently, this will always be 0.

InputContext ⬨

Methods ⬨

activeKeys(): list⬨

Get a list of the currently active keys. The values are Unicode codepoints or special key values from C.KEY, not strings, so make sure to convert as needed

isKeyActive⬨(key : string): bool(key : u32): bool

Check if a given keyboard key is currently held. The input can be either the printable character for a key, the numerical Unicode codepoint, or a special value from C.KEY

Members ⬨

activeGamepad : Gamepad ⬨

The currently active gamepad, if any

seq : u64 ⬨

Sequence number of the next event to be emitted

KeyEvent ⬨

Inherits from Event

A keyboard key event.

Members ⬨

key : s32 ⬨

The relevant key for this event. For most printable characters, this will be the Unicode codepoint of the character. Some special values are present as C.KEY as well.

modifiers : s16 ⬨

A bitmask of current modifiers, represented by ORed C.KMOD values

state : u8 ⬨

The state of the key, represented by a C.INPUT_STATE value

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

MouseButtonEvent ⬨

Inherits from Event

A mouse button event.

Members ⬨

button : u8 ⬨

Which mouse button this event pertains to. Symbolic names for primary (usually left), secondary (usually right), and middle are in C.MOUSE_BUTTON, and further buttons are numeric starting from 3.

mouse : u8 ⬨

Which mouse this event pertains to. Currently, this will always be 0.

state : u8 ⬨

The state of the button, represented by a C.INPUT_STATE value

MouseMoveEvent ⬨

Inherits from Event

A mouse movement event.

Members ⬨

mouse : u8 ⬨

Which mouse this event pertains to. Currently, this will always be 0.

x : s32 ⬨

The x coordinate of the mouse in the context of game screen pixels. This can be out of bounds of the game screen depending on the size of the window in question.

y : s32 ⬨

The y coordinate of the mouse in the context of game screen pixels. This can be out of bounds of the game screen depending on the size of the window in question.

Painter ⬨

StorageBucket ⬨

A single ‘bucket’ of stored data, appropriate for a single script to store its data. Fields can be set directly on the bucket objct, e.g. if you want to store a value called foo on a bucket named bucket, you can directly assign to it as bucket.foo = value, and retrieve it in the same way later. Primitive types (numbers, strings, lists and tables) can be stored in buckets, but complex data types (e.g. a bucket itself) cannot. Data stored in a bucket is periodically flushed to disk and persists between sessions.

Methods ⬨

enableAutoFlush(enable : bool)⬨

Enable or disable the automatic flushing of this bucket. This is good for ensuring buckets don’t get flushed in an inconsistent state. It will also disable flushing to disk when the emulator is shut down, so make sure to either manually flush the bucket or re-enable automatic flushing whenever you’re done updating it if you do disable it prior.

flush(): bool⬨

Flush the bucket to disk manually

reload(): bool⬨

Reload the state of the bucket from disk

StorageContext ⬨

Methods ⬨

flushAll()⬨

Flush all buckets to disk manually

getBucket(key : string): StorageBucket⬨

Get a bucket with the given name. Names can contain letters, numbers, underscores and periods. If a given bucket doesn’t exist, it is created.

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

Size ⬨

A basic size (width/height) object

Methods ⬨

copy(): Size⬨

Create a copy of this Size

Members ⬨

height : s32 ⬨

The height

width : s32 ⬨

The width

TextRunMetrics ⬨

Metrics for the size of a run of text. Generally, a run will represent up to a single line of text.

Methods ⬨

ascender(): f32⬨

Get the distance from the baseline to the top of the line, in pixels

descender(): f32⬨

Get the distance from the baseline to the bottom of the line, in pixels

height(): f32⬨

Get the height of the run of text, in pixels

width(): f32⬨

Get the width of the run of text, in pixels

Top-level objects ⬨

script ⬨

Information about the currently loaded script

Members ⬨

dir : string ⬨

The path to the directory containing the script

path : string ⬨

The path of the current script file

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 ⬨