<pclass="rvps2"><spanclass="rvts6">Lua is a scripting language. It is used in games like Farcry and World of Warcraft (and many other games and applications!). Even though you can find all kinds of tutorials online, let me help you with the basics.</span></p>
<pclass="rvps2"><spanclass="rvts6">I will assume you are at least somewhat familiar with the basics of programming. So basic stuff like arrays, variables, strings, loops and if-then-else and branching are not explained here.</span></p>
<pclass="rvps2"><spanclass="rvts6">When you load the script, the emulator will sort of go into pause mode and hand controls over to Lua (you!). Hence you are responsible for frameadvancing the emulator.</span></p>
<pclass="rvps2"><spanclass="rvts6">IF YOU DO NOT CALL emu.frameadvance AT THE CYCLE OF THE MAIN LOOP YOU WILL FREEZE THE EMULATOR! There. You have been warned. Don't worry though, you'll make this mistake at least once. Just force-quit the application and try again :)</span></p>
<pclass="rvps2"><spanclass="rvts6">First of all, if's require a then and end. After a couple of days intensive Lua coding, I still make this mistake myself, but the Lua interpreter will prompt you of such errors on load, so don't worry too much about it. So:</span></p>
<pclass="rvps2"><spanclass="rvts6">There are only two values that evaluate to "false", these are "nil" and "false". ANYTHING else will evaluate to true, even 0 or the empty string.</span></p>
<pclass="rvps2"><spanclass="rvts6">Comments are denoted by two consecutive dashes; --. Anything after it on the same line is a comment and ignored by Lua. There is no /* */ type of commenting in Lua.</span></p>
<pclass="rvps2"><spanclass="rvts6">Variables have a local and global scope. You explicitly make a variable local by declaring it with the "local" keyword.</span></p>
<pclass="rvps2"><spanclass="rvts6">Do not rely on the table.length() when your table can contain nil values, this function stops when it encounters a nil value, thus possibly cutting your table short.</span></p>
<pclass="rvps2"><spanclass="rvts6">One experienced programmers will have to get used to is the table offset; tables start at index 1, not 0. That's just the way it is, deal with it.</span></p>
<pclass="rvps2"><spanclass="rvts6">When using the colon notation ":" Lua will call the function adding the self-reference to the front of the parameterstack.</span></p>
<pclass="rvps2"><spanclass="rvts6">For comparison, you only have to remember that the exclamationmark is not used. Not equal "!=" is written like tilde-equals "~=" and if (!something) then ... is written with "not " in front of it; if (not something) then...</span></p>
<pclass="rvps2"><spanclass="rvts6">For easy reference to the standard libraries look on the bottom half of this page: http://www.lua.org/manual/5.1/</span></p>
<pclass="rvps2"><spanclass="rvts6">To load a Lua script in FCEU first load a rom (Lua can only do things after each frame cycle so load a rom first). Go to file, at the bottom choose Run Lua Script and select and load the file.</span></p>
<pclass="rvps2"><spanclass="rvts6">When Lua starts, the emulator pauses and hands control over to Lua. Lua (that's you!) decides when the next frame is processed. That's why it's very common to write an endless while loop, exiting the main loop of a script will exit the script and hand control back to the emulator. This also happens when a script unexpectingly crashes.</span></p>
<pclass="rvps2"><spanclass="rvts6">And is about equal to not running Lua at all. The frameadvance function is the same called internally, so no loss of speed there!</span></p>
<pclass="rvps2"><spanclass="rvts6">Lua does not have bitwise operators, so we supply some for you. These are common bitwise operators, nothing fancy.</span></p>
<pclass="rvps2"><spanclass="rvts6">The emulator specific Lua is equal to the one of snes9x, with some platform specific changes (few buttons, for instance). </span></p>
<pclass="rvps2"><spanclass="rvts6">You can find the reference here: </span><aclass="rvts96"href="http://dehacked.2y.net/snes9x-lua.html"target="_blank">http://dehacked.2y.net/snes9x-lua.html</a></p>
<pclass="rvps2"><spanclass="rvts6">To paint stuff on screen, use the gui table. This contains a few predefined functions to manipulate the main window. For any coordinate, 0,0 is the top-left pixel of the window. You have to prevent out-of-bound errors yourself for now. If a color can be passed on, it is a string. HTML-syntax is supported ("#34053D"), as well as a FEW colors ("red", "green", "blue" ...).</span></p>
<pclass="rvps2"><spanclass="rvts6">gui.text(x, y, str); -- Print a line to the window, you can use \n for a return but it will only work once</span></p>
<pclass="rvps2"><spanclass="rvts6">gui.pixel(x, y, color); -- plot a pixel at the given coordinate</span></p>
<pclass="rvps2"><spanclass="rvts6">gui.line(x1, y1, x2, y2, color); -- plot a line from x1,y1 to x2,y2</span></p>
<pclass="rvps2"><spanclass="rvts6">gui.box(x1, y1, x2, y2, color); -- draw a square from x1,y1 to x2,y2</span></p>
<pclass="rvps2"><spanclass="rvts6">gui.popup(str); -- pops up a messagebox informing the user of something. Real handy when debugging!</span></p>
<pclass="rvps2"><spanclass="rvts6">gui.getpixel(x,y); -- return the values of the pixel at given position. Returns three numbers of the emulator image before paiting is applied.</span></p>
<pclass="rvps2"><spanclass="rvts6">gui.gdscreenshot(); -- Takes a screen shot of the image and returns it in the form of a string which can be imported by the gd library using the gd.createFromGdStr() function</span></p>
<pclass="rvps2"><spanclass="rvts6">(for more gd functions see DeHackED's reference: http://dehacked.2y.net/snes9x-lua.html)</span></p>
<pclass="rvps2"><spanclass="rvts6">PAINTING IS ALWAYS ONE FRAME BEHIND! This is because the painting is done at the creation of the next frame, not while Lua is running.</span></p>
<pclass="rvps2"><spanclass="rvts6">emu.frameadvance(); -- advances emulation ONE frame</span></p>
<pclass="rvps2"><spanclass="rvts6">emu.pause(); -- same as pressing the pause button</span></p>
<pclass="rvps2"><spanclass="rvts6">emu.speedmode(strMode); -- Supported are "normal","turbo","nothrottle","maximum". But know that except for "normal", all other modes will run as "turbo" for now.</span></p>
<pclass="rvps2"><spanclass="rvts6">emu.wait(); -- skips the emulation of the next frame, in case your script needs to wait for something</span></p>
<pclass="rvps2"><spanclass="rvts6">memory.readbyte(adr); -- read one byte from given address and return it. Besides decimal values Lua also allows the hex notation 0x00FA. In FCEUX reading is done BEFORE the cheats are applied!</span></p>
<pclass="rvps2"><spanclass="rvts6">memory.writebyte(adr, value); -- write one byte to the RAM of the NES. writing is done AFTER the hexeditor receives its values, so if you are freezing an address by Lua, it will not show in the hex editor (but it will in the game :)</span></p>
<pclass="rvps2"><spanclass="rvts6">memory.readbytesigned(adr); -- same as readbyte, except this returns a signed value, rather then an unsigned value.</span></p>
<pclass="rvps2"><spanclass="rvts6">memory.register(adr, function); -- binds a function to an address. The function will be called when an address changes. NOTE THAT THIS IS EXPENSIVE (eg.: slow)! Only one function allowed per address.</span></p>
<pclass="rvps2"><spanclass="rvts6">You can read and write input by using the joypad table. A input table has the following (case sensitive) keys, where nil denotes they are not to be pressed: up down left right start select A B</span></p>
<pclass="rvps2"><spanclass="rvts6">joypad.read(playern); -- get the input table for the player who's input you want to read (a number!)</span></p>
<pclass="rvps2"><spanclass="rvts6">joypad.write(playern, inputtable); -- set the input for player n. Note that this will overwrite any input from the user, and only when this is used.</span></p>
<pclass="rvps2"><spanclass="rvts6">You can load and save to the predefined savestates 1 ... 9 or create new "anonymous" savestates. You must first create a savestate object, which is your handle to a savestate. Then you can pass this handle on to savestate.load or save to do so.</span></p>
<pclass="rvps2"><spanclass="rvts6">savestate.create(n); -- n is optional. When supplied, it will create a savestate for slot n, otherwise a new (anonymous) savestate object is created. Note that this does not yet save or load anything!</span></p>
<pclass="rvps2"><spanclass="rvts6">savestate.load(state); -- load the given savestate</span></p>
<pclass="rvps2"><spanclass="rvts6">savestate.save(state); -- save the given savestate</span></p>
<pclass="rvps2"><spanclass="rvts6">For an up-to-date list of functions, see the </span><aclass="rvts96"href="LuaFunctionsList.html">Lua Functions List</a><spanclass="rvts6">.</span></p>
<pclass="rvps4"style="clear: both;"><spanclass="rvts18">Created with the Personal Edition of HelpNDoc: </span><aclass="rvts19"href="https://www.helpauthoringsoftware.com">Benefits of a Help Authoring Tool</a></p>
