Changes: Lua Scripting

Latest revision as of 03:47, 24 March 2019

Recipe in NotepadPlusPlus — A recipe in Notepad++ (click for larger view). The print command and other Lua language features are automatically highlighted.

Foldit recipes can be written in Lua, a simple programming language. Lua is also used for scripting in World of Warcraft (WOW) and Angry Birds, although those scripts are no doubt very different than Foldit recipes.

Like GUI recipes, recipes written in Lua contain Foldit commands, such as shake and wiggle. Compared to GUI recipes, Lua recipes have many more Foldit commands available, and have much more flexibility in how the commands are used.

Lua recipes also use a full array of programming features, such as variables, if-then-else statements, loops, and functions, which are not available in GUI recipes.

The Foldit Lua Interface is the set of commands (functions) that a Lua recipe can use. Version 2 of the Foldit Lua interface has been available since 2011, and is the preferred version for new recipes. Recipes written using version 1 are still supported, but the command set of version 1 is not being updated. Version 1 recipes also don't have access to several Lua standard libraries, like "string" and "math".

Getting started[]

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 beginner scripting tutorials. Each of these tutorials also has a technical supplement with additional background information.

Tutorial	Tech Supplement
Beginner 1	Tech 1
Beginner 2	Tech 2
Beginner 3	Tech 3
Beginner 4	Tech 4
Beginner 5	Tech 5

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 just a matter 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.

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 tutorials, 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 Foldit Lua Functions (V1)
Foldit Lua Functions (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

Changes: Lua Scripting

Latest revision as of 03:47, 24 March 2019

Contents

Getting started[]

Resources[]

Cookbook / Recipe Scripting Tutorials[]

Commands / Functions[]

Recipes[]

External / Other[]

Lua Language[]

Foldit Lua Interface[]

@@ Line 1: / Line 1: @@
+[[File:Recipe_in_NotepadPlusPlus.png|thumb|400px|A recipe in Notepad++ (click for larger view). The print command and other Lua language features are automatically highlighted.]]
+Foldit [[Recipes|recipes]] can be written in [http://lua.org Lua], a simple programming language. Lua is also used for scripting in World of Warcraft (WOW) and Angry Birds, although those scripts are no doubt very different than Foldit recipes.
+Like [[Recipes#GUI_recipes|GUI recipes]], recipes written in Lua contain Foldit commands, such as [[Shake|shake]] and [[Wiggle|wiggle]]. Compared to GUI recipes, Lua recipes have many more Foldit commands available, and have much more flexibility in how the commands are used.
+Lua recipes also use a full array of programming features, such as variables, if-then-else statements, loops, and functions, which are not available in GUI recipes.
-== INTRODUCTION ==
+The [[Foldit Lua Interface]] is the set of commands (functions) that a Lua recipe can use. [[Foldit Lua Functions|Version 2]] of the  Foldit Lua interface has been available since 2011, and is the preferred version for new recipes. Recipes written using [[Foldit Lua Functions (v1)|version 1]] are still supported, but the command set of version 1 is not being updated. Version 1 recipes also don't have access to several Lua standard libraries, like "string" and "math".
-As you may know, the newest Fold-it update includes support for '''Lua Scripting'''. In very basic terms, '''Lua''' is a simple '''programming language''' that we can use to manipulate proteins and automate repetitive tasks -- much like we already do with the''' Cookbook.''' A '''script '''is actually quite similar to a Cookbook recipe (as well as to a real-life recipe for say, a cake) -- it contains a series of '''instructions''' (called '''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 scripting adds an exciting new layer of gameplay to Foldit!&nbsp; Fortunately, lua is easy enough to learn that everyone can use it, even people who have never programmed or scripted before.&nbsp; 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!&nbsp; But if you want to go a bit further and modify scripts and write your own, you can move onto Beginner 2 and 3.
+==Getting started==
+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 beginner scripting tutorials. Each of these tutorials also has a technical supplement with additional background information.
+{| class="wikitable"
+!Tutorial
+!Tech<br>Supplement
+|- align="center"
+|[[Lua_Scripting_Tutorial_(Beginner_1)|Beginner 1]]
+|[[Lua_Scripting_Tutorial_(Beginner_1_Tech_Supplement)|Tech 1]]
+|- align="center"
+|[[Lua_Scripting_Tutorial_(Beginner_2)|Beginner 2]]
+|[[Lua_Scripting_Tutorial_(Beginner_2_Tech_Supplement)|Tech 2]]
+|- align="center"
+|[[Lua_Scripting_Tutorial_(Beginner_3)|Beginner 3]]
+|[[Lua_Scripting_Tutorial_(Beginner_3_Tech_Supplement)|Tech 3]]
+|- align="center"
+|[[Lua_Scripting_Tutorial_(Beginner_4)|Beginner 4]]
+|[[Lua_Scripting_Tutorial_(Beginner_4_Tech_Supplement)|Tech 4]]
+|- align="center"
+|[[Lua_Scripting_Tutorial_(Beginner_5)|Beginner 5]]
+|[[Lua_Scripting_Tutorial_(Beginner_5_Tech_Supplement)|Tech 5]]
+|}
 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 just a matter 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.
+[http://foldit.wikia.com/wiki/Category:Script_tutorial Category-Script Tutorial]
+== Resources ==
-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.&nbsp; If you already know how to program, you'll find that it's a&nbsp; simple issue of learning Lua's simple syntax and the Foldit command set.&nbsp; Additional resources for working with Lua are listed below, including guides to exporting and importing scripts and more!
+===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)
-Whatever option you choose, best of luck and happy scripting!
+* [[Lua Scripting Tutorial (Beginner 3)]] (using game commands)
+* [[Lua Scripting Tutorial (Intermediate)]] (similar to beginner tutorials, but more compact)
-== RESOURCES ==
-[[Lua Scripting Tutorial (Beginner 1)]] (browsing, loading and running scripts, open output window)
+* [[Lua Scripting Tutorial (Advanced)]] (using functions and tables)
+* [https://fernleaf07.blogspot.fr/search?updated-min=2013-01-01T00:00:00-05:00&updated-max=2014-01-01T00:00:00-05:00&max-results=2 User's Guide to Foldit Lua 2.0 API] (blog entry by [http://fold.it/portal/user/167300 smith92clone] )
+* [http://www.youtube.com/watch?v=lRvNVZPhrB8 Foldit Scripting Preview ]
-[[Lua Scripting Tutorial (Beginner 2)]] (Lua commands)
+* [http://www.youtube.com/watch?v=7y43yYUA4mE Foldit Cookbook Scripting]
-[http://foldit.wikia.com/index.php?title=Lua_Scripting_Tutorial_%28Beginner_3%29&action=edit&redlink=1 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)
-[[Simplified List of Lua Commands]]
-[[Lua Script Library]] (useful functions you can add to your recipes)
-[[Lua Export and Import of Scripts|Lua Export and Import of Scripts using Text and HEX editor]]
-[[Lua Export and Import of Scripts using WORDPAD++]]
-[http://fold.it/portal/recipes Foldit Recipes and Scripts Homepage]
-[http://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual ]
-[http://lua-users.org/wiki/ Lua-users wiki]
-[http://www.youtube.com/watch?v=lRvNVZPhrB8 Foldit Scripting Preview ]
-[http://www.youtube.com/watch?v=7y43yYUA4mE Foldit Cookbook Scripting]
-[http://www.wowwiki.com/Lua Lua Wiki for WOW (WOW-specific but contains a lot of useful resources)]
-[http://www.lua.org/pil/index.html Programming in Lua Book (First Edition)]
-[[Lua Script Advice]]
-[[Lua_Functions_That_Should_Be_Implemented]]
-== LUA LANGUAGE ==
-Here is a condensed summary of the keywords and operators available in LUA:[[Simplified List of Lua Commands| ]]
-'''--''' - 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.<br />
-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)
-== LUA&nbsp;INTERFACE to FOLD.IT ==
-The following Fold.It function calls are available from the Lua interface. For a version of this interface more appropriate for beginners, as well as code snippets, see the [[Simplified List of Lua Commands]].
-'''void set_behavior_clash_importance(number importance)'''<br />Set the clashing importance to 'importance' (between 0 and 1).
-'''void restore_abs_best()'''<br />Restore to the absolute best pose.
-'''void restore_credit_best()'''<br />Restore to the best pose for which you have gotten credit.
-'''void restore_recent_best()'''<br />Restore to the recent best pose.
-'''void reset_recent_best()'''<br />Set this pose as recent best.
-'''void reset_puzzle()'''<br />Reset puzzle to the starting configuration.
-'''void quicksave(integer slot_number)'''<br />Quicksave to a slot.
-'''void quickload(integer slot_number)'''<br />Quickload from a slot.
-'''void save_structure()'''<br />Save current structure assignment.
-'''void load_structure()'''<br />Load previously saved structure assignment.
-'''void do_unfreeze_all()'''<br />Unfreeze all segments.
-'''number get_score([boolean negative_score])'''<br />Return the current score. If negative_score is present and true, will return negative score, otherwise, negative scores will be 0.
-'''number get_segment_score(integer segment_index_1[, ..., integer segment_index_n])'''<br />Return the current score of the given segments. More than one segment index may be specified.
-'''integer get_segment_count()'''<br />Return the number of segments.
-'''integer get_band_count()'''<br />Return the number of bands.
-'''void band_add_segment_segment(integer segment_index_1, integer segment_index_2)'''<br />Add a band between the segments at 'segment_index_1' and at 'segment_index_2'.
-'''void band_set_strength(integer band_index, number strength)'''<br />Set the strength of the band at the given index.
-'''void band_set_length(integer band_index, number length)'''<br />Set the length of the band at the given index.
-'''number get_segment_distance(integer segment_index_1, integer segment_index_2)'''<br />Return distance between 2 segments.
-'''boolean is_hydrophobic(integer segment_index_1[, ..., integer segment_index_n])'''<br />Get segments' hydrophobicity at given segment indices.
-'''string get_ss(integer segment_index_1[, ..., integer segment_index_n])'''<br />Get segments' secondary structure type at given segment indices.
-'''integer get_sidechain_snap_count(integer segment_index)'''<br />Return the number of positions the sidechain at the given index can snap to. NOTE: this number can change if the protein is moved.
-'''void do_sidechain_snap(integer segment_index, integer snap_index)'''<br />Snap the position of the sidechain at the given index to the given snap position.
-'''void band_delete(integer band_index_1[, ..., integer band_index_n])'''<br />Delete the bands at the given band indices.
-'''void band_enable(integer band_index_1[, ..., integer band_index_n])'''<br />Enable the bands at the given band indices.
-'''void band_disable(integer band_index_1[, ..., integer band_index_n])'''<br />Disable the bands at the given band indices.
-'''string get_aa(integer segment_index_1[, ..., integer segment_index_n])'''<br />Get segments' amino acid type at given segment indices.
-'''void do_shake([integer iterations])'''<br />Run shake. Run for 'iterations' iterations if given; otherwise, until stopped.
-'''void do_mutate([integer iterations])'''<br />Run mutate. Run for 'iterations' iterations if given; otherwise, until stopped.
-'''void do_global_wiggle_all([integer iterations])'''<br />Run global wiggle on backbone and sidechains. Run for 'iterations' iterations if given; otherwise, until stopped.
-'''void do_global_wiggle_backbone([integer iterations])'''<br />Run global wiggle on backbone. Run for 'iterations' iterations if given; otherwise, until stopped.
-'''void do_global_wiggle_sidechains([integer iterations])'''<br />Run global wiggle on sidechains. Run for 'iterations' iterations if given; otherwise, until stopped.
-'''void do_local_wiggle([integer iterations])'''<br />Run local wiggle. Run for 'iterations' iterations if given; otherwise, until stopped.
-'''void do_local_rebuild([integer iterations])'''<br />Run local rebuild on selection. Run for 'iterations' iterations if given; otherwise, until stopped.
-'''void do_freeze(boolean backbone, boolean sidechain)'''<br />Freeze segments. If 'backbone' or 'sidechain' is true, freeze that part of the segment.
-'''void select_all()'''<br />Select all segments.
-'''void select_index(integer segment_index_1[, ..., integer segment_index_n])'''<br />Select segments at the given indices. More than one segment index may be specified.
+===Commands / Functions===
-'''void select_index_range(integer segment_index_1, integer segment_index_2)'''<br />Select all segments from (including) 'segment_index_1' to (including) 'segment_index_2'.
+* [[Simplified List of Lua Commands|Simplified list of Foldit Lua Functions (V1)]]
+* [[Foldit_Lua_Functions_(v1)|Foldit Lua Functions (V1)]]
+* [[Foldit Lua Functions|Foldit Lua Functions (V2)]]
+* [[Lua_Standard_Libraries|Lua Standard Libraries (V2)]]
+* [[Lua_Error_Handling|Error Handling in Lua (V2)]]
+* [[Lua Script Library]] (useful functions you can add to your recipes)
+* [[Lua Export and Import of Scripts|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|Lua Functions that should be implemented]]
+* [[Foldit library for debugging]]
+===Recipes===
-'''void deselect_all()'''<br />Clear selection.
+* [http://fold.it/portal/recipes Foldit Recipes and Scripts Homepage]
+* [[Recipes|best recipes]]
+===External / Other===
-'''void deselect_index(integer segment_index_1[, ..., integer segment_index_n])'''<br />Deselect segments at the given indices. More than one segment index may be specified.
+* [http://www.lua.org/manual/5.3/ Lua 5.3 Reference Manual ]
+* [http://lua-users.org/wiki/ Lua-users wiki]
+* [http://www.lua.org/pil/index.html Programming in Lua Book (First Edition)]
+* [http://www.wowwiki.com/Lua Lua Wiki for WOW (WOW-specific but contains a lot of useful resources)]
+== Lua Language ==
-'''void replace_aa(string aa)'''<br />Replace segments' amino acid within selection with 'aa'.
+See [[Lua language reference]].
-'''void replace_ss(string ss)'''<br />Replace segments' secondary structure within selection with 'ss'.
+== Foldit Lua Interface==
-'''number [[get_segment_score_part]](string score_part, integer segment_index_1[, ..., integer segment_index_n])'''<br />Return the current score part of the given segments. More than one segment index may be specified.
+See [[Foldit Lua Interface]].
-'''void help()'''<br />Prints to Recipe Output, an unannotated list of Foldit functions.
+[[Category:Script tutorial]]