Lua Scripting

Foldit recipes can be written using Lua Scripting. Lua is a simple programming language. Like the simpler GUI recipes, recipes written in Lua contain a series of instructions or commands that tell Foldit what to do with your protein.

(Just as a real-life recipe has step-by-step instructions about how to combine ingredients to create a cake!)

Lua recipes have many features not found in GUI recipes. For one thing, more Foldit commands are available in Lua. Also, programming features, such as variables, if-then-else statements, while loops, and functions are available in Lua.

Lua scripting adds an exciting layer of gameplay to Foldit! Fortunately, Lua is easy enough to learn that everyone can use it, even people who have never programmed or scripted before. The best place to get started if you don't have any programming experience is to work through the Lua Scripting Tutorial (Beginner 1) (followed by Lua Scripting Tutorial (Beginner 2) and the upcoming Lua Scripting Tutorial (Beginner 3). If you're not interested in scripting yourself but just want to download and run other people's scripts, Beginner 1 is all you need! But if you want to go a bit further and modify scripts and write your own, you can move onto Beginner 2 and 3.

If, on the other hand, you have some programming experience or want to get a quicker start, begin with Lua Scripting Tutorial (Intermediate). This intermediate tutorial starts from the ground up and assumes no prior knowledge but moves through material at a more rapid pace, including basics about how to run and modify scripts as well as core programming concepts like looping and variables.

Another option for experienced programmers is to use the full Lua Interface listing (below) in combination with the Lua Reference Manual to learn the material on your own. If you already know how to program, you'll find that it's an simple issue of learning Lua's simple syntax and the Foldit command set. Additional resources for working with Lua are listed below, including guides to exporting and importing scripts and more!

There are two versions of the Foldit Lua interface. Version 1 was available early on, and Version 2 was added in 2011. Foldit player Tlaloc worked on the implementation of V2. While V1 is still supported, V2 should be used for new recipes.

Category-Script Tutorial

Resources

Cookbook / Recipe Scripting Tutorials

101 - Cookbook
Lua Scripting Tutorial (Beginner 1) (browsing, loading and running scripts, open output window)
Lua Scripting Tutorial (Beginner 2) (Lua commands)
Lua Scripting Tutorial (Beginner 3) (using game commands)
Lua Scripting Tutorial (Intermediate) (similar to Beginner 1-3, but more compact)
Lua Scripting Tutorial (Advanced) (using functions and tables)
User's Guide to Foldit Lua 2.0 API (blog entry by smith92clone )
Foldit Scripting Preview
Foldit Cookbook Scripting

Commands / Functions

Simplified List of Lua Commands
Foldit Lua Interface V1
Foldit Lua Functions (V2)
Lua Standard Libraries (V2)
Error Handling in Lua (V2)
Lua Script Library (useful functions you can add to your recipes)
Lua Export and Import of Scripts using Text and HEX editor
Lua Export and Import of Scripts using WORDPAD++
Lua Script Advice
Lua Functions that should be implemented
Foldit library for debugging

Recipes

External / Other

Lua Language

Here is a condensed summary of the keywords and operators available in Lua:

-- - use double dash to immediately precede comments on any line.

--[ [ x ] ] - multi-line comments provided by enclosing comment body in double brackets

+ (addition) - (negation/subtraction) * (multiplication) / (division) ^ (exponent) % (modulo) .. (string concatenation)

> < >= <= == ~= - relational operators

= - assignment. Note that Lua allows multiple assignments like a,b = 1,2.

a={} - creates empty table

a[1]=3; a["apple"]=4; a[12]="red" - sets some values in table

#a - indexing upward from zero, this returns the index of the last non-nil value. For example, if a[1] is nil, #a returns zero.

nil - a non-value that indicates non-existent variables

true false - Boolean values. Note everything except false and nil evaluates as true (including zero and empty string!)

and or not - Boolean operators

if then elseif else end - keywords for structuring if/then statements

while do end - keywords for while statement

repeat until - keywords for repeat statement

for i=1,N,delta do end - numeric "for" statement

for i in iterator(table) do end - generic "for" statement

break - terminates a loop

local - limits scope of variable to the current block. Use this in functions to avoid corrupting global variables.

function name(arg) return end - keywords for structuring function.

Note that functions can return multiple values. Functions can also take variable numbers of arguments by including an ellipsis at the end of the argument list. The following example illustrates this:

function test(...)
  local args={...}
  for i=1,#args do  print(args[i])  end
  return args[1], args[2]
end
a,b = test(1,2,3)

Foldit Lua Interface

There are two versions of the Foldit Lua interface, known as V1 and V2. The Lua language is the same in both versions, but the functions that work with Foldit are different.

The new version 2 (V2) of the Foldit Lua interface includes more functions than the original version. Unlike V1, the functions in V2 are grouped into namespaces. For example, all banding-related functions are now in the "band" namespace. In V1, each function stood on its own.

See Foldit Lua Functions for a complete list of the V2 functions.

The original version, now known as version 1 (V1), had a more limited set of functions with names like "do_global_wiggle". V1 is now obsolete, but Foldit continues to support recipes written using the V1 functions. See Foldit Lua Functions (v1) for a complete list of functions. All the V1 functions have V2 equivalents.