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-7562-0b2cfb505-dirty.
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
- 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
- loadStateBuffer(buffer : string, flags : s32 = 29): s32
-
Load state a buffer. See C.SAVESTATE for possible values for
flags
- loadStateSlot(slot : s32, flags : s32 = 29): s32
-
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
- 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
- saveStateSlot(slot : s32, flags : s32 = 31): s32
-
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 posiiton 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
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 |
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 |