View Page Source

Lua scripting is an extremely useful tool when TASing. Although some programming knowledge is required, the user has power over things like game screen display, inputs, and memory. The following are some common applications, though the possibilities are endless.
*Displaying helpful information on screen.
*Eliminating tedious repetition.
*Creating specific circumstances for testing.
*Brute forcing a solution.

[EmulatorResources/Snes9x|Snes9x] was the first emulator modified to support Lua, back in 2008. Now, the following emulators support Lua: [EmulatorResources/FCEUX|FCEU(X)], [BizHawk], [EmulatorResources/Lsnes|lsnes], [EmulatorResources/Snes9x|Snes9x], [EmulatorResources/Gens|Gens], [EmulatorResources/VBA|VBA], [EmulatorResources/Fbarr|Final Burn Alpha], [EmulatorResources/PCSX|PCSX], [EmulatorResources/Desmume|DeSmuME], [EmulatorResources/Pcejin|PCEjin], [EmulatorResources/Vbjin|VBjin], [EmulatorResources/JPC|JPC-RR], and [EmulatorResources/Mamerr|MAME].

In order to integrate Lua, a number of emulator-specific functions were created, which form the emulator-specific Lua API, enabling control of the emulator. However, one is not limited only to emulator-specific Lua functions. Anyone can use any function in the main Lua API, including file I/O. Thus the emulator can be scripted to communicate with, say, text files!

!! How to run a Lua script

To run a Lua script, copy the code and place it in a text editor. Name the file as "file.lua" or anything ending in "lua". When saving from Notepad in Windows, you need to put quotes around the name {{"file.lua"}}. 

Then go to the emulator and run the Lua file. Some emulators have a Lua script window; the Lua script will automatically begin when you load it.

!! Basics

To become familiar with Lua, check out the [http://www.lua.org/manual/5.4/|Lua 5.4 manual]. It covers how the Lua language works, and the main Lua API.

In the emulator, it is desirable to have a main execution loop. The main execution loop can take one of two forms (-- means the rest of the line is a comment):

%%SRC_EMBED lua
--Declarations here
while true do
    --Statements
emu.frameadvance()
end
%%END_EMBED

and

%%SRC_EMBED lua
--Declarations here
function fn()
    --Statements
end

gui.register(fn)
%%END_EMBED

The second one is technically a function which is called whenever there is an update to the display (which is supposed to be every frame but is also called in some emulators[#1] during when the display is paused). The second form is required for DeSmuME since the first form is working in a different way than most other emulators (see [Forum/Topics/18798|this topic] for more information).

*[LuaScripting/Registers|Registers] - run functions during specific events, includes advancing a frame, state save/load, etc.
*[LuaScripting/Display|Display] - drawing, memory observation, etc.
*[LuaScripting/Macros|Macros]
** [LuaScripting/TableKeys] - controlling input, includes autohold and autofire)
*[LuaScripting/MemoryEditing|Memory Editing]

[TODO]

* To be covered
** joypad.set
** savestate.create , savestate.load , savestate.save
** FCEU.pause  
** FCEU.speedmode
** io.write , io.output

!!Using MHS for emulators without lua embedded

[http://memoryhacking.com/download.php|L. Spiro's Memory Hacking Software]

*To be covered
**(Be sure to note that position values are most often floating point data types.)

!!More information

! Site Links

* [Bizhawk/LuaFunctions|Lua Functions for BizHawk emulator]
* [EmulatorResources/Lsnes/LuaFunctions|Lua Functions for lsnes emulator]
* [EmulatorResources/Snes9x/LuaFunctions|Lua Functions for Snes9x emulator]
* Check out for some [/HomePages/Bisqwit/LuaFunctions|more complicated] Lua applications by [user:Bisqwit].

! External Links

* [https://github.com/TASEmulators/snes9x-rr/wiki/Lua-Functions|Snes9x Lua function library] ([http://code.google.com/p/snes9x-rr/wiki/LuaScriptingFunctions|old archive])
* [http://code.google.com/p/vba-rerecording/wiki/LuaScriptingFunctions|VBA Lua function library]
* [https://github.com/TASEmulators/mame-rr/wiki/Lua-scripting-functions|MAME Lua function library]
* [https://github.com/TASEmulators/gens-rerecording/blob/master/Gens-rr/src/luascript.cpp|Gens Lua function library] (TODO: make a proper wiki documenting the functions)
* [http://dehacked.2y.net/snes9x-lua/|DeHackEd's sample Lua scripts]

----

[1]: This is known to occur in FCEUX, PCSX, and DeSmuME.