<html><head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"><title>Snes9x Lua Library</title></head><body>
This is the API from DeHackEd's version of Lua in ZSnes. At the time of writing, FCUE's Lua was based on this API.<br /><br />
<h1>Basics</h1>
Your code will be run alongside the emulator's main loop. You code should
probably look roughly like this:
<hr>
<pre>-- initialization goes here
while condition do
-- Code executed once per frame
snes9x.frameadvance()
end
-- Cleanup goes here
</pre><hr>
When Lua execution starts, the emulator will be automatically unpaused if it
is currently paused. If so, it will automatically be paused when the script
exits, voluntarily or otherwise. This allows you to have a script execute
some work on your behalf and then when it exits the emulator will be paused,
ready for the player to continue use.
<br>
<h1>Base library</h1>
Handy little things that are not put into a class. Mostly binary operations right now.
<hr>
<a name="AND">
</a><pre><a name="AND">int AND(int arg1, int arg2, ..., int argn)</a></pre>
<a name="AND">Since Lua lacks binary operators and since binary will come up with memory manipulation,
I offer this function. Output is the binary AND of all its parameters together.
Minimum 1 argument, all integers.
</a><p>
<a name="AND">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.
</a></p><hr>
<a name="OR">
</a><pre><a name="OR">int OR(int arg1, int arg2, ..., int argn)</a></pre>
<a name="OR">The OR of two bits is 1 if either of the inputs is 1, and 0 if both inputs are 0.
Typically used to force a single bit to 1, regardless of its current state.
</a><hr>
<a name="XOR">
</a><pre><a name="XOR">int XOR(int arg1, int arg2, ..., int argn)</a></pre>
<a name="XOR">XOR flips bits. An even number of 1s yields a zero and an odd number of 1s yields a 1.
Commonly used to toggle a bit by XORing.
</a><hr>
<a name="BIT">
</a><pre><a name="BIT">int BIT(int which)</a></pre>
<a name="BIT">Returns a number with only the given bit set. <tt>which</tt> is in the range from 0 to 15 since the
SNES is a 16 bit system. <tt>BIT(15) == 32768</tt>
</a><p>
<a name="BIT">... 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.
</a></p><h1><a name="BIT">snes9x</a></h1>
<a name="BIT">Basic master emulator control.
</a><hr>
<a name="snes9x.speedmode">
</a><pre><a name="snes9x.speedmode">snes9x.speedmode(string mode)</a></pre>
<a name="snes9x.speedmode">Selects the speed mode snes9x should run at while Lua is in control of frame advance. It must be set to one of the following:
</a><ul>
<li><a name="snes9x.speedmode"><b><tt>normal</tt></b> sets to normal operation. The game runs at its normal speed. Speed control (eg: 50%) apply.</a></li>
<li><a name="snes9x.speedmode"><b><tt>nothrottle</tt></b> makes snes9x run at maximum CPU speed while still showing each frame on screen.
</a></li><li><a name="snes9x.speedmode"><b><tt>turbo</tt></b> drops some frames. It looks like high speed fast-forwarding.</a></li>
<li><a name="snes9x.speedmode"><b><tt>maximum</tt></b> disables screen rendering</a></li>
</ul>
<a name="snes9x.speedmode">In modes other than normal, pause will have no effect.
</a><hr>
<a name="snes9x.frameadvance">
</a><pre><a name="snes9x.frameadvance">snes9x.frameadvance()</a></pre>
<a name="snes9x.frameadvance">Snes9x executes one frame. This function pauses until the execution finishes. General system slowdown
when running at normal speed (ie. sleeping for 1/60 seconds) also occurs here when not in high speed mode.
</a><p>
<a name="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.
</a></p><p>
</p><hr>
<a name="snes9x.message">
</a><pre><a name="snes9x.message">snes9x.message(string msg)</a></pre>
<a name="snes9x.message">Displays the indicated string on the user's screen. snes9x.speedmode("normal") is probably the only way this is of any use,
lest the message not be displayed at all
</a><hr>
<a name="snes9x.pause">
</a><pre><a name="snes9x.pause">snes9x.pause()</a></pre>
<a name="snes9x.pause"><font color="#800000">v0.05+ only</font><br>
Pauses the emulator. This function blocks until the user unpauses.
</a><p>
<a name="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.
</a></p><p>
<a name="snes9x.pause">It might be smart to reset the speed mode to "normal" if it is not already so.
</a></p><hr>
<a name="snes9x.wait">
</a><pre><a name="snes9x.wait">snes9x.wait()</a></pre>
<a name="snes9x.wait"><font color="#800000">v0.06+ only</font><br>
Skips emulation of the next frame. If your script needs to wait for something to happen before proceeding (eg.
input from another application) then you should call this. Otherwise the GUI might jam up and your
application will not appear to be responding and need termination. It is expected that this function
will pause the script for 1/60 of a second without actually running the emulator itself, though it tends to be
OS-dependent right now.
</a><p>
<a name="snes9x.wait">If you're not sufficiently confused yet, think of this as pausing for one frame.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
</p><h1><a name="snes9x.wait">memory</a></h1>
<a name="snes9x.wait">Memory access and manipulation.
</a><pre><a name="snes9x.wait">int memory.readbyte(int address)
int memory.readword(int address)</a></pre>
<a name="snes9x.wait">Reads a number of bits (8 or 16) and returns the memory contents. The address must be a fully qualified
memory address. The RAM range is 0x7e0000 through 0x7fffff, but you may use any memory address, including
the ROM data itself.
</a><hr>
<pre><a name="snes9x.wait">int memory.readbytesigned(int address)
int memory.readwordsigned(int address)</a></pre><a name="snes9x.wait"><font color="#800000">v0.04+ only</font><br>
Same as its counterparts, except numbers will be treated as signed. Numbers larger than 127 for bytes and
32767 for words will be translated into the correct negative numbers. For reference, an alternate formula
is to subtract 256 for bytes and 65536 for words from any number equal to or larger than half that number.
For example, a byte at 250 becomes <tt>250-256 = -6</tt>.
</a><hr>
<pre><a name="snes9x.wait">memory.writebyte(int address, int value)
memory.writebyte(int address, int value)</a></pre>
<a name="snes9x.wait">Writes a number of bits (8 or 16) to the indicated memory address. The address MUST be in the range of
0x7e0000 through 0x7fffff.
</a><hr>
<pre><a name="snes9x.wait">memory.register(int address, function func)</a></pre>
<a name="snes9x.wait">When the given memory address is written to (range must be 0x7e0000 to 0x7fffff), the given function will be
called. The execution of the CPU will be paused mid-frame to call the given function.
</a><p>
<a name="snes9x.wait">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. <tt>func</tt> may be nil in order to
delete a function from listening.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
</p><h1><a name="snes9x.wait">joypad</a></h1>
<a name="snes9x.wait">Access to the gamepads. Note that Lua makes some joysticks do strange things.
Setting joypad inputs causes the user input for that frame to be ignored, but
only for that one frame.
</a><p>
<a name="snes9x.wait">Joypads are numbered 1 to 5.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
<a name="snes9x.wait">Currently reading input from a movie file is not possible, but
a movie will record button presses from Lua.
</a></p><pre><a name="snes9x.wait">table joypad.read(int which)</a></pre>
<a name="snes9x.wait">Returns a table indicating which buttons are pressed <i>by the user</i>.
This is probably the only way to get input to the script by the user.
This is always user input, even if the joypads have been set by joypad.set.
</a><hr>
<pre><a name="snes9x.wait">joypad.set(int which, table buttons)</a></pre>
<a name="snes9x.wait">Sets the buttons to be pressed. These choices will be made in place of
what the user is pressing during the next frame advance; they are then
discarded, so this must be called once every frame, even if you just want to
keep the same buttons pressed for several frames.
</a><p>
</p><h1><a name="snes9x.wait">savestate</a></h1>
<a name="snes9x.wait">Control over the savestate process. Savestate objects are opaque structures
that represent non-player accessible states (except for the functions that
return "official" savesates). Such an object is garbage collectable, in which
case the savestate is no longer usable. Recycling of existing savestate objects
is highly recommended for disk space concerns lest the garbage collector
grow lazy.</a><p>
<a name="snes9x.wait">Each object is basically a savestate file. Anonymous savestates are saved to
your temp directory.
</a></p><hr>
<pre><a name="snes9x.wait">object savestate.create(int userslot=nil)</a></pre>
<a name="snes9x.wait">Creates a savestate object for use. If the userslot argument
is given, the state will be accessible via the associated
F-key (F1 through F12 are 1 through 12). If not specified or
nil, an anonymous savestate is created that only Lua can access.
</a><p>
<a name="snes9x.wait">Each call to <tt>savestate.create()</tt> (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.
</a></p><p>
<a name="snes9x.wait">An object may be used freely once created, saved over and loaded whenever.
</a></p><p>
<a name="snes9x.wait">It is an error to load an anonymous (non-player accessbile) state that
has not been saved yet, since it's empty.
</a></p><p>
<a name="snes9x.wait">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. <small>(The actual windows limit is about 32768, Linux is higher).</small>
</a></p><hr><pre><a name="snes9x.wait">savestate.save(object state)</a></pre>
<a name="snes9x.wait">Saves the current state to the given object. Causes an error if something goes horribly
wrong, or if called within any "registered" callback function.
</a><hr><pre><a name="snes9x.wait">savestate.load(object state)</a></pre>
<a name="snes9x.wait">Loads the given state. Throws an error for all the same bad things that might happen.
</a><hr>
<pre><a name="snes9x.wait">function savestate.registersave(function save)</a></pre>
<a name="snes9x.wait"><font color="#800000">v0.06+ only</font><br>
Registers a function to be called on a savestate event. This includes both calls to
<tt>savestate.save()</tt> and users pressing buttons. The function will be called without
parameters.
</a><p>
<a name="snes9x.wait">The function called is permitted to return any number of string and number values.
Lua lets you do this by simply writing <tt>return 1, 2, 3, "four and five", 6.2, integerVar</tt>
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><hr>
<pre><a name="snes9x.wait">function savestate.registerload(function load)</a></pre>
<a name="snes9x.wait"><font color="#800000">v0.06+ only</font><br>
The companion to savestate.registersave, this function registers a function to be called during
a load. The function will be passed parameters -- exactly those returned by the function
registered for a save. If the savestate contains no saved data for your script, the function
will be called without parameters.
</a><p>
<a name="snes9x.wait">Concept code:
<font color="#000080">
<pre>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))
</pre></font>
</a></p><h2><a name="snes9x.wait">Recommendations for registered savestates</a></h2>
<ul><li><a name="snes9x.wait">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.</a></li>
<li><a name="snes9x.wait">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.</a></li>
<li><a name="snes9x.wait">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.</a></li>
</ul>
<p>
</p><h1><a name="snes9x.wait">movie</a></h1>
<a name="snes9x.wait">Access to movie information.
<br>
</a><hr>
<pre><a name="snes9x.wait">int movie.framecount()</a></pre>
<a name="snes9x.wait">Returns the current frame count, or nil if no movie is running.
</a><hr>
<pre><a name="snes9x.wait">string movie.mode()</a></pre>
<a name="snes9x.wait">Returns "record", "playback", or nil, depending on the current movie.
</a><hr>
<pre><a name="snes9x.wait">movie.rerecordcounting(boolean counting)</a></pre>
<a name="snes9x.wait">Select whether rerecording should be counted. If set to false, you can do
all the brute force work you want without inflating the rerecord count.
</a><p>
<a name="snes9x.wait">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.
</a></p><hr>
<pre><a name="snes9x.wait">movie.stop()</a></pre>
<a name="snes9x.wait">Stops movie recording/playback. I'm not sure why you'd want to do that, but you can.
</a><hr>
<!--
<pre>movie.record(string filename, boolean resetFirst = true, int players = 1)</pre>
Starts recording a movie with the indicated filename. Will throw an error if the file
already exists
<hr>
<pre>movie.playback(string filename, boolean readonly = true)</pre>
Starts playback of the given movie file. It is an error if the file does not already exist, is invalid, etc.
Specify readonly=true if savestates should be used for seeking during playback. If readonly=false,
loading a savestate will switch into recording mode.
<p>
The selection of readonly mode might affect the ability to open a file. readonly=true would successfully
play a file on a read-only medium (such as a CD) but readonly=false would fail.
-->
<h1><a name="snes9x.wait">gui</a></h1>
<a name="snes9x.wait"><font color="#800000">0.03+ only</font><br>
The ability to draw on the surface of the screen is a long sought feature. The surface is 256x239 pixels
(256x224 most of the time though) with (0,0) being in the top-left corner of the screen.
</a><p>
<a name="snes9x.wait">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 <tt>31*2048 = 63488</tt>, for example.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><p>
<a name="snes9x.wait">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.
</a></p><hr>
<pre><a name="snes9x.wait">r,g,b = gui.getpixel(int x, int y)</a></pre>
<a name="snes9x.wait">Returns the pixel on the indicated coordinate. (0,0) is the top-left corner and (255, 223) is the typical bottom-right corner,
though (255,238) is allowed. The return value range is (0,0,0) to (31,63,31). You get the actual screen surface before
any damage is done by your drawing. Well, unless you call snes9x.wait() in which case your damage is applied and the SNES
hardware doesn't get a chance to draw a new frame. :)
</a><hr>
<pre><a name="snes9x.wait">gui.drawpixel(int x, int y, type colour)</a></pre>
<a name="snes9x.wait">Draw a single pixel on the screen.
</a><hr>
<pre><a name="snes9x.wait">gui.drawline(int x1, int y1, int x2, int y2, type colour)</a></pre>
<a name="snes9x.wait">Draw a line between the two indicated positions.
</a><hr>
<pre><a name="snes9x.wait">gui.drawbox(int x1, int y1, int x2, int y2, type colour)</a></pre>
<a name="snes9x.wait">Draw a box going through the indicated opposite corners.
</a><hr>
<pre><a name="snes9x.wait">gui.text(int x, int y, string message)</a></pre>
<a name="snes9x.wait">Write text on the screen at the indicated position.
</a><p>
<a name="snes9x.wait">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. <tt>:(</tt>
</a></p><p>
<a name="snes9x.wait">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.
</a></p><hr>
<pre><a name="snes9x.wait">string gui.gdscreenshot()</a></pre>
<a name="snes9x.wait"><font color="#800000">0.04+ only</font><br>
Takes a screen shot of the image and returns it in the form of a string which can be imported by
the </a><a href="http://lua-gd.luaforge.net/">gd library</a> using the gd.createFromGdStr() function.
<p>
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.
</p><p>
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.
</p><hr>
<pre>gui.gdoverlay(int x=0, int y=0, string gdimage)</pre>
<font color="#800000">0.04+ only</font><br>
Overlays the given image on top of the screen with the top-left corner in the given screen location.
Transparency is not fully supported -- a pixel must be 100% transparent to actually leave
a hole in the overlayed image or else it will be treated as opaque.<p>
Naturally, the format for input is the gd file format, version 1. The image MUST be truecolour.
</p><p>
The image will be clipped to fit into the screen area.
</p><hr>
<pre>gui.transparency(int strength)</pre>
<font color="#800000">0.04+ only</font><br>
Transparency mode. A value of 0 means opaque; a value of 4 means invisible (useful option that one).
As for 1 through 3, I'll let you figure those out.<p>
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.
</p><hr>
<pre>function gui.register(function func)</pre>
<font color="#800000">0.04+ only</font><br>
Register a function to be called between a frame being prepared for displaying on your screen and
it actually happening. Used when that 1 frame delay for rendering is a pain in the butt.
<p>This function is not necessarily complicated to use, but it's not recommended to users
new to the whole scripting thing.
</p><p>
You may pass nil as the parameter to kill off a registered function. The old function (if any) will be
returned.
</p><hr>
<pre>string function gui.popup(string message, [string type = "ok"])</pre>
<font color="#800000">v0.05+ only</font><br>
Pops up a dialog to the user with a message, and returns after the user acknowledges the dialog.
<tt>type</tt> may be any of "ok", "yesno", "yesnocancel". The return value will be "yes", "no" or "cancel"
as the case may be. "ok" is a waste of effort.
<p>
Linux users might want to install xmessage to perform the work. Otherwise the dialog will
appear on the shell and that's less noticable.
</p></body></html>
