Merge branch 'rr1-maint'

[lsnes.git] / manual.txt

1 Introduction

lsnes is SNES rerecording emulator based on bsnes core.

2 Dependencies

1. bsnes libsnes

  (a) v084 or 085

  (b) accuracy or compatiblity core.

  (c) Patched version (using included 6 patches)

2. Zlib

3. boost_iostreams

4. boost_filesystem

5. boost_thread

6. libsdl (SDL only)

7. sdlmain (SDL only, part of SDL)

8. boost_conversion (this is header-only library)

9. libswscale (wxwidgets graphics only)

10. Portaudio (portaudio sound only)

11. std::thread and co (for threaded dumper only, not needed if 
  std::thread is available)

12. Lua (if Lua support is needed).

• Version 5.1.X or 5.2X.

3 Building

Building is via makefile, the following options are available:

• CROSS_PREFIX=<prefix>

  – Prefix to apply to commands when building executables / 
    object files for the target architecture. 

  – Default is blank.

• CC=<name>

  – Name of C++ compiler.

  – CROSS_PREFIX is prepended if compiling for target 
    architecture.

  – This needs to be at least GCC 4.6.

  – Set to 'g++-mp-4.6' if compiling on Mac OS X using GCC 4.6 
    from Macports.

  – Default is 'g++'.

• HOSTCC=<name>

  – Name of host C++ compiler.

  – Default is value of 'CC' option.

• USER_HOSTCCFLAGS=<flags>:

  – Compiler flags to pass when compiling/linking for host 
    architecture.

  – Default is blank.

• USER_CFLAGS=<flags>

  – Extra flags to pass when compiling for target architecture

  – Default is blank.

• USER_LDFLAGS=<flags>: 

  – Extra flags to pass when linking for target architecture.

  – Default is blank.

• USER_PLATFORM_CFLAGS=<flags>

  – Extra flags to pass when compiling files using 
    platform-dependent code for target architecture.

  – Default is blank.

• USER_PLATFORM_LDFLAGS=<flags>

  – Extra flags to pass when linking files using 
    platform-dependent code for target architecture.

  – Default is blank.

• FONT_SRC=<file>

  – Set the font file to use.

  – Currently the valid values are:

    ∗ cp437.hex: Standard VGA font (256 characters).

    ∗ unifontfull-5.1.20080820.hex: GNU unifont (covers most of 
      Unicode BMP)

  – Default is 'unifontfull-5.1.20080820.hex'

• LUA=<package>

  – Package to use for Lua support.

  – Usually valid value is 'lua' or 'lua5.1'.

  – Default is not to build Lua support.

• THREADS=<value>

  – Override platform default for dumper threading support.

  – Threading is default on Linux.

  – 'YES' tries to use threading (std::thread).

  – 'BOOST' tries to use threading (boost::thread).

  – 'NO' disables threading.

  – Note: This has absolutely nothing to do with platform 
    threading.

• BSNES_IS_COMPAT=<anything>

  – Signals that BSNES core used is compatiblity core, not 
    accuracy core.

  – Default is to assume accuracy core.

• JOYSTICK=<implementation>

  – Set joystick implementation. Valid values are:

    ∗ SDL: Use SDL for joystick (requires SDL graphics)

    ∗ EVDEV: Use EVDEV for joystick (Linux only).

    ∗ DUMMY: Disable joystick support.

  – Default is SDL.

• SOUND=<implementation>

  – Set sound implementation. Valid values are:

    ∗ SDL: Use SDL for sound (requires SDL graphics)

    ∗ PORTAUDIO: Use Portaudio for sound.

    ∗ DUMMY: Disable sound support

  – Default is SDL.

• GRAPHICS=<implementation>

  – Set windowing library to use. Valid values are:

    ∗ SDL: Use SDL for graphics

    ∗ WXWIDGETS: Use wxWidgets for graphics.

  – Default is SDL.

4 Command line options

4.1 ROM options

<kind> in the following can be one of:

• rom: Cartridge ROM (BIOS for special carts). This is required.

• bsx: BS-X (non-slotted) Game flash ROM.

• bsxslotted: BS-X (slotted) Game flash ROM.

• dmg: DMG game ROM

• slot-a: Sufami Turbo Slot A ROM

• slot-b: Sufami Turbo Slot B ROM

4.1.1 --<kind>=<file> (lsnes/SDL, lsnes-avidump)

Load <file> as specified ROM (SFC/BS/DMG/ST file format).

4.1.2 --<kind>-xml=<file> (lsnes/SDL, lsnes-avidump)

Override hardware detection for ROM, reading the values from 
<file> (BSNES XML format).

4.1.3 --ips-<kind>=<file> (lsnes/SDL, lsnes-avidump)

Apply BPS/IPS patch <file> to ROM <kind>. If specified multiple 
times, the patches are applied in order.

4.1.4 --ips-<kind>-xml=<file> (lsnes/SDL, lsnes-avidump)

Apply BPS/IPS patch <file> to XML of ROM <kind>. If specified 
multiple times, the patches are applied in order.

4.1.5 --ips-offset=<offset> (lsnes/SDL, lsnes-avidump)

Set offset to apply to IPS patches. May be negative. Handy for 
applying headered IPS patches (use offset of -512 for this). The 
offset must be 0 for BPS patches.

4.1.6 --pal

Force ROM to be considered PAL-only.

• Only works on SNES and SGB ROMs (not BS-X or Sufami Turbo).

• Attempting to load NTSC movie file will error out.

4.1.7 --ntsc

Force ROM to be considered NTSC-only.

• Attempting to load PAL movie file will error out.

4.2 Session options

4.2.1 <filename> (lsnes/SDL, lsnes-avidump, movieinfo)

Load <filename> as movie or savestate file. All other session 
options are ignored.

4.2.2 --port1=<device> (lsnes/SDL)

Set type of port1. Valid values are:

• none: No device connected

• gamepad: One gamepad (the default)

• multitap: Four gamepads (warning: makes most games refuse to 
  start)

• mouse: Mouse.

4.2.3 --port2=<type> (lsnes/SDL)

Set type of port2. Valid values are:

• none: No device connected (the default)

• gamepad: One gamepad

• multitap: Four gamepads.

• mouse: Mouse

• superscope: Super Scope

• justifier: One justifier

• justifiers: Two justifiers

4.2.4 --gamename=<name> (lsnes/SDL)

Set the name of game to <name>. Default is blank.

4.2.5 --author=<name> (lsnes/SDL)

Add author with full name of <name> (no nickname).

4.2.6 --author=|<name> (lsnes/SDL)

Add author with nickname of <name> (no full name).

4.2.7 --author=<fullname>|<nickname> (lsnes/SDL)

Add author with full name of <fullname> and nickname of 
<nickname>.

4.2.8 --rtc-second=<value> (lsnes/SDL)

Set RTC second (0 is 1st January 1970 00:00:00Z). Default is 
1,000,000,000.

4.2.9 --rtc-subsecond=<value> (lsnes/SDL)

Set RTC subsecond. Range is 0-. Unit is CPU cycle. Default is 0.

4.3 Misc. options:

4.3.1 --run=<file> (lsnes/SDL)

After running main RC file, run this file. If multiple are 
specified, these execute in order specified.

4.4 dump options (lsnes-dumpavi only)

4.4.1 --dumper=<dumper>

Set the dumper to use (required). Use 'list' for listing of known 
dumpers.

4.4.2 --mode=<mode>

Set the mode to use (required for dumpers with multiple modes, 
forbidden otherwise). Use 'list' for known modes.

4.4.3 --prefix=<prefix>

Set dump prefix. Default is “avidump”.

4.4.4 --option=<name>=<value>

Set option <name> to value <value>.

4.4.5 --length=<length>

Set number of frames to dump. Mandatory.

4.4.6 --lua=<script>

Run specified lua script (lsnes-dumpavi does not have 
initialization files).

4.4.7 --load-library=<library>

Load the specified shared object / dynamic library / dynamic link 
library.

5 Startup file lsnes.rc

Upon startup, lsnes (lsnes/SDL only) executes file lsnes.rc as 
commands. This file is located in:

• Windows: %APPDATA%\lsnes\lsnes.rc (if %APPDATA% exists)

• Unix: $XDG_CONFIG_HOME/lsnes/lsnes.rc (if $XDG_CONFIG_HOME 
  exists)

• Unix: $HOME/.config/lsnes/lsnes.rc (if $HOME exists)

• All: ./lsnes.rc (fallback default).

If leading directories do not exist, attempt to create them is 
made.

6 Internal commands

• Commands beginning with '*' invoke the corresponding command 
  without alias expansion.

• If command starts with '+' (after possible '*'), the command is 
  executed as-is when button is pressed, and when button is 
  released, it is executed with '+' replaced by '-'.

• Commands without '+' execute only on negative edge (release).

6.1 Settings:

Settings control various aspects of emulator behaviour.

6.1.1 set-setting <setting> <value>

Sets setting <setting> to value <value> (may be empty).

6.1.2 unset-setting <setting>

Try to unset setting <setting> (not all settings can be unset).

6.1.3 get-setting <setting>

Read value of setting <setting>

6.1.4 show-settings

Print names and values of all settings.

6.2 Keybindings

Keybindings bind commands or aliases to keys (or pseudo-keys). 

Notes:

• Do not bind edge active (+/-) commands to keys with modifiers, 
  that won't work right!

• Names of keys and modifiers are platform-dependent.

• Be careful before binding pseudo-keys (such as joystick axes, 
  buttons or hats) with modifiers. That may or may not work 
  right.

6.2.1 bind-key [<mod>/<modmask>] <key> <command>

Bind <command> to key <key> (activating if modifiers in <modmask> 
(comma-seperated list) are set as <mod> (comma-seperated list).

The names of keys and modifiers are platform-dependent.

6.2.2 unbind-key [<mod>/<modmask>] <key>

Unbind command from <key> (with specified <mod> and <modmask>).

6.2.3 set-axis <axis> [disabled | axis | axis-inverse | 
  pressure0- | pressure0+ | pressure-0 | pressure-+ | pressure+0 
  | pressure+-] [minus=<val>] [zero=<val>] [plus=<val>] 
  [tolerance=<val>]

Set axis parameters for axis <axis>.

• disabled: Disable axis

• axis: Normal axis

• axis-inverse: Inverse axis

• pressure0-: Pressure sensitive. Released at 0, pressed at -.

• pressure0+: Pressure sensitive. Released at 0, pressed at +.

• pressure-0: Pressure sensitive. Released at -, pressed at 0.

• pressure-+: Pressure sensitive. Released at -, pressed at +.

• pressure+0: Pressure sensitive. Released at +, pressed at 0.

• pressure+-: Pressure sensitive. Released at +, pressed at -.

• minus=<val>: Calibration at extreme minus position 
  (-32768-32767)

• zero=<val>: Calibration at neutral position (-32768-32767)

• plus=<val>: Calibration at extreme plus position (-32768-32767)

• tolerance=<value>: Center band tolerance (0<x<1). The smaller 
  the value, the more sensitive the control is.

6.2.4 show-bindings

Print all key bindings in effect.

6.3 Aliases

Aliases bind command to sequence of commands. After alias has 
been defined, it replaces the command it shadows.

Notes:

• You can't alias command to itself.

• Aliases starting with +/- are edge active just like ordinary 
  commands starting with +/-.

• One command can be aliased to multiple commands.

6.3.1 alias-command <command> <expansion>

Append <expansion> to alias <command>. If alias does not already 
exist, it is created.

6.3.2 unalias-command <command>

Clear alias expansion for <command>.

6.3.3 show-aliases

Print all aliases and their expansions in effect.

6.4 run-script <script>

Run <script> as if commands were entered on the command line.

6.5 Video dumping

Following commands control video dumping:

6.5.1 start-dump <dumper> [<mode>] <prefix/filename>

Start dumping using dumper <dumper>. If mode is present or not 
and if prefix or filename is present depends on the dumper and 
dumper mode.

The following dumpers are available:

• INTERNAL-AVI-CSCD: Internal CSCD in .avi dumper.

  – Mode: uncompressed/pcm: Uncompressed video, PCM audio. Takes 
    prefix.

  – Mode: cscd/pcm: CSCD video, PCM audio. Takes prefix.

• INTERNAL-JMD: Internal .jmd dumper.

  – Does not take mode.

  – Takes a filename.

• INTERNAL-RAW: Internal RAW dumper.

  – Does not take mode.

  – Takes a prefix.

  – Sound is big-endian signed 16-bit, usually at 32040.5Hz.

  – Video is always upscaled to double resolution (512x448 / 512 
    x 478).

  – Video framerate is usually 322445/6448 fps for PAL and 
    10738636/178683 fps for NTSC.

• INTERNAL-SDMP: Internal SDMP dumper.

  – Mode 'ms': Multi-segment. Takes prefix.

  – Mode 'ss': Single-segment. Takes filename.

6.5.2 end-dump <dumper>

End dumping using <dumper>

6.5.3 show-dumpers [<dumper>]

Show the list of dumpers or list of modes for <dumper>

6.6 Memory manipulation

<address> may be decimal or hexadecimal (prefixed with '0x'). 
<value> can be hexadecimal (prefixed with '0x'), unsigned or 
signed (prefixed with '-') decimal.

The available element <sizes> are:

• byte: 1 byte

• word: 2 bytes

• dword: 4 bytes

• qword: 8 bytes

When reading RAM and ROM, multi-byte reads/writes are big-endian. 
When dealing with DSP memory, multi-byte reads/writes are 
native-endian (do not use operand sizes exceeding DSP bitness, 
except dword is OK for 24-bit memory).

6.6.1 read-<size> <address>

Read the value of byte in <address>.

6.6.2 read-s<size> <address>

Read the value of signed byte in <address>.

6.6.3 write-<size> <address> <value>

Write <value> to byte in address <address>.

6.6.4 search-memory reset

Reset the memory search

6.6.5 search-memory count

Print number of candidates remaining

6.6.6 search-memory print

Print all candidates remaining

6.6.7 search-memory <usflag><sizeflag><op>

Searches memory for addresses satisfying criteria.

<usflag> can be:

• u: unsigned

• s: signed

<sizeflag> can be:

• b: byte

• w: word

• d: dword

• q: qword

<op> can be:

• lt: < previous value.

• le: <= previous value.

• eq: = previous value.

• ne: != previous value.

• ge: >= previous value.

• gt: > previous value.

6.6.8 search-memory <sizeflag> <value>

Searches for addresses that currently have value <value>. 
<sizeflag> is as in previous command.

6.7 Main commands

These commands are not available in lsnesrc, but are available 
after ROM has been loaded.

6.7.1 quit-emulator [/y]

Quits the emulator (asking for confirmation). If /y is given, no 
confirmation is asked.

6.7.2 pause-emulator

Toggle paused/unpaused

6.7.3 +advance-frame 

Advance frame. If the button is still held after configurable 
timeout expires, game unpauses for the duration frame advance is 
held.

6.7.4 +advance-poll 

Advance subframe. If the button is still held after configurable 
timeout expires, game unpauses for the duration frame advance is 
held.

6.7.5 advance-skiplag 

Skip to first poll in frame after current.

6.7.6 reset 

Reset the SNES after this frame.

6.7.7 load <filename> 

Load savestate <filename> in current mode.

6.7.8 load-state <filename> 

Load savestate <filename> in readwrite mode.

6.7.9 load-readonly <filename> 

Load savestate <filename> in readonly mode.

6.7.10 load-preserve <filename> 

Load savestate <filename> in readonly mode, preserving current 
events.

6.7.11 load-movie <filename> 

Load savestate <filename>, ignoring save part in readonly mode.

6.7.12 save-state <filename> 

Save system state to <filename> as soon as possible.

6.7.13 save-movie <filename> 

Save movie to <filename>.

6.7.14 set-rwmode 

Set read-write mode.

6.7.15 set-romode 

Set read-only mode

6.7.16 toggle-rwmode 

Toggle between read-only and read-write modes.

6.7.17 set-gamename <name> 

Set name of the game to <name>

6.7.18 get-gamename 

Print the name of the game.

6.7.19 add-author <author> 

Adds new author <author>. If <author> does not contain '|' it is 
full name. If it contains '|', '|' splits the full name and 
nickname.

6.7.20 edit-author <num> <author> 

Edit the author in slot <num> (0-based) to be <author> (see 
add-author for format)

6.7.21 remove-author <num> 

Remove author in slot <num>

6.7.22 print-authors 

Print authors.

6.7.23 test-1, test-2, test-3

Internal test commands. Don't use.

6.7.24 take-screenshot <filename> 

Save screenshot to <filename>.

6.7.25 +controller<num><button>

Press button <button> on controller <num> (1-8). The following 
button names are known:

• left

• right

• up

• down

• A

• B

• X

• Y

• L

• R

• select

• start

• trigger

• cursor

• pause

• turbo

6.7.26 controllerh<num><button>

Hold/unhold button <button> on controller <num> (1-8). See 
+controller for button names.

6.7.27 autofire (<pattern>|-)...

Set autofire pattern. Each parameter is comma-separated list of 
button names (in form of 1start, 1A, 2B, etc..) to hold on that 
frame. After reaching the end of pattern, the pattern restarts 
from the beginning.

6.7.28 repaint

Force a repaint.

6.8 Save jukebox 

6.8.1 cycle-jukebox-backward

Cycle save jukebox backwards.

6.8.2 cycle-jukebox-forward

Cycle save jukebox forwards

6.8.3 add-jukebox-save <filename>

Add <filename> to jukebox saves.

6.8.4 load-jukebox

Do load from jukebox (current mode).

6.8.5 save-jukebox

Do state save to jukebox.

6.9 Lua 

Only available if lua support is compiled in.

6.9.1 evaluate-lua <luacode>

Run Lua code <luacode> using built-in Lua interpretter.

6.9.2 run-lua <script>

Run specified lua file using built-in Lua interpretter.

6.10 Memory watch

6.10.1 add-watch <name> <expression>

Adds new watch (or modifies old one).

6.10.2 remove-watch <name>

Remove a watch.

6.11 Sound 

6.11.1 enable-sound <on/off> 

Enable/Disable sound.

6.11.2 set-sound-device <device> 

Set sound device to <device>

6.11.3 show-sound-status 

Show status of sound system.

6.11.4 show-sound-devices

Show all available devices.

6.12 SDL Platform commands 

The following are valid on SDL platform.

6.12.1 identify-key

Asks to press a key and then identifies that (pseudo-)key.

6.12.2 toggle-console 

Toggle between windowed/fullscreen console.

6.12.3 scroll-fullup 

Scroll messages window as far back as it goes.

6.12.4 scroll-fulldown 

Scroll messages window as far forward as it goes.

6.12.5 scroll-up 

Scroll messages window back one screenful.

6.12.6 scroll-down 

Scroll messages window forward one screenful.

7 Settings

7.1 Core settings

7.1.1 firmwarepath

Set where bsnes looks for firmware files. Default is “.”.

7.1.2 targetfps

Set the target fps. Numeric, range is 0.001 to “infinite”. 
Default is native framerate.

7.1.3 savecompression

Set save compression level (integer 0-9). Default is 7 (0 is no 
compression).

7.1.4 advance-timeout

Set the frame advance timeout in milliseconds. Numeric integer, 
range is 0-999999999. Default is 500.

7.2 AVI dumper settings

7.2.1 avi-large

AVI dumper: Always dump at 512x448 or 512x478 regardless of what 
the console outputs.

7.2.2 avi-left-border

AVI dumper: Set the default left border thickness (unless lua 
overrides) for dumps. Range 0-8191. Default is 0.

7.2.3 avi-right-border

AVI dumper: Set the default right border thickness (unless lua 
overrides) for dumps. Range 0-8191. Default is 0.

7.2.4 avi-top-border

AVI dumper: Set the default top border thickness (unless lua 
overrides) for dumps. Range 0-8191. Default is 0.

7.2.5 avi-bottom-border

AVI dumper: Set the default bottom border thickness (unless lua 
overrides) for dumps. Range 0-8191. Default is 0.

7.2.6 avi-maxframes

AVI dumper: Maximum number of frames per dump segment (0 => 
unlimited). Range 0-999999999. Default is 0.

7.2.7 avi-compresison

AVI dumper: Compression level (0-18).

• Compression levels 10 and above are not compatible with stock 
  CSCD codec.

• Recomended level is 7.

7.2.8 avi-soundrate

AVI dumper: Set method of determining the sound rate.

• 0: Pick nearest of 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, 48, 
  64, 88.2, 96, 128, 176.4 and 192 kHz.

• 1: Round down to nearest integer.

• 2: Round up to nearest ingeter.

7.3 JMD options

7.3.1 jmd-copression

JMD dumper: Compression level (0-9).

7.4 SDL platform settings

7.4.1 autorepeat-first-delay

Sets the delay for first character in typematic autorepeat.

7.4.2 autorepeat-subsequent-delay

Sets the delay for subsequent characters in typematic autorepeat.

8 Lua functions

8.1 Core (in main table)

8.1.1 print

Print line to message console.

8.1.2 exec(string command)

Run command as it was entered on the command line

8.1.3 utime()

Returns two values. First is time since some epoch in seconds, 
the second is microseconds mod 10^6 since that epoch.

8.1.4 emulator_ready()

Returns true if emulator has finished booting, false if not 
(on_startup() will be issued later).

8.1.5 set_idle_timeout(number timeout)

Set number of microseconds to block idle for. After this timeout 
has expired, on_idle() will be called once.

8.1.6 set_timer_timeout(number timeout)

Set number of microseconds to block timer for. After this timeout 
has expired, on_timer() will be called once.

8.2 Table bit:

Bitwise logical functions and related.

8.2.1 bit.none(number...) / bit.bnot(number...)

48-bit bitwise NOT / NONE function (set bits that are set in none 
of the arguments).

8.2.2 bit.any(number...) / bit.bor(number...)

48-bit bitwise OR / ANY function (set bits that are set in any of 
the arguments).

8.2.3 bit.all(number...) / bit.band(number...)

48-bit bitwise AND / ALL function (set bits that are set in all 
of the arguments).

8.2.4 bit.parity(number...) / bit.bxor(number...)

48-bit bitwise XOR / PARITY function (set bits that are set in 
odd number of the arguments).

8.2.5 bit.lrotate(number base[, number amount[, number bits]])

Rotate bits-bit (max 48, default 48) number left by amount 
(default 1) places.

8.2.6 bit.rrotate(number base[, number amount[, number bits]])

Rotate bits-bit (max 48, default 48) number right by amount 
(default 1) places.

8.2.7 bit.lshift(number base[, number amount[, number bits]])

Shift bits-bit (max 48, default 48) number left by amount 
(default 1) places. The new bits are filled with zeroes.

8.2.8 bit.lrshift(number base[, number amount[, number bits]])

Shift bits-bit (max 48, default 48) number logically right by 
amount (default 1) places. The new bits are filled with zeroes.

8.2.9 bit.arshift(number base[, number amount[, number bits]])

Shift bits-bit (max 48, default 48) number arithmetically right 
by amount (default 1) places. The new bits are shifted in with 
copy of the high bit.

8.2.10 bit.extract(number base[, number bit0[, number bit1,...]])

Returns number that has bit0-th bit as bit 0, bit1-th bit as 1 
and so on.

Notes: 

• Bit numbers up to 51 should work reliably (then things start 
  falling apart due to double precision issues).

• There are two special bit positions, true and false, standing 
  for always set bit and always clear bit.

8.3 Table gui:

Most of these functions can only be called in on_paint and 
on_video callbacks. Exceptions are noted.

Colors are 32-bit. Bits 0-7 are the blue component, bits 8-15 are 
the green component, bits 16-23 are the red component, bits 24-31 
are alpha component (0 is fully opaque, 255 is almost 
transparent). -1 is the fully transparent color. Alpha values 
greater than 127 do work.

Origin of coordinates is at top left corner of game display area. 
Left and top gaps correspond to negative coordinates.

8.3.1 gui.resolution()

Returns 2-tuple (hresolution, vresolution).

8.3.2 gui.<class>_gap(number gap)

Set the <class> (left, right, top, bottom) gap to specified value 
(max gap is 8191).

8.3.3 gui.text(number x, number y, string text[, number fgc[, 
  number bgc]])

Draw specified text on the GUI (each character cell is 8 or 16 
wide and 16 high). Parameters:

• x: X-coordinate to start the drawing from (and x-coordinate at 
  begining of the lines).

• y: Y-coordinate to start the drawing from.

• text: The text to draw.

• fgc: Text color (default is 0xFFFFFF (white))

• bgc: Background color (default is -1 (transparent))

8.3.4 gui.textH(number x, number y, string text[, number fgc[, 
  number bgc]])

Like gui.text, but draw using double-width.

8.3.5 gui.textV(number x, number y, string text[, number fgc[, 
  number bgc]])

Like gui.text, but draw using double-height.

8.3.6 gui.textHV(number x, number y, string text[, number fgc[, 
  number bgc]])

Like gui.text, but draw using double-width/double-height.

8.3.7 gui.rectangle(number x, number y, number width, number 
  height[, number thickness[, number outline[, number fill]]])

Draw rectangle on the GUI. Parameters:

• x: X-coordinate of left edge.

• y: Y-coordinate of upper edge.

• width: Width of rectangle.

• height: Height of rectangle.

• thickness: Thickness of outline (default is 1).

• outline: Color of outline (default is 0xFFFFFF (white))

• fill: Color of fil (default is -1 (transparent))

8.3.8 gui.pixel(number x, number y[, number color])

Draw one pixel on the GUI. Parameters:

• x: X-coordinate of the pixel

• y: Y-coordinate of the pixel

• color: Color of the pixel (default is 0xFFFFFF (white))

8.3.9 gui.crosshair(number x, number y[, number length[, number 
  color]])

Draw a crosshair. Parameters:

• x: X-coordinate of the crosshair

• y: Y-coordinate of the crosshair

• length: Length of the crosshair lines (default 10).

• color: Color of the crosshair (default is 0xFFFFFF (white))

8.3.10 gui.line(number x1, number y1, number x2, number y2[, 
  number color])

Draw a thin line. Parameters:

• x1: X-coordinate of one end.

• y1: Y-coordinate of one end.

• x2: X-coordinate of the other end.

• y2: Y-coordinate of the other end.

• color: Color of the line (default is 0xFFFFFF (white)).

8.3.11 gui.circle(number x, number y, number r[, number thick[, 
  number border[, number fil]]])

Draw a circle. Parameters.

• x: X-coordinate of the center

• y: Y-coordinate of the center

• r: The radius of the circle

• thick: Border thickness

• border: Border color (default is 0xFFFFFF (white))

• fill: Fill color (default is -1 (transparent)).

8.3.12 gui.bitmap_draw(number x, number y, bitmap bitmap, palette 
  palette)

Draw a bitmap on screen with specified palette. Parameters:

• x: X-coordinate of left edge.

• y: Y-coordinate of top edge.

• bitmap: The bitmap to draw

• palette: The palette to draw the bitmap using.

8.3.13 gui.bitmap_draw(number x, number y, dbitmap bitmap)

Draw a bitmap on screen. Parameters:

• x: X-coordinate of left edge.

• y: Y-coordinate of top edge.

• bitmap: The bitmap to draw

8.3.14 gui.palette_new()

Returns a new palette (initially all transparent). Can be used 
anywhere.

8.3.15 gui.bitmap_new(number w, number h, boolean direct)

Returns a new bitmap/dbitmap. Can be used anywhere. Parameters:

• w: The width of new bitmap

• h: The height of new bitmap

• direct: If true, the returned bitmap is dbitmap, otherwise 
  bitmap.

8.3.16 gui.bitmap_load(string file)

Returns loaded bitmap/dbitmap (if bitmap, the second return value 
is palette for bitmap). Can be used anywhere. Parameters:

• file: The name of file to load.

8.3.17 gui.palette_set(palette palette, number index, number 
  color)

Sets color in palette. Can be used anywhere. Parameters:

• palette: The palette to manipulate

• index: Index of color (0-65535).

• color: The color value.

8.3.18 gui.bitmap_pset(bitmap/dbitmap bitmap, number x, number y, 
  number color)

Sets specified pixel in bitmap. Can be used anywhere. Parameters:

• bitmap: The bitmap to manipulate

• x: The x-coordinate of the pixel.

• y: The y-coordinate of the pixel.

• color: If bitmap is a bitmap, color index (0-65535). Otherwise 
  color value.

8.3.19 gui.bitmap_size(bitmap/dbitmap bitmap)

Get size of bitmap. Can be used anywhere. Parameters:

• bitmap: The bitmap to query.

The first return is the width, the second is the height.

8.3.20 gui.bitmap_blit(bitmap/dbitmap dest, number dx, number dy, 
  bitmap/dbitmap src, number sx, number sy, number w, number h[, 
  number ck])

Blit a part of bitmap to another. Can be used anywhere. 
Parameters:

• dest: Destination to blit to.

• dx: left edge of target

• dy: Top edge of target

• src: The source to blit from. Must be of the same type as 
  destination.

• sx: left edge of source

• sy: Top edge of source

• w: Width of region

• h: Height of region.

• ck: Color key. Pixels of this color are not blitted.

  – If bitmaps are bitmaps, this is color index of colorkey. 
    Values outside range 0-65535 cause no key to be used as 
    colorkey.

  – If bitmaps are dbitmaps, this color value of colorkey.

  – May be absent or nil for no colorkey blit.

8.3.21 gui.repaint()

Request on_repaint() to happen as soon as possible. Can be used 
anywhere.

8.3.22 gui.subframe_update(boolean on)

Request subframe updates (calling on_paint() on subframes) to 
happen (on=true) or not happen (on=false). Can be used anywhere.

8.3.23 gui.screenshot(string filename)

Write PNG screenshot of the current frame (no drawings) to 
specified file. Can be used anywhere.

8.3.24 gui.color(number r, number g, number b[, number a])

Returns color (in notation Lua scripts use) corresponding to 
color (r,g,b), each component in scale 0-255. If a is specified, 
that is alpha (0 is fully transparent, 256(sic) is fully opaque). 
The default alpha is 256.

8.3.25 gui.status(string name, string value)

Set status field “L[<name>]” to <value> in status area. Can be 
used anywhere.

8.4 table input

Input handling. Only available in on_input callback.

8.4.1 input.get(number controller, number index)

Read the specified index (0-11) from specified controller (0-7). 
Notes:

• Uses physical controller numbering. Gamepad in port 2 is 
  controller 4, not 1!

8.4.2 input.set(number controller, number index, number value)

Write the specified index (0-11) from specified controller (0-7), 
storing value. Notes:

• Uses physical controller numbering. Gamepad in port 2 is 
  controller 4, not 1!

8.4.3 input.geta(number controller)

Get input state for entiere controller. Returns 13 return values.

• 1st return value: Bitmask: bit i is set if i:th index is 
  nonzero

• 2nd-13th return value: value of i:th index.

8.4.4 input.seta(number controller, number bitmask, number 
  args...)

Set state for entiere controller. args is up to 12 values for 
indices (overriding values in bitmask if specified).

8.4.5 input.reset([number cycles])

Execute reset. If cycles is greater than zero, do delayed reset. 
0 (or no value) causes immediate reset.

• Only available with subframe flag false.

8.4.6 input.raw()

Returns table of tables of all available keys and axes. The first 
table is indexed by key name (platform-dependent!), and the inner 
table has the following fields:

• last_rawval: Last reported raw value for control.

• ktype: Type of key (disabled, key, mouse, axis, axis-inverse, 
  hat, pressure-m0, pressure-mp, pressure-0m, pressure-0p, 
  pressure-pm, pressure-p0).

• cal_left: Minimum calibration value. Only meaningful with axis 
  and pressure types.

• cal_center: Center calibration value. Only meaningful with axis 
  and pressure types.

• cal_right: Maximum calibration value. Only meaningful with axis 
  and pressure types.

• cal_tolerance: Dead zone tolerance. Only meaningful with axis 
  and pressure types.

8.4.7 input.keyhook(key, state)

Requests that keyhook events to be sent for key (state=true) or 
not sent (state=false).

8.5 Table hostmemory

Host memory handling (extra memory saved to savestates). Host 
memory starts empty.

8.5.1 hostmemory.read(number address)

Reads hostmemory slot address. Slot numbers out of range return 
false instead of numeric.

8.5.2 hostmemory.write(number address, number value)

Writes hostmemory slot with 0-255. Slot numbers out of range 
cause extension of host memory slot space.

8.5.3 hostmemory.readbyte(number address)

Read unsigned byte (1 element) from given address. Slots out of 
range return false.

8.5.4 hostmemory.writebyte(number address, number value)

Write unsigned byte (1 element) to given slot. Slot numbers out 
of range cause extension.

8.5.5 hostmemory.readsbyte(number address)

Read signed byte (1 element) from given address. Slots out of 
range return false.

8.5.6 hostmemory.writesbyte(number address, number value)

Write signed byte (1 element) to given slot. Slot numbers out of 
range cause extension.

8.5.7 hostmemory.readword(number address)

Read unsigned word (2 elements) from given address. Slots out of 
range return false.

8.5.8 hostmemory.writeword(number address, number value)

Write unsigned word (2 elements) to given slot. Slot numbers out 
of range cause extension.

8.5.9 hostmemory.readsword(number address)

Read signed word (2 elements) from given address. Slots out of 
range return false.

8.5.10 hostmemory.writesword(number address, number value)

Write signed word (2 elements) to given slot. Slot numbers out of 
range cause extension.

8.5.11 hostmemory.readdword(number address)

Read unsigned doubleword (4 elements) from given address. Slots 
out of range return false.

8.5.12 hostmemory.writedword(number address, number value)

Write unsigned doubleword (4 elements) to given slot. Slot 
numbers out of range cause extension.

8.5.13 hostmemory.readsdword(number address)

Read signed doubleword (4 elements) from given address. Slots out 
of range return false.

8.5.14 hostmemory.writesdword(number address, number value)

Write signed doubleword (4 elements) to given slot. Slot numbers 
out of range cause extension.

8.5.15 hostmemory.readqword(number address)

Read unsigned quadword (8 elements) from given address. Slots out 
of range return false.

8.5.16 hostmemory.writeqword(number address, number value)

Write unsigned quadword (4 elements) to given slot. Slot numbers 
out of range cause extension.

8.5.17 hostmemory.readsqword(number address)

Read signed quadword (8 elements) from given address. Slots out 
of range return false.

8.5.18 hostmemory.writesqword(number address, number value)

Write signed quadword (8 elements) to given slot. Slot numbers 
out of range cause extension.

8.6 Table movie

Movie handling

8.6.1 movie.currentframe()

Return number of current frame.

8.6.2 movie.framecount()

Return number of frames in movie.

8.6.3 movie.readonly()

Return true if in readonly mode, false if in readwrite.

8.6.4 movie.set_readwrite()

Set readwrite mode (does not cause on_readwrite callback).

8.6.5 movie.frame_subframes(number frame)

Count number of subframes in specified frame (frame numbers are 
1-based) and return that.

8.6.6 movie.read_subframe(number frame, number subframe)

Read specifed subframe in specified frame and return data as 
array (100 elements, numbered 0-99 currently).

8.7 Table settings

Routines for settings manipulation

8.7.1 settings.get(string name)

Get value of setting. If setting is blank, returns false. If 
setting value can't be obtained, returns (nil, error message).

8.7.2 settings.set(string name, string value)

Set value of setting. If setting can't be set, returns (nil, 
error message).

8.7.3 settings.is_set(string name)

Returns if setting is set. If setting does not exist, returns 
(nil, error message).

8.7.4 settings.blank(string name)

Blanks a setting and returns true. If setting can't be blanked, 
returns (nil, error message).

8.8 Table memory

Contains various functions for managing memory

8.8.1 memory.vma_count()

Returns the number of VMAs

8.8.2 memory.read_vma(number index)

Reads the specified VMA (indices start from zero). Trying to read 
invalid VMA gives nil. The read VMA is table with the following 
fields:

• region_name (string): The readable name of the VMA

• baseaddr (number): Base address of the VMA

• lastaddr (number): Last address in the VMA.

• size (number): The size of VMA in bytes.

• readonly (boolean): True of the VMA corresponds to ROM.

• native_endian (boolean): True if the VMA has native endian as 
  opposed to little endian.

8.8.3 memory.find_vma(number address)

Finds the VMA containing specified address. Returns table in the 
same format as read_vma or nil if not found.

8.8.4 memory.readbyte(number address)

Reads the specified address as unsigned byte and returns the 
result.

8.8.5 memory.readsbyte(number address)

Reads the specified address as signed byte and returns the 
result.

8.8.6 memory.writebyte(number address, number value)

Writes the specified value (negative values undergo 2's 
complement) to specified address (as a byte).

8.8.7 memory.readword(number address)

Reads the specified address as unsigned word and returns the 
result.

8.8.8 memory.readsword(number address)

Reads the specified address as signed word and returns the 
result.

8.8.9 memory.writeword(number address, number value)

Writes the specified value (negative values undergo 2's 
complement) to specified address (as a word).

8.8.10 memory.readdword(number address)

Reads the specified address as unsigned doubleword and returns 
the result.

8.8.11 memory.readsdword(number address)

Reads the specified address as signed doubleword and returns the 
result.

8.8.12 memory.writedword(number address, number value)

Writes the specified value (negative values undergo 2's 
complement) to specified address (as a doubleword).

8.8.13 memory.readqword(number address)

Reads the specified address as unsigned quadword and returns the 
result.

8.8.14 memory.readsqword(number address)

Reads the specified address as signed quadword and returns the 
result.

8.8.15 memory.writeqword(number address, number value)

Writes the specified value (negative values undergo 2's 
complement) to specified address (as a quadword).

8.9 Table _SYSTEM

Contains copy of global variables from time of Lua 
initialization. Non-writeable.

8.10 Callbacks

Various callbacks to Lua that can occur.

8.10.1 Callback: on_paint(bool not_synth)

Called when screen is being painted. Any gui.* calls requiring 
graphic context draw on the screen.

not_synth is true if this hook is being called in response to 
received frame, false otherwise.

8.10.2 Callback: on_video()

Called when video dump frame is being painted. Any gui.* calls 
requiring graphic context draw on the video.

8.10.3 Callback: on_frame_emulated()

Called when emulating frame has completed and 
on_paint()/on_video() calls are about to be issued.

8.10.4 Callback: on_frame()

Called on each starting whole frame.

8.10.5 Callback: on_startup()

Called when the emulator is starting (lsnes.rc and --run files 
has been run).

8.10.6 Callback: on_rewind()

Called when rewind movie to beginning has completed.

8.10.7 Callback: on_pre_load(string name)

Called just before savestate/movie load occurs (note: loads are 
always delayed, so this occurs even when load was initiated by 
lua).

8.10.8 Callback: on_err_load(string name)

Called if loadstate goes wrong.

8.10.9 Callback: on_post_load(string name, boolean was_savestate)

Called on successful loadstate. was_savestate gives if this was a 
savestate or a movie.

8.10.10 Callback: on_pre_save(string name, boolean is_savestate)

Called just before savestate save occurs (note: movie saves are 
synchronous and won't trigger these callbacks if called from 
Lua).

8.10.11 Callback: on_err_save(string name)

Called if savestate goes wrong.

8.10.12 Callback: on_post_save(string name, boolean is_savestate)

Called on successful savaestate. is_savestate gives if this was a 
savestate or a movie.

8.10.13 Callback: on_quit()

Called when emulator is shutting down.

8.10.14 Callback: on_input(boolean subframe)

Called when emulator is just sending input to bsnes core. 
Warning: This is called even in readonly mode, but the results 
are ignored.

8.10.15 Callback: on_reset()

Called when SNES is reset.

8.10.16 Callback: on_readwrite()

Called when moving into readwrite mode as result of “set-rwmode” 
command (note: moving to rwmode by Lua won't trigger this, as per 
recursive entry protection).

8.10.17 Callback: on_snoop(number port, number controller, number 
  index, number value)

Called each time bsnes asks for input. The value is the final 
value to be sent to bsnes core (readonly mode, autohold and 
autofire have been taken into account). Might be useful when 
translating movies to format suitable for console verification. 
Note: There is no way to modify the value to be sent.

8.10.18 Callback: on_keyhook(string keyname, table state)

Sent when key that has keyhook events requested changes state. 
Keyname is name of the key (group) and state is the state (same 
kind as table values in input.raw).

8.10.19 Callback: on_idle()

Called when requested by set_idle_timeout(), the timeout has 
expired and emulator is waiting.

8.10.20 Callback: on_timer()

Called when requested by set_idle_timeout() and the timeout has 
expired (regardless if emulator is waiting).

9 Memory watch expression syntax

Memory watch expressions are in RPN (Reverse Polish Notation). At 
the end of expression, the top entry on stack is taken as the 
final result.

Notations:

• Evaluation order is strictly left to right.

• a is the entry on top of stack

• b is the entry immediately below top of stack

• ; separates values to be pushed (no intermediate pop).

• After end of element, all used stack slots are popped and all 
  results are pushed.

• When pushing multiple values, the pushes occur in order shown.

The following operators are available:

• + : a + b

• - : a - b

• * : a * b

• / : a / b

• % : a % b

• a : atan(a)

• b : read_signed_byte(a)

• c : cos(a)

• d : read_signed_dword(a)

• i : quotent(a / b)

• p :\pi


• q : read_signed_qword(a)

• r : sqrt(a)

• s : sin(a)

• t : tan(a)

• u : a; a

• w : read_signed_word(a)

• A : atan2(a, b)

• B : read_unsigned_byte(a)

• C<number>z : Push number <number> to stack.

• D : read_unsigned_dword(a)

• C0x<number>z : Push number <number> (hexadecimal) to stack.

• Q : read_unsigned_qword(a)

• R<digit> : round a to <digit> digits.

• W : read_unsigned_word(a)

9.1 Example:

C0x007e0878zWC0x007e002czW-

1. Push value 0x7e0878 on top of stack (C0x007e0878z).

2. Pop the value on top of stack (0x7e0878), read word value at 
  that address and push the result,call it x1 (W).

3. Push value 0x7e002c on top of stack (C0x007e002cz).

4. Pop the value on top of stack (0x7e002c), read word value at 
  that address and push the result,call it x2 (W).

5. Pop the two top numbers on stack, x1 and x2, substract x1 from 
  x2 and push x2 - x1 (-).

6. Since the expression ends, the final memory watch result is 
  the top one on stack, which is x2 - x1.

10 Modifier and key names:

10.1 SDL Platform

10.1.1 Modifier names

Following modifier names are known:

• ctrl, lctrl, rctrl: Control keys

• alt, lalt, ralt: ALT keys.

• shift, lshift, rshift: Shift keys.

• meta, lmeta, rmeta: Meta keys.

• num, caps: Numlock/Capslock (these are sticky!)

• mode: Mode select.

10.1.2 Key names

Following key names are known:

• backspace, tab, clear, return, pause, escape, space, exclaim, 
  quotedbl, hash, dollar, ampersand, quote, leftparen, 
  rightparen, asterisk, plus, comma, minus, period, slash, 0, 1, 
  2, 3, 4, 5, 6, 7, 8, 9, colon, semicolon, less, equals, 
  greater, question, at, leftbracket, backslash, rightbracket, 
  caret, underscore, backquote, a, b, c, d, e, f, g, h, i, j, k, 
  l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, delete, world_0, 
  world_1, world_2, world_3, world_4, world_5, world_6, world_7, 
  world_8, world_9, world_10, world_11, world_12, world_13, 
  world_14, world_15, world_16, world_17, world_18, world_19, 
  world_20, world_21, world_22, world_23, world_24, world_25, 
  world_26, world_27, world_28, world_29, world_30, world_31, 
  world_32, world_33, world_34, world_35, world_36, world_37, 
  world_38, world_39, world_40, world_41, world_42, world_43, 
  world_44, world_45, world_46, world_47, world_48, world_49, 
  world_50, world_51, world_52, world_53, world_54, world_55, 
  world_56, world_57, world_58, world_59, world_60, world_61, 
  world_62, world_63, world_64, world_65, world_66, world_67, 
  world_68, world_69, world_70, world_71, world_72, world_73, 
  world_74, world_75, world_76, world_77, world_78, world_79, 
  world_80, world_81, world_82, world_83, world_84, world_85, 
  world_86, world_87, world_88, world_89, world_90, world_91, 
  world_92, world_93, world_94, world_95, kp0, kp1, kp2, kp3, 
  kp4, kp5, kp6, kp7, kp8, kp9, kp_period, kp_divide, 
  kp_multiply, kp_minus, kp_plus, kp_enter, kp_equals, up, down, 
  right, left, insert, home, end, pageup, pagedown, f1, f2, f3, 
  f4, f5, f6, f7, f8, f9, f10, f11, f12, f13, f14, f15, numlock, 
  capslock, scrollock, rshift, lshift, rctrl, lctrl, ralt, lalt, 
  rmeta, lmeta, lsuper, rsuper, mode, compose, help, print, 
  sysreq, break, menu, power, euro, undo

• Names of form 'key<n>' where <n> is 0-255 are interpretted as 
  key having hardware-dependent scan code of <n> (useful to bind 
  those keys that don't have symbolic names).

10.1.3 Joystick pseudo-keys:

• joystick<num>button<button>: Joystick <num> (0-based) button 
  <button> (0-based).

• joystick<num>hat<hat>n: Joystick <num> (0-based) hat <hat> 
  (0-based) up.

• joystick<num>hat<hat>w: Joystick <num> (0-based) hat <hat> 
  (0-based) left.

• joystick<num>hat<hat>s: Joystick <num> (0-based) hat <hat> 
  (0-based) down.

• joystick<num>hat<hat>e: Joystick <num> (0-based) hat <hat> 
  (0-based) right.

• joystick<num>axis<axis>-: Joystick <num> (0-based) axis <axis> 
  negative position (axis modes axis and axis_inverse).

• joystick<num>axis<axis>+: Joystick <num> (0-based) axis <axis> 
  positive position (axis modes axis and axis_inverse).

• joystick<num>axis<axis>: Joystick <num> (0-based) axis <axis> 
  pressure (axis modes pressure_*).

10.1.4 Special buttons:

• Escape: Enter/Exit Command mode, cancel modal dialogs.

• Return (also KPEnter): Execute command, ok modal dialog.

• Pgup/Up (also KP8/9 if no num lock; command mode): Previous 
  command in command history

• Pgdn/Down(also KP2/3 if no num lock; command mode): Next 
  command in command history

• Home (also KP7 if no num lock; command mode): Beginning of 
  command.

• End (also KP1 if no num lock; command mode): End of command.

• Left (also KP4 if no num lock; command mode): Move cursor left.

• Right (also KP6 if no num lock; command mode): Move cursor 
  right.

• Delete (also KP. if no num lock; command mode): Delete 
  character to right of cursor.

• Insert (also KP0 if no num lock; command mode): Toggle between 
  insert / overwrite modes.

• Backspace (command mode): Delete character to left of cursor.

• LCTRL+LALT+ESCAPE: Ungraceful shutdown (leaves dump 
  corrupted!).

10.2 wxWidgets platform

10.2.1 Modifier names:

Following modifier names are known:

• alt

• ctrl

• shift 

• meta

• cmd (Mac OS X only)

10.2.2 Key names:

Following key names are known:

• back, tab, return, escape, space, exclaim, quotedbl, hash, 
  dollar, percent, ampersand, quote, leftparen, rightparen, 
  asterisk, plus, comma, minus, period, slash, 0, 1, 2, 3, 4, 5, 
  6, 7, 8, 9, colon, semicolon, less, equals, greater, question, 
  at, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, 
  u, v, w, x, y, z, leftbracket, backslash, rightbracket, caret, 
  underscore, backquote, a, b, c, d, e, f, g, h, i, j, k, l, m, 
  n, o, p, q, r, s, t, u, v, w, x, y, z, leftcurly, pipe, 
  rightcurly, tilde, delete, start, lbutton, rbutton, cancel, 
  mbutton, clear, shift, alt, control, menu, pause, capital, end, 
  home, lefT, up, right, down, select, print, execute, snapshot, 
  insert, help, numpad0, numpad1, numpad2, numpad3, numpad4, 
  numpad5, numpad6, numpad7, numpad8, numpad9, multiply, add, 
  separator, subtract, decimal, divide, f1, f2, f3, f4, f5, f6, 
  f7, f8, f9, f10, f11, f12, f13, f14, f15, f16, f17, f18, f19, 
  f20, f21, f22, f23, f24, numlock, scroll, pageup, pagedown, 
  numpad_space, numpad_tab, numpad_enter, numpad_f1, numpad_f2, 
  numpad_f3, numpad_f4, numpad_home, numpad_left, numpad_up, 
  numpad_right, numpad_down, numpad_pageup, numpad_pagedown, 
  numpad_end, numpad_begin, numpad_insert, numpad_delete, 
  numpad_equal, numpad_multiply, numpad_add, numpad_separator, 
  numpad_subtract, numpad_decimal, numpad_divide, windows_left, 
  windows_right, windows_menu, command, special1, special2, 
  special3, special4, special5, special6, special7, special8, 
  special9, special10, special11, special12, special13, 
  special14, special15, special16, special17, special18, 
  special19, special20

11 Movie file format

Movie file is .zip archive in itself, normal ZIP archive tools 
work on it (note: If you recompress it, do not use compression 
methods other than store and deflate and especially do not use 
encryption of any kind).

11.1 Detecting clean start/SRAM/Savestate

• If file has member “savestate” it is savestate, otherwise:

• If file has members with names starting “moviesram.” it is 
  movie starting from SRAM, otherwise:

• It is movie starting from clear state.

11.2 Member: gametype

Type of game ROM and region (as one line). Valid values are:


+--------------+---------------------+--------+
|    Value     |       System        | Region |
+--------------+---------------------+--------+
+--------------+---------------------+--------+
|  snes_pal    |     Super NES       |  PAL   |
+--------------+---------------------+--------+
|   sgb_pal    |   Super Game Boy    |  PAL   |
+--------------+---------------------+--------+
|  snes_ntsc   |     Super NES       |  NTSC  |
+--------------+---------------------+--------+
|  sgb_ntsc    |   Super Game Boy    |  NTSC  |
+--------------+---------------------+--------+
|     bsx      | BS-X (non-slotted)  |  NTSC  |
+--------------+---------------------+--------+
| bsxslotted   |   BS-X (slotted)    |  NTSC  |
+--------------+---------------------+--------+
| sufamiturbo  |    Sufami Turbo     |  NTSC  |
+--------------+---------------------+--------+


Frame rates are:


+---------+-----------------+
| Region  | Framerate (fps) |
+---------+-----------------+
+---------+-----------------+
|  PAL    |   322445/6448   |
+---------+-----------------+
|  NTSC   | 10738636/178683 |
+---------+-----------------+


11.3 Member: port1

Contains type of port #1 (as one line). Valid values are 'none', 
'gamepad', 'multitap' and 'mouse'. If not present, defaults to 
'gamepad'.

11.4 Member: port2

Contains type of port #2 (as one line). Valid values are 'none', 
'gamepad', 'multitap', 'mouse', 'superscope', 'justifier' and 
'justifiers'. If not present, defaults to 'none'.

11.5 Member: gamename

Contains name of the game (as one line).

11.6 Member: authors

Contains authors, one per line. Part before '|' is the full name, 
part after is the nickname.

11.7 Member: systemid

Always “lsnes-rr1” (one line). Used to reject other saves.

11.8 Member: controlsversion

Always “0” (one line). Used to identify what controls are there.

11.9 Member: “coreversion”

Contains bsnes core version number (as one line).

11.10 Member: projectid

Contains project ID (as one line). Used to identify if two movies 
are part of the same project.

11.11 Member: {rom,slota,slotb}{,xml}.sha256

Contains SHA-256 of said ROM or ROM mapping file (as one line). 
Absent if corresponding file is absent.

11.12 Member: moviesram.<name>

Raw binary startup SRAM of kind <name>. Only present in 
savestates and movies starting from SRAM.

11.13 Member: saveframe

Contains frame number (as one line) of frame movie was saved on. 
Only present in savestates.

11.14 Member: lagcounter

Current value of lag counter (as one line). Only present in 
savestates.

11.15 Member: pollcounters

Contains poll counters (currently 100 of them), one per line. 
Each line is raw poll count if DRDY is set for it. Otherwise it 
is negative poll count minus one. Only present in savestates.

11.16 Member: hostmemory

Raw binary dump of host memory. Only present in savestates.

11.17 Member: savestate

The raw binary savestate itself. Savestate detection uses this 
file, only present in savestates.

11.18 Member: screenshot

Screenshot of current frame. Only present in savestates. First 2 
bytes are big-endian width of image, rest are 24-bit RGB image 
data. Height of image is inferred from the width and size of 
data.

11.19 Member: sram.<name>

Raw binary SRAM of kind <name> at time of savestate. Only present 
in savestates.

11.20 Member: input

The actual input track, one line per subframe (blank lines are 
skipped).

• If the first byte of each line is '.', ' ', <tab> or '|', then 
  the line is part of same frame as previous, otherwise it starts 
  a new frame.

• First subframe must start a new frame.

Length of movie in frames is number of lines in input file that 
start a new frame.

11.21 Member: rerecords

Contains textual base-10 rerecord count (as one line; emulator 
just writes this, it doesn't read it) + 1.

11.22 Member: rrdata

This member stores set of load IDs. There is one load ID per 
rerecord (plus one corresponding to start of project).

• This member constists of concatenation of records

• Each record is 2-36 bytes long and can represent 1-16,843,009 
  consequtive IDs.

• IDs are interpretted as 256-bit big-endian integers with 
  warparound.

• Initial predicted ID is all zeroes.

Format of each record is:

• 1 byte: Opcode byte. Bits 0-4 are prefix length (prefixlen), 
  bits 5-6 are count length (countlen). Bit 7 is unused.

• 32-prefixlen bytes of ID.

• countlen bytes of big-endian count (count).

Records are processed as follows:

• To form the first ID encoded by record, take the first 
  prefixlen bytes predicted ID and append the read ID value to 
  it. The result is the first ID encoded.

• If countlen is 0, record encodes 1 ID.

• If countlen is 1, record encodes 2+count IDs.

• If countlen is 2, record encodes 258+count IDs.

• If countlen is 3, record encodes 65794+count IDs.

• The new predicted ID is the next ID after last one encoded by 
  the record.

The number of rerecords + 1 is equal to the sum of number of IDs 
encoded by all records.

11.23 Member: starttime.second

Movie starting time, second part. Epoch is Unix epoch. Default is 
1,000,000,000.

11.24 Member: starttime.subsecond

Movie starting time, subsecond part. Unit is CPU clocks. Default 
is 0.

11.25 Member: savetime.second

Movie saving time, second part. Default is starttime.second. Only 
present in savestates.

11.26 Member: savetime.subsecond

Movie saving time, subsecond part. Default is 
starttime.subsecond. Only present in savestates.

12 Quick'n'dirty encode guide

1. Start the emulator and load the movie file.

2. Set large AVI option 'set-setting avi-large on'

3. Enable dumping 'dump-avi tmpdump' 

4. Unpause and let it run until you want to end dumping.

5. Close the emulator (closing the window is the easiest way). Or 
  use 'end-avi'.

6. For each tmpdump*.avi file created, on command prompt, do 
  'x264 --crf 10 -o tmpdump_<numbers>.mkv tmpdump_<numbers>.avi'.

7. Do 'sox tmpdump.sox tmpdump.ogg rate -v 32000'

8. Do 'mkvmerge -o tmpdump_video.mkv tmpdump_0000000.mkv + 
  tmpdump_0000001.mkv + tmpdump_0000002.mkv' (list every 
  tmpdump_<numbers>.mkv, with + in between).

9. Do 'mkvmerge -o final.mkv tmpdump_video.mkv tmpdump.ogg'. Now 
  final.mkv contains quick'n'dirty encode.

13 Axis configurations for some gamepad types:

13.1 XBox360 controller:

Axes 2 and 5 (joystick<n>axis2 and joystick<n>axis5) should be 
set to pressure-+.

set-axis joystick0axis2 pressure-+

set-axis joystick0axis5 pressure-+

• This is needed for SDL only. EVDEV sets those types correctly.

13.2 PS3 “sixaxis” controller:

Axes 8-19 should be disabled.

set-axis joystick0axis8 disabled

set-axis joystick0axis9 disabled

set-axis joystick0axis10 disabled

set-axis joystick0axis11 disabled

set-axis joystick0axis12 disabled

set-axis joystick0axis13 disabled

set-axis joystick0axis14 disabled

set-axis joystick0axis15 disabled

set-axis joystick0axis16 disabled

set-axis joystick0axis17 disabled

set-axis joystick0axis18 disabled

set-axis joystick0axis19 disabled

14 Errata:

14.1 Problems from BSNES core:

• The whole pending save stuff.

• Lack of layer hiding.

• It is slow (especially accuracy).

• Firmwares can't be loaded from ZIP archives.

14.2 Other problems:

• Modifiers don't work with pseudo-keys (SDL, EVDEV).

• Audio for last dumped frame is not itself dumped.

• Audio in UI is pretty bad in quality if game doesn't run at 
  full speed.

• AVI compression levels 10-18 are not compatible with AVISynth 
  AVISource.

• No menus, command based interface (SDL).

• Long commands don't scroll.

• Wxwidgets UI is still buggy.

15 Changelog:

15.1 rr0-beta1

• Fix -Wall warnings

• Fix dumper video corruption with levels 10-18.

15.2 rr0-beta2

• Autofire

• Lots of code cleanups

• Lua interface to settings

• Allow specifying AVI borders without Lua

• Fix scaling if vscale > 1 and originx > 0 (left border exists)

• on_snoop lua callback

• Faster movie loading and saving.

15.3 rr0-beta3

• Joystick support

15.4 rr0-beta4

• Fix multi-buttons

• Save jukebox functionality.

15.5 rr0-beta5

• Try to fix some nasty failing movie load edge cases

• Allow specifying scripts to run on command line.

15.6 rr0-beta6

• Major source code reorganization.

• Backup savestates before overwriting.

• Don't crash if loading initial state fails.

15.7 rr0-beta7

• Fix firmware lookup

• Fix author name parsing

• Fix rerecord counting

• (SDL) Print messages to console if SDL is uninitialized

• Add movieinfo program

• Fix loading movies starting from SRAM.

15.8 rr0-beta8

• Add support for unattended dumping

• Fix compiling for Win32

• Don't lock up if sound can't be initialized

• Strip trailing CR from commands

• Don't try to do dubious things in global ctors (fix crash on 
  startup)

15.9 rr0-beta9

• Small documentation tweaking

• Fix make clean

• Fix major bug in modifier matching

15.10 rr0-beta10

• Lots of documentation fixes

• Use dedicated callbacks for event backcomm., not commands.

• Ensure that the watchdog is not hit when executing delayed 
  reset.

• Remove errant tab from joystick message.

15.11 rr0-beta11

• Make autofire operate in absolute time, not linear time

• Reinitialize controls when resuming from loadstate

• Some more code cleanups

• If Lua allocator fails, call OOM_panic()

• Byte/word/dword/qword sized host memory write/read functions.

• Dump at correct framerate if dumping interlaced NTSC 
  (height=448).

15.12 rr0-beta12

• Actually include the complete source code

• Keep track of RTC

15.13 rr0-beta13

• Document {save,start}time.{,sub}second.

• Intercept time() from bsnes core.

15.14 rr0-beta14

• Allow disabling time() interception (allow build on Mac OS X)

• Use SDLMain on Mac OS X (make SDL not crash)

• Disable delayed resets (just plain too buggy for now).

• Code cleanups

• Use 16-bit for graphics/video instead of 32-bit.

• gui.rectangle/gui.pixel

• gui.crosshair

• New CSCD writer implementation.

15.15 rr0-beta15

• Fix interaction of * and +.

• Manual improvements

• Use gettimeofday()/usleep(), these seem portable enough.

• Move joystick axis manipulation to keymapper code.

• Changes to how read-only works.

• Refactor controller input code.

15.16 rr0-beta16

• Fix mouseclick scale compensation.

• Draw area boundaries correctly in SDL code.

• gui.screenshot.

• Fix CSCD output (buffer overrun and race condition).

15.17 rr0-beta17

• JMD dumping support.

• Allow unattended dumping to JMD.

• Move to BSNES v083.

• Switch back to 32-bit colors.

• Add Lua function gui.color.

• Use some new C++11 features in GCC 4.6.

• Be prepared for core frequency changes.

• Pass colors in one chunk from Lua.

15.18 rr0-beta18

• New lua functions gui.line(), gui.status() and gui.circle(), 
  memory.vma_count(), memory.read_vma() and memory.find_vma().

• Numerious documentation fixups

• RTC time format changed

• Reformat flags display

• Allow lua package name to be overridden

• SDUMP (high-quality dumping).

• Split platform support to plugins.

• Make all sound plugins support basic sound commands

• Support portaudio for sound.

• Allow disable Lua/SDL searching.

• Upconvert colors when copying lcscreen to screen.

• Reorganize source tree.

• Evdev joystick support.

• Refactor more code into generic window code.

15.19 rr0-beta19

• Refactor message handling.

• Rework makefile

• Documentation fixes

• Finish pending saves before load/quit.

• Wxwidgets graphics plugin.

15.20 rr0-beta20

• Get rid of win32-crap.[ch]pp.

• Move files around a lot.

• Get rid of need for host C++ compiler.

• Bsnes v084 core.

• Refactor inter-component communication.

• Fix zero luma.

• Fix crash on multiline aliases.

• Load/Save settings in wxwidgets gui.

15.21 rr0-beta21

• Patch problems in bsnes core

• SNES is little-endian, not big-endian!

• Fix memory corruption in lcscreen::load()

15.22 rr0-beta22

• Fix interpretting repeat counts in rrdata loading.

• New lua callback: on_frame()

• Remove calls to runtosave() that aren't supposed to be there

• Lua function: movie.read_rtc()

• Ignore src/fonts/font.cpp

• Fix more bsnes core problems

• Control bsnes random seeding

• Pause-on-end

• Some bsnes core debugging features (state dump and state hash)

• Fix titlebar version number (no, the last version wasn't 
  'lsnes-0-beta21', it was 'lsnes rr0-beta21').

15.23 rr0-beta23

• Fix memory corruption due to macro/field mixup

• search-memory update

• Allow direct-mapped framebuffer

• SDL: Use SDL_ANYFORMAT if possible

• SDMP2SOX: 2s delay modes.

• Wxwidgets: Cleanups

• Use sed -E, not sed -r. Fixes building on Mac OS X.

• Wxwidgets: Save jukebox on exit

• Fix RTC if using load-movie on savestate.

• Fix crash related to full console mode.

15.24 rr0-beta24

• Wxwidgets: Allow bringing application to foreground on Mac OS 
  X.

• Wxwidgets: Allow compiling on Mac OS X.

• Use movie compare instead of movie hashing (faster save/load).

• Lua: _SYSTEM table.

15.25 rr0-beta25

• sdmp2sox: Pad soundtrack if using -l or -L.

• sdmp2sox: Fix NTSC overscan.

• sdmp2sox: Add AR correction mode.

• call lua_close() when exiting.

• Fix zip_writer bug causing warnings from info-zip and error 
  from advzip.

15.26 rr0-beta26

• Fix IPS patching code (use bsnes core IPS patcher).

• Implement BPS patching (using bsnes core IPS patcher).

• Add feature to load headered ROMs.

15.27 rr0-beta27

• Show command names when showing keybindings

15.28 rr0

• Fix pause-on-end to be actually controllable

• SDL: Poll all events in queue, not just first one (fixes 
  slowness in command typing)

• Wxwidgets: Fix ROM loading.

15.29 rr1-beta0

• Lua: Add gui.textH, gui.textV, gui.textHV

• Fix text colors on SDL on Mac OS X

• Mode 'F' for finished in readonly mode.

• Fix some WS errors.

• Reliably pause after skip poll

• Split UI and core into their own threads

15.30 rr1-beta1

• Remove leftover dummy SRAM slot

• Fix controller numbers.

15.31 rr1-beta2

• Fix lsnes-dumpavi after interface change.

• Also give BSNES patches for v085.

• Pack movie data in memory.

15.32 rr1-beta3

• Fix framecount/length given when loading movies.

• Controller command memory leak fixes.

• Don't leak palette if freeing screen object.

15.33 rr1-beta4

• Detect revisions.

• Wxwidgets: Allow controlling dumper from the menu.

15.34 rr1-beta5

• Rewrite parts of manual

• Lua: Make it work with Lua 5.2.

15.35 rr1-beta6

• Win32: Fix compile errors.

15.36 rr1-beta7

• Refactor controller input code.

• Fix crash when using command line on SDL / Mac OS X.

15.37 rr1-beta8

• Delete core/coroutine (obsolete)

• Lag input display by one frame.

• Rewind movie to beginning function.

• Fix wrong frame number reported to Lua when repainting after 
  loadstate

• Support UI editing of jukebox

• Wxwidgets: Save settings on exit.

• Support ${project} for filenames

• SDL: Fix command history

15.38 rr1-beta9

• Fix some order-of-global-ctor bugs.

15.39 rr1-beta10

• Fix crashes when quitting on Win32.

15.40 rr1-beta11

• EVDEV: Queue keypresses from joystick, don't send directly

• Wxwidgets: Load-Preserve that actually works.

15.41 rr1-beta12

• Wxwidgets: GUI for memory search.

• Warn about using synchronous queue in UI callback.

15.42 rr1-beta13

• Remember last saved file for each ROM

• Support MT dumping via boost.

• Lua: input.raw

• Lua: input.keyhook

• Make mouse be ordinary input instead of special-casing

• SDL: Don't screw up commands with NUL codepoints.

15.43 rr1-beta14

• Merge status panel and main window

• True movie slot support (the rest of it)

• SDL: Fix compilation error

• Elminate cross calls in dump menu code.

15.44 rr1-beta15

• Cancel pending saves command

• Wxwidgets: Code refactoring

• Wxwidgets: Fix system -> reset

• Wxwidgets: Read watch expressions in the right thread

15.45 rr1-beta16

• Wxwidgets: Don't prompt for member when running Lua script (Lua 
  doesn't support that).

• Wxwidgets: 128 -> 1024 Autohold slots (in case more are 
  needed).

• Don't append trailing '-' to prefix when saving movie.

• Fix ROM/savestate handling (don't let user mismatch ROM and 
  savestates).

15.46 rr1

• Document memory watch syntax.

15.47 rr1-delta1

• Fix unattended dumping (lsnes-dumpavi)

• Support RAW dumping

• Use adv_dumper instead of the old interface in lsnes-dumpavi 
  (changes syntax)

• Add option to control sample rate preturbation in AVI dumper

15.48 rr1-delta2

• Wxwidgets: Fix dumper submodes

• Set core controller types before loadstate

15.49 rr1-delta2epsilon1

• Fix compiling with bsnes v086.

15.50 rr1-delta3

• Don't prompt before quitting

• Start unpaused, preserve pause/unpause over load.

• Try to autodetect if ROM is headered.

• Wxwidgets: Only bring up ROM patching screen if specifically 
  requested.

• Allow configuring some hotkeys.

15.51 rr1-delta4

• Lots of code cleanups

• Fix JMD compression (JMD dumping was broken)

• Don't crash if Lua C function throws an exception.

• Support bitmap drawing in Lua.

• Fix bsnes v085/v086 patches.

• Improve stability on win32.

15.52 rr1-delta4epsilon1

• Don't corrupt movie if movie length is integer multiple of 
  frames per page.