Basics

-- initialization goes here
while condition do
   -- Code executed once per frame
 
   snes9x.frameadvance()


end

-- Cleanup goes here

Base library

int AND(int arg1, int arg2, ..., int argn)

At a binary level, the AND of two binary bits is 1 if both inputs are 1, and the output is 0 in any other case. Commonly used to test if a bit is set by ANDing with a number with only the desired position set to 1.

int OR(int arg1, int arg2, ..., int argn)

int XOR(int arg1, int arg2, ..., int argn)

int BIT(int which)

... Actually this system will accept a range of 0 to 30, but none of the memory access functions will accept it, so you're on your own for those. 31 is not allowed for now due to signedness risking wreaking havoc.

snes9x

snes9x.speedmode(string mode)

• normal sets to normal operation. The game runs at its normal speed. Speed control (eg: 50%) apply.
• nothrottle makes snes9x run at maximum CPU speed while still showing each frame on screen.
• turbo drops some frames. It looks like high speed fast-forwarding.
• maximum disables screen rendering

snes9x.frameadvance()

Warning: Due to the way the code is written, the times this function may be called is restricted. Norably, it must not be called within a coroutine or under a [x]pcall(). You can use coroutines for your own purposes, but they must not call this function themselves. Furthermore, this function cannot be called from any "registered" callback function. An error will occur if you do.

snes9x.message(string msg)

snes9x.pause()

This function is allowed to be called from outside a frame boundary (ie. when it is not allowed to call snes9x.frameadvance). In this case, the function does not wait for the pause because you can't pause midway through a frame. Your code will continue to execute and the emulator will be paused at the end of the current frame. If you are at a frame boundary, this function acts a lot like snes9x.frameadvance() plus the whole pause thing.

It might be smart to reset the speed mode to "normal" if it is not already so.

snes9x.wait()

If you're not sufficiently confused yet, think of this as pausing for one frame.

If you need to do a large amount of calculations -- so much that you risk setting off the rampant script warning, just call this function every once in a while.

Might want to avoid using this if you don't need to. If the emulator is running at normal speed, paused and the user presses frame-advance, they might be confused when nothing happens.

memory

int memory.readbyte(int address)
int memory.readword(int address)

int memory.readbytesigned(int address)
int memory.readwordsigned(int address)

memory.writebyte(int address, int value)
memory.writebyte(int address, int value)

memory.register(int address, function func)

Only one function can be registered with a memory address. 16 bit writes will only trigger the lower address listener. There is no distinction between 8 and 16 bit writes. func may be nil in order to delete a function from listening.

Code called may not call snes9x.frameadvance() or any savestate save/load functions, and any button manipulation results are undefined. Those actions are only meaningful at frame boundaries.

joypad

Joypads are numbered 1 to 5.

Joypad buttons are selected by use of a table with special keys. The table has keys start, select, up, down, left, right, A, B, X, Y, L, R. Note the case is sensetive. Buttons that are pressed are set to a non-nil value (use of the integer 1 is just a convention). Note that "false" is valid, but discouraged as testing for logical true will fail.

Currently reading input from a movie file is not possible, but a movie will record button presses from Lua.

table joypad.read(int which)

joypad.set(int which, table buttons)

savestate

Each object is basically a savestate file. Anonymous savestates are saved to your temp directory.

object savestate.create(int userslot=nil)

Each call to savestate.create() (without parameters) returns a unique savestate. As such, if you discard the contents of a variable containing an important savestate, you've just shot yourself in the foot.

An object may be used freely once created, saved over and loaded whenever.

It is an error to load an anonymous (non-player accessbile) state that has not been saved yet, since it's empty.

Each savestate uses about 120 KB of disk space and the random filename generator has its limits with regards to how many filenames it can generate. Don't go too overboard. If you need more than 1000 savestates, maybe you should rethink your tehcnique. (The actual windows limit is about 32768, Linux is higher).

savestate.save(object state)

savestate.load(object state)

function savestate.registersave(function save)

The function called is permitted to return any number of string and number values. Lua lets you do this by simply writing return 1, 2, 3, "four and five", 6.2, integerVar

These variables must be numeric or string. They will be saved into the savestate itself and returned back to the application via savestate.registerload() should the state ever be loaded again later.

Only one function can be registered. Registering a second function will cause the first function to be returned back by savestate.registersave() before being discarded.

Savestates created with this mechanism are likely to break some savestate features in other emulators. Don't be surprised if savestates from this version don't work on others if you enable all those fancy features. Compatible savestates are created if there is no registered save function, or if the save function returns no parameters at all.

function savestate.registerload(function load)

Concept code:

function saveState() .... end
function loadState(arg1, arg2, ...)  ... end

savestate.registersave(saveState)
savestate.registerload(loadState)


-- Behind the scenes
local saved_variables 



-- User presses savestate
saved_variables = { saveState() } -- All return values saved


-- Time passes
-- ...


-- User presses loadstate
loadState(unpack(saved_variables))

Recommendations for registered savestates

• You may want to reserve the first parameter as a sort of key to make sure that the right script or the correct revision of a script is receiving its data.
• The order of declarations in your script should be local variables, then functions (inclduing these), then any registration calls, and then your main loop. Code is executed top-to-bottom, and that includes variables being prepared as locals, functions created, etc.
• You can build a string using string.char() from bytes and disassemble one from string.byte(). If you need to store a table's worth of data, you'll have to do this.

movie

int movie.framecount()

string movie.mode()

movie.rerecordcounting(boolean counting)

This will automatically be set to true after a script finishes running, so don't worry about messing up the rerecord count for the player.

movie.stop()

gui

The SNES uses a 16 bit colour system. Red and blue both use 5 bits (0 through 31) while green uses 6 bits (0 through 63), in place of the usual 0 to 255 range. If you want to construct your own exact colours, multiply your red value by 2048, your green value by 32 and leave your blue value untouched. Add these all together to get a valid colour. Bright red would be 31*2048 = 63488, for example.

Some strings are accepted. HTML style encoding such as "#00ff00" for green is accepted. Some simple strings such as "red", "green", "blue", "white" and "black" are also accepted.

The transparent colour is 1 (a VERY dark blue, which is probably not worth using in place of black) or the string "clear". Remove drawn elements using this colour.

Output is delayed by a frame. The graphics are drawn on a separate buffer and then overlayed on the image during the next refresh, which means allowing for a frame to execute. Also, the buffer is cleared after drawing, so if you want to keep something on screen, you must keep drawing it on each frame.

It is an error to draw outside the drawing area. gdoverlay is the only exception to this rule - images will be clipped to the visible area.

r,g,b = gui.getpixel(int x, int y)

gui.drawpixel(int x, int y, type colour)

gui.drawline(int x1, int y1, int x2, int y2, type colour)

gui.drawbox(int x1, int y1, int x2, int y2, type colour)

gui.text(int x, int y, string message)

The coordinates determine the top-left corner of the box that the text fits in. The font is the same one as the snes9x messages, and you can't control colours or anything. :(

The minimum y value is 9 for the font's height and each letter will take around 8 pixels of width. Text that exceeds the viewing area will be cut short, so ensuring your text will fit would be wise.

string gui.gdscreenshot()

This function is provided so as to allow snes9x to not carry a copy of the gd library itself. If you want raw RGB32 access, skip the first 11 bytes (header) and then read pixels as Alpha (always 0), Red, Green, Blue, left to right then top to bottom, range is 0-255 for all colours.

Warning: Storing screen shots in memory is not recommended. Memory usage will blow up pretty quick. One screen shot string eats around 230 KB of RAM.

gui.gdoverlay(int x=0, int y=0, string gdimage)

Naturally, the format for input is the gd file format, version 1. The image MUST be truecolour.

The image will be clipped to fit into the screen area.

gui.transparency(int strength)

All image drawing (including gui.gdoverlay) will have the given transparency level applied from that point on. Note that drawing on the same point over and over will NOT build up to a higher opacity level.

function gui.register(function func)

This function is not necessarily complicated to use, but it's not recommended to users new to the whole scripting thing.

You may pass nil as the parameter to kill off a registered function. The old function (if any) will be returned.

string function gui.popup(string message, [string type = "ok"])

Linux users might want to install xmessage to perform the work. Otherwise the dialog will appear on the shell and that's less noticable.