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

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 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