Scripting API

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

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

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 ⬨