This page documents various lua functions in lsnes.
Unless otherwise noted, functions are in rr1 version and work anywhere.
Table of contents
- Bit manipulation functions
- GUI functions
- (Color notation)
- (Coordinate system)
- (Draw order)
- (Valid in)
- gui.screenshot
- gui.circle
- gui.resolution
- gui.left_gap / gui.top_gap / gui.right_gap / gui.bottom_gap
- gui.repaint
- gui.subframe_update
- gui.color
- gui.status
- gui.crosshair
- gui.line
- gui.pixel
- gui.rectangle
- gui.box
- gui.text / gui.textH / gui.textV / gui.textHV
- gui.bitmap_draw
- gui.palette_new
- gui.palette_set
- gui.bitmap_new
- gui.bitmap_pset
- gui.bitmap_size
- gui.bitmap_blit
- gui.bitmap_load
- gui.rainbow
- Hostmemory functions
- (Generic)
- hostmemory.read / hostmemory.readbyte / hostmemory.readword / hostmemory.readdword / hostmemory.readqword
- hostmemory.readsbyte / hostmemory.readsword / hostmemory.readsdword / hostmemory.readsqword
- hostmemory.write / hostmemory.writebyte / hostmemory.writeword / hostmemory.writedword / hostmemory.writeqword
- Input functions
- Memory functions
- (Generic)
- memory.read / memory.readbyte / memory.readword / memory.readdword / memory.readqword
- memory.readsbyte / memory.readsword / memory.readsdword / memory.readsqword
- memory.write / memory.writebyte / memory.writeword / memory.writedword / memory.writeqword
- memory.mapbyte / memory.mapsbyte / memory.mapword / memory.mapsword / memory.mapdword / memory.mapsdword / memory.mapqword / memory.mapsqword
- memory.map_structure()
- memory.vma_count
- memory.read_vma
- memory.find_vma
- memory.hash_state
- memory.hash_region
- memory.readregion
- memory.writeregion
- Movie functions
- Settings functions
- Misc. functions
- Callbacks
Bit manipulation functions
(Generic remarks)
Bit manipulation functions work on 48-bit numbers and return 48-bit results. Negative numbers are interpreted as two's complement.
bit.none / bit.bnot
Syntax: Number bit.none(Number n...)
Syntax: Number bit.bnot(Number n...)
Returns number that has bit i set exactly when none of the arguments has the bit i set.
When called with one argument, this is the same as the bitwise NOT.
bit.any / bit.bor
Syntax: Number bit.any(Number n...)
Syntax: Number bit.bor(Number n...)
Returns number that has bit i set exactly when any of the arguments has the bit i set.
If called with two arguments, this is the same as bitwise OR.
bit.all / bit.band
Syntax: Number bit.all(Number n...)
Syntax: Number bit.band(Number n...)
Returns number that has bit i set exactly when all of the arguments have the bit i set.
If called with two arguments, this is the same as bitwise AND.
bit.parity
Syntax: Number bit.parity(Number n...)
Syntax: Number bit.bxor(Number n...)
Returns number that has bit i set exactly when odd number of the arguments has the bit i set.
If called with two arguments, this is the same as bitwise XOR.
bit.lrotate
Syntax: Number bit.lrotate(Number base, [Number nplaces], [Number nbits])
- If nplaces is not specified, defaults to 1.
- If nbits is not specified, defaults to 48.
Returns base, assumed to be nbits bits, rotated left by nplaces places.
Behavior is undefined if nbits is greater than 48 or if nplaces is greater than 47.
bit.rrotate
Syntax: Number bit.rrotate(Number base, [Number nplaces], [Number nbits])
- If nplaces is not specified, defaults to 1.
- If nbits is not specified, defaults to 48.
Returns base, assumed to be nbits bits, rotated right by nplaces places.
Behavior is undefined if nbits is greater than 48 or if nplaces is greater than 47.
bit.lshift
Syntax: Number bit.lshift(Number base, [Number nplaces], [Number nbits])
- If nplaces is not specified, defaults to 1.
- If nbits is not specified, defaults to 48.
Returns base, assumed to be nbits bits, shifted left by nplaces places.
The bits that leave nbits least significant bits are discarded. The shifted in bits are zeroes.
Behavior is undefined if nbits is greater than 48 or if nplaces is greater than 47.
bit.lrshift
Syntax: Number bit.lrshift(Number base, [Number nplaces], [Number nbits])
- If nplaces is not specified, defaults to 1.
- If nbits is not specified, defaults to 48.
Returns base, assumed to be nbits bits, shifted logically right by nplaces places.
The bits that drop off the right end are discarded. The shifted in bits are zeroes.
Behavior is undefined if nbits is greater than 48 or if nplaces is greater than 47.
bit.arshift
Syntax: Number bit.arshift(Number base, [Number nplaces], [Number nbits])
- If nplaces is not specified, defaults to 1.
- If nbits is not specified, defaults to 48.
Returns base, assumed to be nbits bits, shifted arithmetically right by nplaces places.
The bits that drop off the right end are discarded. The shifted in bits are copies of the most significant bit.
Behavior is undefined if nbits is greater than 48 or if nplaces is greater than 47.
bit.extract
Syntax: Number bit.extract(Number base, Number/Boolean place...)
- Since rr1-Δ5
Returns a number where ith bit is taken from the ith placeth bit of base.
As special case, if ith place is boolean, the ith returned bit is that value (1 if argument was true, 0 if false).
bit.value
Syntax: Number bit.value(Number/nil place...)
- Since rr1-Δ5
Returns number that has all placeth bits set.
As special case, any nil arguments are ignored.
bit.test_any
Syntax: Boolean bit.test_any(Number a, Number b)
- Since rr1-Δ16 / rr2-β2
Returns true if a and b have common set bit or bits.
bit.test_all
Syntax: Boolean bit.test_all(Number a, Number b)
- Since rr1-Δ16 / rr2-β2
Returns true if a has all the bits set in b set.
bit.popcount
Syntax: Number bit.popcount(Number a)
- Since rr1-Δ16 / rr2-β2
Returns population count (number of set bits) of a.
bit.clshift
Syntax: Number,Number bit.clshift(Number a, Number b, [Number places], [Number bits])
- Since rr1-Δ16 / rr2-β2
Chained shift of a and b left by specified number of places (default 1). The numbers are treated as having specified number of bits (default 48).
bit.crshift
Syntax: Number,Number bit.crshift(Number a, Number b, [Number places], [Number bits])
- Since rr1-Δ16 / rr2-β2
Chained shift of a and b right by specified number of places (default 1). The numbers are treated as having specified number of bits (default 48).
bit.flagdecode
Syntax: String bit.flagdecode(Number a, Number bits, [String set], [String clear])
- Since rr1-Δ16 / rr2-β2
Returns string where ith character is ith character (only character or '*') of set if corresponding bit is set, otherwise corresponding character of clear.
bit.rflagdecode
Syntax: String bit.rflagdecode(Number a, Number bits, [String set], [String clear])
- Since rr1-Δ16 / rr2-β2
Same as bit.flagdecode, but reverses the output string.
GUI functions
(Color notation)
- -1 is fully transparent.
- 16777216 * a + 65536 * r + 256 * g + b for other colors, where a is transparency.
- * The range of r, g and b and a is 0-255.
- * Alpha 0 is fully opaque, alpha 256 is fully transparent.
- * The a of this notation only goes to 255, despite there being alpha 256.
(Coordinate system)
- Origin is at top left of the game area.
- Positive directions are right and down.
- Left gap and top gap have negative coordinates.
(Draw order)
- The primitives are drawn in order they are specified.
- Gap settings always overtake everything else.
(Valid in)
- These primitives (unless otherwise noted) are only valid in callbacks on_paint and on_video.
- If called in on_paint, the screen is affected.
- If called in on_video, the dumped video is affected.
gui.screenshot
Syntax: none gui.screenshot(string filename)
- Valid anywhere.
Take a screenshot in PNG format and save it to filename
gui.circle
Syntax: none gui.circle(Number x, Number y, Number r, [Number thickness], [Number outline_color], [Number fill_color])
- thickness defaults to 1
- outline_color defaults to white
- fill_color defaults to transparent
Draws a circle centered at (x,y) with radius r.
The outline is of thickness thickness and is drawn using color specified by outline_color
The interior region is filled with color fill_color.
gui.resolution
Syntax (number width, number height) gui.resolution()
Returns the width (width) and height (height) of game area.
gui.left_gap / gui.top_gap / gui.right_gap / gui.bottom_gap
Syntax none gui.left_gap(number pixels)
Syntax none gui.top_gap(number pixels)
Syntax none gui.right_gap(number pixels)
Syntax none gui.bottom_gap(number pixels)
Sets the width of drawable blank area to the left/top/right/bottom of the game area to pixels.
gui.repaint
Syntax: none gui.repaint()
- Valid anywhere.
Arranges on_paint hook to be called as soon as possible.
gui.subframe_update
Syntax: none gui.subframe_update(boolean enabled)
- Valid anywhere
Enables (enabled=true)/Disables (enabled=false) calling of on_paint on every subframe (as opposed to just when new frame is available).
gui.color
Syntax: Number gui.color(Number r, Number g, Number b, [Number a])
- Valid anywhere.
- a defaults to 0 if not specified.
Returns the color code for color (r,g,b) (0-255 each channel) with alpha of a (0-256).
gui.status
Syntax: none gui.status(String name, String value)
- Valid anywhere
Set status name to value value.
If value is "", the status name is erased.
gui.crosshair
Syntax: none gui.crosshair(Number x, Number y, Number size, [Number color])
- color defaults to white.
Draws a crosshair of size size at (x,y) using color color.
gui.line
Syntax: none gui.color(Number x1, Number y1, Number x2, Number y2, [Number color])
- color defaults to white.
Draws a line from (x1,y1) to (x2,y2) using color color.
gui.pixel
Syntax: none gui.pixel(Number x, Number y, [Number color])
- color defaults to white.
Draws pixel at (x,y) using color color.
Be careful with this function. Even if it is the lightest of all draw functions, lots of draw functions don't do any good to performance.
gui.rectangle
Syntax: none gui.rectangle(Number x, Number y, Number w, Number h, [Number thickness], [Number outline_color], [Number fill_color])
- tickness defaults to 1.
- outline_color defaults to white.
- fill_color defaults to transparent.
Draws rectangle of size (w,h) with top-left corner at (x,y). Outline is of thickness thickness and is colored with color outline_color.
The interior is filled with color fill_color.
gui.box
Syntax: none gui.box(Number x, Number y, Number w, Number h, [Number thickness], [Number hilight_color], [Number shadow_color], [Number fill_color])
- Since rr1-Δ6
- thickness defaults to 1.
- hilight_color defaults to white.
- shadow_color defaults to dark gray.
- fill_color defaults to gray.
Draws rectangle of size (w,h) with top-left corner at (x,y).
The outline is of thickness thickness and is colored with hilight_color/shadow_color to create a 3D effect.
The interior is filled with fill_color.
gui.text / gui.textH / gui.textV / gui.textHV
Syntax: none gui.text(Number x, Number y, String text, [Number fgcolor], [Number bgcolor])
Syntax: none gui.textH(Number x, Number y, String text, [Number fgcolor], [Number bgcolor])
Syntax: none gui.textV(Number x, Number y, String text, [Number fgcolor], [Number bgcolor])
Syntax: none gui.textHV(Number x, Number y, String text, [Number fgcolor], [Number bgcolor])
- fgcolor defaults to white.
- bgcolor defaults to transparent.
Draws text string text starting from (x, y).
The text will be colored using color fgcolor and the text background is colored using bgcolor.
The
H
variants will draw the text using double width, and the V
variants will draw the text using double height.
gui.bitmap_draw
Syntax: none gui.bitmap_draw(Number x, Number y, BITMAP bmp, PALETTE pal)
Syntax: none gui.bitmap_draw(Number x, Number y, DBITMAP bmp)
- Since rr1-Δ4.
Render bitmap bmp with upper-left corner at (x,y).
If the bitmap is indexed, it will be rendered using palette pal.
gui.palette_new
Syntax: PALETTE gui.palette_new()
- Since rr1-Δ4.
- Can be used anywhere.
Returns a new PALETTE object. All colors are initialized to transparent.
gui.palette_set
Syntax: none gui.palette_set(PALETTE pal, number idx, number color)
- Since rr1-Δ4.
- Can be used anywhere.
Sets the color index idx in palette pal to color color.
gui.bitmap_new
Syntax: BITMAP gui.bitmap_new(number width, number height, false)
Syntax: DBITMAP gui.bitmap_new(number width, number height, true)
- Since rr1-Δ4.
- Can be used anywhere.
Returns a new bitmap of size width by height.
The third argument determines if the bitmap is indexed (false) or not (true).
gui.bitmap_pset
Syntax: none gui.bitmap_pset(BITMAP/DBITMAP bmp, number x, number y, number c)
- Since rr1-Δ4.
- Can be used anywhere.
Sets the pixel at (x,y) in bitmap bmp to color c.
The c is color index for indexed bitmaps and color for non-indexed ones.
gui.bitmap_size
Syntax: (Number w, Number h) gui.bitmap_size(BITMAP/DBITMAP bmp)
- Since rr1-Δ4.
- Can be used anywhere.
Returns the width (w) and height (h) of bitmap bmp.
gui.bitmap_blit
Syntax: none gui.bitmap_blit(BITMAP target, number dx, number dy, BITMAP source, number sx, number sy, number w, number h, [number colorkey])
Syntax: none gui.bitmap_blit(DBITMAP target, number dx, number dy, DBITMAP source, number sx, number sy, number w, number h, [number colorkey])
- Since rr1-Δ4.
- Can be used anywhere.
- colorkey defaults to NONE.
Blits region of size w by h starting from (sx,sy) from source to region starting from (dx,dy) in target.
If colorkey is specified, the pixels with that color are not blitted.
Note that this copies pixels, not composites those. This matters when copying (partially) transparent regions.
gui.bitmap_load
Syntax: BITMAP/DBITMAP gui.bitmap_load(string filename)
- Since rr1-Δ4.
- Can be used anywhere
Loads BITMAP or DBITMAP from file filename and returns the result.
If the result is indexed or not depends on the file.
gui.rainbow
Syntax: Number gui.rainbow(Number step, Number steps, Number base)
- Since rr1-Δ6.
- Can be used anywhere
Performs hue rotation on color base.
The rotation is step/steps of full hue circle. The positive direction is red->yellow->green->cyan->blue->magenta->red.
The rotation will preserve saturation, value and opacity.
Hostmemory functions
(Generic)
These read/write memory space that is preserved over saves and loads.
All functions use little-endian byte order.
The data types are:
- byte (unspecified is byte) is 8 bits.
- word is 16 bits.
- dword is 32 bits.
- qword is 64 bits.
hostmemory.read / hostmemory.readbyte / hostmemory.readword / hostmemory.readdword / hostmemory.readqword
Syntax: Number hostmemory.read(Number address)
Syntax: Number hostmemory.readbyte(Number address)
Syntax: Number hostmemory.readword(Number address)
Syntax: Number hostmemory.readdword(Number address)
Syntax: Number hostmemory.readqword(Number address)
Returns the unsigned value read from address address (or false if out of bounds).
hostmemory.readsbyte / hostmemory.readsword / hostmemory.readsdword / hostmemory.readsqword
Syntax: Number hostmemory.readsbyte(Number address)
Syntax: Number hostmemory.readsword(Number address)
Syntax: Number hostmemory.readsdword(Number address)
Syntax: Number hostmemory.readsqword(Number address)
Returns the signed (two's complement) value read from address address (or false if out of bounds).
hostmemory.write / hostmemory.writebyte / hostmemory.writeword / hostmemory.writedword / hostmemory.writeqword
Syntax: Number hostmemory.write(Number address, Number value)
Syntax: Number hostmemory.writebyte(Number address, Number value)
Syntax: Number hostmemory.writeword(Number address, Number value)
Syntax: Number hostmemory.writedword(Number address, Number value)
Syntax: Number hostmemory.writeqword(Number address, Number value)
Writes the value value (two's complement if negative) to address address (extending memory if out of bounds).
Input functions
(Generic)
Unless otherwise noted, these are only valid in on_input callback.
Physical controllers 0-3 are on port #1 and controllers 4-7 are on port #2.
The control indices are:
Index | SNES gamepad | GB(C) gamepad | mouse | justifier | superscope |
0 | B | A | xaxis | xaxis | xaxis |
1 | Y | B | yaxis | yaxis | yaxis |
2 | select | select | L | trigger | trigger |
3 | start | start | R | start | cursor |
4 | up | right | - | - | turbo |
5 | down | left | - | - | pause |
6 | left | up | - | - | - |
7 | right | down | - | - | - |
8 | A | - | - | - | - |
9 | X | - | - | - | - |
10 | L | - | - | - | - |
11 | R | - | - | - | - |
input.set
Syntax: none input.set(number controller, number index, number value)
- This function does nothing in read-only mode.
Set input on physical controller controller control index index to value value.
In case of buttons, zero is released, anything else is pressed.
input.get
Syntax: number input.get(number controller, number index)
Returns the value of physical controller controller input index index.
input.reset
Syntax: none input.reset([number delay])
- Only valid in on_input callback with subframe flag clear.
- delay defaults to 0.
- Nonzero delay since rr1-Δ8.
- This function does nothing in read-only mode.
Resets console. If delay is specified and delayed reset is supported, the reset will be delayed by that amount (but still at most one frame).
input.raw
Syntax: table input.raw()
- Can be used anywhere.
Returns a table of tables. The outer table is indexed by key name.
The inner table has the following fields:
- last_value: Raw value of input.
* For keys, this is 0 for released, 1 for pressed. * For mouse, this is coordinate relative to top left of draw area (note that this may be negative!). * For axis types, this is raw value of axis. * For hats, 1 is up, 2 is right, 4 is down, 8 is left. Diagonals are OR of primary directions.
- cal_left: Left/Top calibration limit.
- cal_center: Center calibration value.
- cal_right: Right/Bottom calibration limit.
- cal_tolerance: Tolerance of button (the width of dead zone, 0<x<1).
- ktype: The type of the key.
* disabled: Disabled axis. * key: Key * axis: Axis * axis-inverse: Axis (inverted). * hat: Hat * mouse: Mouse axis. * pressure-mp: Pressure-sensitive button, reads cal_left when released, cal_right when pressed. * pressure-m0: Pressure-sensitive button, reads cal_left when released, cal_center when pressed. * pressure-0m: Pressure-sensitive button, reads cal_center when released, cal_left when pressed. * pressure-0p: Pressure-sensitive button, reads cal_center when released, cal_right when pressed. * pressure-pm: Pressure-sensitive button, reads cal_right when released, cal_left when pressed. * pressure-p0: Pressure-sensitive button, reads cal_right when released, cal_center when pressed.
For mouse axes, cal_left is top/left edge of draw area, cal_center is top/left edge of game area, and cal_right is bottom/right edge of draw area.
input.keyhook
Syntax: none input.keyhook(string key, boolean enabled)
- Can be used anywhere.
If enabled=true, requests on_keyhook callback to happen when key key changes state.
If enabled=false, requests that state changes on key key do not cause callbacks to on_keyhook.
input.geta
Syntax: Tuple input.geta(Number controller)
- Since rr1-Δ5
Get all input indices of physical controller controller at once. The returned tuple is in control index order.
input.seta
Syntax: none input.seta(Number controller, Number values...)
- Since rr1-Δ5
Set all input indices of physical controller controller at once. The values are in control index order.
input.joyget
Syntax: table input.joyget(Number controller)
- Since rr1-Δ15
Returns a table, indexes by control name containing state of logical controller controller.
input.joyset
Syntax: none input.joyset(Number controller, table state)
- Since rr1-Δ14ε1
Set state of logical controller controller to state. The state is indexed by control name.
For buttons, nil/false is released, anything else is pressed (normal lua boolean rules).
Memory functions
(Generic)
These functions read/write console memory space.
The byte order used depends on the target address. Normally it is little-endian, but DSP memory is host-endian.
The data types are:
- byte (unspecified is byte) is 8 bits.
- word is 16 bits.
- dword is 32 bits.
- qword is 64 bits.
memory.read / memory.readbyte / memory.readword / memory.readdword / memory.readqword
Syntax: Number memory.read(Number address)
Syntax: Number memory.readbyte(Number address)
Syntax: Number memory.readword(Number address)
Syntax: Number memory.readdword(Number address)
Syntax: Number memory.readqword(Number address)
Returns the unsigned value read from address address (out of bounds bytes read as zeroes).
memory.readsbyte / memory.readsword / memory.readsdword / memory.readsqword
Syntax: Number memory.readsbyte(Number address)
Syntax: Number memory.readsword(Number address)
Syntax: Number memory.readsdword(Number address)
Syntax: Number memory.readsqword(Number address)
Returns the signed (two's complement) value read from address address (out of bounds bytes read as zeroes).
memory.write / memory.writebyte / memory.writeword / memory.writedword / memory.writeqword
Syntax: None memory.write(Number address, Number value)
Syntax: None memory.writebyte(Number address, Number value)
Syntax: None memory.writeword(Number address, Number value)
Syntax: None memory.writedword(Number address, Number value)
Syntax: None memory.writeqword(Number address, Number value)
Writes the value value (two's complement if negative) to address address (writes out of bounds are ignored).
memory.mapbyte / memory.mapsbyte / memory.mapword / memory.mapsword / memory.mapdword / memory.mapsdword / memory.mapqword / memory.mapsqword
Syntax: Table memory.map<type>()
Syntax: Table memory.map<type>(Number base, Number aperturesize)
- Since: rr1-Δ15ε2
Map area of size aperturesize starting from base (the entire map space if not specified) with specified type.
The returned table can be read/written to read/write console memory space.
The index values to this table are measured in bytes.
memory.map_structure()
Syntax: MAP_STRUCTURE memory.map_structure()
Syntax: none MAP_STRUCTURE(String field, Number address, String type)
Syntax: MAP_STRUCTURE:<field>
- Since: rr1-Δ15ε2
Returns an object that works like a structure that maps console memory variables as fields.
On call to object, the field field is mapped to memory address address (with type type, which can be "byte", "sbyte", "word", "sword", "dword", "sdword", "qword" or "sqword").
memory.vma_count
Syntax: number memory.vma_count()
Returns the number of VMAs active.
memory.read_vma
Syntax: Table/Nil memory.read_vma(Number vma)
Returns a table (Nil if index is out of range) about vmath VMA (zero-based).
The returned table has the following fields:
- region_name: Readable name of region
- baseaddr: Starting address of region.
- size: Size of region in bytes.
- lastaddr: Last address belonging to the region.
- readonly: True if VMA is read-only, false if VMA is writable.
- native_endian: True if VMA is native-endian, false if little-endian.
Invalid VMA index causes nil to be returned.
memory.find_vma
Syntax: Table/Nil memory.find_vma(Number address)
Return the information (the same table as returned by memory.read_vma) about the VMA where address address belongs to.
If the address address is not covered by any VMA, returns nil.
memory.hash_state
Syntax: String memory.hash_state()
Return hash (hexadecimal) of state of the entire system. Mainly useful for debugging core savestate code.
memory.hash_region
Syntax: String memory.hash_region(Number base, Number size)
- Since rr1-Δ8
Returns the SHA-256 hash (hexadecimal) of the contents of memory in region of size size starting from base.
memory.readregion
Syntax: Table memory.readregion(Number base, Number size)
- Since: rr1-Δ15ε2
Returns a table (zero-based) containing the byte values of memory region of size size starting from base.
Note that behavior is undefined if the specified range crosses a VMA boundary.
memory.writeregion
Syntax: None memory.writeregion(Number base, Number size, Table data)
- Since: rr1-Δ15ε2
Writes contents of tabe data (zero-based) as byte values to memory region of size size starting from base.
Note that behavior is undefined if the specified range crosses a VMA boundary.
Movie functions
movie.currentframe
Syntax: Number movie.currentframe()
Returns the current frame number.
movie.framecount
Syntax: Number movie.framecount()
Returns the number of frames in movie.
movie.readonly
Syntax: Boolean movie.readonly()
Returns true in readonly mode, otherwise false.
movie.readwrite
Syntax: none movie.readwrite()
Set readwrite mode.
Note: Does not trigger callback to on_readwrite.
movie.frame_subframes
Syntax: Number movie.frame_subframes(Number frame)
Returns the number of subframes in frame frame.
movie.read_subframes
Syntax: Table movie.read_subframes(Number frame, Number subframe)
Reads subframe subframe (0-based) of frame frame.
Return value is a table with numeric indices:
- 0: Frame sync flag.
- 1: Reset flag.
- 2: Delay field low (units of 0).
- 3: Delay field high (units of 10000)
- 4-99: Controller buttons/axes.
The index i of controller c is at table index 12 * c + i + 4.
Buttons/flags read as 0 (released, not set) or 1 (pressed, set).
movie.read_rtc
Syntax: (Number seconds, Number sseconds) movie.read_rtc()
Returns the current RTC time. seconds is in whole seconds (since 19700101T000000Z) and sseconds is subsecond ticks (32040.5*768 per second for SNES, 32768*64 per second for second for GB(C)) in second.
movie.unsafe_rewind
Syntax: none movie.unsafe_rewind() Syntax: none movie.unsafe_rewind(UNSAFEREWIND r)
- Since rr1-Δ9.
If called without parameters, triggers call to on_set_rewind with state.
If called with parameter r, rewinds to that state.
The state rewinded must be in past or the results are undefined.
movie.rerecords
Syntax: Number movie.rerecords()
- Since: rr1-Δ14.
Returns the current rerecord count.
Settings functions
(Generic)
On failure, the first return value is nil and the second is error message.
settings.set
Syntax: true settings.set(String name, String value)
Sets setting name to value value.
setting.get
Syntax: String/false settings.get(String name)
Reads setting name. Returns value or false if setting is not set.
setting.blank
Syntax: true setting.blank(String name)
Blanks setting name. Returns true on success.
setting.is_set
Syntax: boolean setting.is_set(String name)
Checks if setting name is set. Returns true if it is, false if it isn't.
Misc. functions
exec
Syntax: none exec(String cmd)
Invokes emulator command cmd.
Syntax: none print(...)
Print value(s)
Prints values of all arguments (note: Table, function, thread, light userdata and userdata values can't be printed). The arguments are printed separated by tabs.
utime
Syntax: (Number secs, Number usecs) utime()
- Since: rr1-Δ5.
Return the current time. secs is the number of seconds since 19700101T000000Z. usecs is the number of microseconds within second.
emulator_ready
Syntax: boolean emulator_ready()
- Since: rr1-Δ5.
Returns true if on_startup has already been called, false otherwise.
set_idle_timeout
Syntax: none set_idle_timeout(Number microsecs)
- Since: rr1-Δ5.
After microsecs microseconds have passed and the emulator is idle, call the on_idle callback.
set_timer_timeout
Syntax: none set_timer_timeout(Number microsecs)
- Since: rr1-Δ5.
After microsecs microseconds have passed, call the on_timer callback.
bus_address
Syntax: Number bus_address(Number address)
- Since: rr1-Δ10.
Returns the map address corresponding to address address on physical console bus.
Currently only supported for SNES & co.
loopwrapper(
Syntax: Function loopwrapper(Function fn, ...)
- Since: rr1-Δ14ε1
First calls function fn with function suspending the execution of the function when called and any remaining arguments.
When the function calls the suspend function, loopwrapper returns function that will resume fn when called.
The suspend function returns the values passed to resume function as parameters.
This is handy for using functions that have internal loops, that need to run over a long time, as callbacks.
Callbacks
(Generic)
These all are defined by Lua scripts.
Return fast from these hooks or the performance suffers. Not returning at all locks up the emulator.
on_paint
Called when screen is rerendered. Any draw primitives here affect the drawn screen.
Parameter: boolean non_synthetic
non_synthetic is true if on_paint is triggered by actual frame from console or by a subframe (if requested). It is false for calls triggered by gui.request_paint().
on_video
Called when video frame is rendered. Any draw primitives here affect dumped video frame.
- May be called multiple times per frame if multiple dumpers are active.
- SDMP dumper does not call this.
on_input
Called when input for frame is decided. May change the input in readwrite mode.
Parameter: boolean subframe
subframe is true if this is in response to subframe. Otherwise false.
on_reset
Called when console resets.
on_frame
Called after frame has completed (after on_paint)
on_readwrite
Called when entering readwrite mode.
on_startup
Called when the emulator starts up.
on_pre_load
- Parameter #1: String savename
Called before loading a savestate or movie.
Parameter: String name
The name of savestate or movie to load is passed as name.
on_err_load
Called if loading savestate or movie failed.
Parameter: String name
The name of savestate or movie attempted to load is passed as name.
on_post_load
Called if loading savestate or movie succeeded.
- Parameter: String name
- Parameter: boolean is_state.
The name of savestate/movie is name. is_state is true if savestate, false for movies.
on_pre_save
Called before saving savestate or movie (except if movie save was requested from Lua).
- Parameter: String name
- Parameter: boolean is_state.
name is the name of savestate or movie. is_state is true if this is savestate, false if movie.
on_err_save
Called if saving savestate or movie failed (except if movie save was requested from Lua).
- Parameter: String name
name is the name of savestate or movie that failed to save.
on_post_save
Called if saving savestate or movie succeeded (except if movie save was requested from Lua).
- Parameter: String name
- Parameter: boolean is_state.
name is the name of savestate or movie. is_state is true if this is savestate, false if movie.
on_snoop
Called just before answering a poll from emulator core. Can't alter the result.
- Parameter: number port
- Parameter: number controller
- Parameter: number index
- Parameter: number value.
The poll is for port port, controller controller, control index index and the value to be returned is value.
on_quit
Called just before the emulator quits.
on_keyhook
Called if status of key has changed (and callbacks have been requested for that key).
- Parameter: String key
- Parameter: Table state
The key state change is for is key. state is state table, in the same format as the inner tables of input.raw.
on_set_rewind
Called when unsafe rewind point has been set up.
- Parameter: UNSAFEREWIND state
The state object is passed as state.
on_pre_rewind
Called just before unsafe rewind occurs.
on_post_rewind
Called just after unsafe rewind has occured.
on_frame_emulated
- Since: rr1-Δ5.
Called just after frame emulation finishes, but before on_paint.
on_idle
Called when the specified idle timeout expires and the emulator is idle.
on_timer
Called when the specified timer timeout expires.