Note: the commands (functions) described here are for Version 2 (V2) of the Foldit Lua Interface. The Version 1 equivalents are shown in parenthesis. See Simplified List of Lua Commands (V1) for the V1 version of this page.
The Lua commands on this page have been divided into three basic categories:
- "doer" commands
- "getter" commands
- "setter" commands
Each command is briefly described and one or more examples are given.
You can copy and paste these commands, then insert your own parameters. Parameters are the things inside the parentheses -- they are italicized in this list to make them easier to identify. There can be zero, one, two, or more parameters depending on the command, so read the description and look at the examples. When a parameter is surrounded by brackets [like this], that means it's optional whether you include it or not.
You can paste directly into the Foldit editor with control-V, but you may see Little Square Boxes (LSB). These LSB are harmless ("tab characters"), and you can ignore them.
The example include comments, which start with "--". When Lua sees "--", it treats the rest of the line as a comment. You can also start a line with "--", meaning the entire line is a comment.
- 1 Doer Commands
- 2 Setter Commands
- 2.1 absolutebest.Restore ()
- 2.2 recentbest.Save ()
- 2.3 recentbest.Restore ()
- 2.4 puzzle.StartOver ()
- 2.5 save.Quicksave ( saveslot )
- 2.6 save.Quickload ( saveslot )
- 2.7 bndx = band.AddBetweenSegments ( segment1, segment2, [atom1,] [atom2] )
- 2.8 band.SetGoalLength ( band, length )
- 2.9 band.SetStrength ( band, strength )
- 2.10 band.Disable ( band )
- 2.11 band.Enable ( band )
- 2.12 band.Delete ( band )
- 2.13 freeze.FreezeSelected ( backbone, sidechain )
- 2.14 freeze.UnfreezeAll ()
- 2.15 behavior.SetClashImportance ( importance )
- 2.16 selection.Select ( segment )
- 2.17 selection.Deselect ( segment )
- 2.18 selection.SelectRange ( segment1, segment2 )
- 2.19 selection.SelectAll ()
- 2.20 selection.DeselectAll
- 2.21 structure.SetSecondaryStructureSelected ( structure )
- 3 Getter Commands
- 3.1 structure.GetCount ()
- 3.2 current.GetEnergyScore ()
- 3.3 current.GetSegmentEnergyScore ( segment )
- 3.4 structure.GetSecondaryStructure ( segment )
- 3.5 structure.GetDistance ( segment1, segment2 )
- 3.6 band.GetCount ()
- 3.7 current.GetSegmentEnergySubscore ( segment, score_part )
- 3.8 structure.IsHydrophobic ( segment )
- 3.9 help ( [ cmd ] )
- 3.10 print ( args )
Doer commands do something to the protein. The commands structure.WiggleAll and structure.RebuildSelected can change the shape of all or part of the protein. The command structure.ShakeSidechainsAll can change the positions of the sidechains, but doesn't affect the overall shape.
The command structure.MutateSidechainsAll can change the amino acids that make up the protein. Mutating may effect the score, but it doesn't change the overall shape of the protein.
structure.ShakeSidechainsAll ( iterations )
structure.ShakeSidechainsAll ( 2 ) -- shakes for two rounds
structure.WiggleAll ( iterations, [backbone], [sidechains] )
The parameters backbone and sidechains are optional, and can be replaced by true or false as shown below.
structure.WiggleAll ( 3 ) -- wiggle backbone and sidechains for 3 rounds structure.WiggleAll ( 5, false, true ) -- wiggle sidechains for 5 rounds structure.WiggleAll ( 10, true, false ) -- wiggle backbone for 10 rounds
(V1: do_global_wiggle_all, do_global_wiggle_sidechains, do_global_wiggle_backbone)
structure.RebuildSelected ( iterations )
Rebuilds the current selection for the specified number of iterations. If nothing is selected, nothing happens, and no error message is generated.
structure.RebuildSelected ( 5 ) -- rebuilds selection for five rounds
See also: structure.RebuildSelected
structure.MutateSidechainsAll ( iterations )
structure.MutateSidechainsAll ( 3 ) -- mutates for three rounds
Setter commands set or store information about, the condition of, or the state of the protein. They don't directly alter a protein like "doers". Saving, loading, banding, and setting secondary structures are all setters because they don't directly change the protein itself. The distinction is a bit tricky -- as one example, consider the fact that bands don't actually change the protein, so adding bands is a set command; but wiggling with bands on does change the protein, so wiggle is a "doer" command.
Restore to the point in the game when you had the absolute best score. This version may include problems such as open cutpoints which prevent your score from counting on the leaderboards.
See also: absolutebest.Restore
Saves the current version of the protein as your "recent best".
See also recentbest.Save
Restore to the point in the game when you had the recent best score. (Note that the recent best must be set first, either by hand or earlier in the script.) If your score has improved since recentbest.Save, this command does nothing. If your score is worse, the protein is returned to where it was at the last recentbest.Save.
See also: recentbest.Restore
Reset the puzzle, including the secondary structures (loops, helixes, sheets) it had in the beginning. For multistart puzzle, this command also advances to the next starting model.
See also: puzzle.StartOver
save.Quicksave ( saveslot )
Save the current pose of the protein into the slot specified by saveslot. There are 100 slots you can use, numbered 1 to 100.
save.Quicksave ( 1 ) -- save the puzzle into save slot 1
See also: save.Quicksave
save.Quickload ( saveslot )
Load the pose previously saved in the slot specified by saveslot.
save.Quickload ( 1 ) -- load the puzzle from save slot 1
See also: save.Quickload
bndx = band.AddBetweenSegments ( segment1, segment2, [atom1,] [atom2] )
Add a band between segment1 and segment2. Note that both segment1 and segment2 are required. You can optionally specify atom numbers for finer control over banding.
The command returns a "band index", shown as bndx. The band index allows you to perform other "band" commands.
bndx = band.AddBetweenSegments ( 1, 5 ) -- band segments 1 and 5
See also: band.AddBetweenSegments
band.SetGoalLength ( band, length )
Set a band's length. The length is in angstroms, and must be between 0 and 10,000. The default goal length of a new band is 3.5 angstroms.
The band is specified by its band index, and must be between 1 and the value returned by band.GetCount.
If you know the band index:
band.SetGoalLength ( 1, 5 ) -- set band 1 goal length to 5
Use band.GetCount to find the band index of the last band added, allowing you to change its length:
bands = band.GetCount () -- get the total number of bands band.SetGoalLength ( bands, 5 ) -- set length of the most recently added band to 5
See also: band.SetGoalLength
band.SetStrength ( band, strength )
Set a band's strength. Strength must be between 0 and 10. The default strength of a new band is 1.0. The unit of measure for band strength is not known.
The band parameter must be the band index of an existing band, between 1 and the value returned by band.GetCount.
band.SetStrength ( 1, 5 ) -- add band between first and fifth segments
Alternately, use band.GetCount to determine the maximum band index:
bndx = band.GetCount () -- find the last band's index number band.SetStrength ( bndx, 5 ) -- set the band to strength 5
See also: band.SetStrength
band.Disable ( band )
Disable the specified band. The band parameter must be the band index of an existng band, between 1 and the value returned by band.GetCount. Disabled bands don't pull on the protein during a wiggle.
Use band.DisableAll () to disable all bands.
band.Disable ( 7 ) -- disable band at index 7
band.Enable ( band )
Enable the specified band. The band parameter must be the band index of an existng band, between 1 and the value returned by band.GetCount.
Use band.EnableAll () to enable all bands.
band.Enable ( 4 ) -- enable band at index 4
band.Delete ( band )
Delete the specified band. The band parameter must be the band index of an existng band, between 1 and the value returned by band.GetCount.
Deleting a band also changes the band indexes of all bands that were added afterward. For example, if you have 30 bands, deleting band 5 leaves indexes 1 through 4 unchanged, but the former band 6 is now index 5, 7 is 6, 8 is 7, and so on.
Use band.DeleteAll () to delete all bands.
band.Delete ( 25 ) -- delete band 25
freeze.FreezeSelected ( backbone, sidechain )
Freeze previously selected segments. If backbone or sidechain is true, freeze only that part of the segment.
selection.DeselectAll () -- limit segments to only the following selection.SelectRange ( 2, 6 ) -- select segments 2 through 6 freeze.FreezeSelected ( true, false ) -- freeze the selected backbone
freeze.FreezeSelected ( false, true ) -- freeze the selected sidechains
freeze.FreezeSelected ( true, true ) -- freeze both backbone and sidechains
Unfreeze all segments.
freeze.UnfreezeAll () -- unfreeze backbone and sidechains of all segments
See also: freeze.UnfreezeAll
behavior.SetClashImportance ( importance )
Set clashing importance also known as CI. The value of importance is between 0 and 1, where 1 is normal behavior.
behavior.SetClashImportance ( 1 ) -- set CI to 1 (max, normal default) behavior.SetClashImportance ( 0 ) -- set behavior to 0 (min) behavior.SetClashImportance ( 0.5 ) -- set CI to 0.5
See also: behavior.SetClashImportance
selection.Select ( segment )
Select the specified segment. The value of segment must be valid segment number.
Use selection.SelectAll () to select all segments.
selection.Select ( 14 ) -- select segment 14
selection.Deselect ( segment )
Deselect the specified segment.
Use selection.DeselectAll () to deselect all segments.
selection.Deselect ( 14 ) -- deselect segment 14
selection.SelectRange ( segment1, segment2 )
Select all the indexes between segment1 and segment2, inclusive
selection.SelectRange ( 14, 18 ) -- select segments 14 through 18
See also: selection.SelectRange
Select all segments in the protein.
See also selection.SelectAll
Deselects all segments in the protein.
See also: selection.DeselectAll
structure.SetSecondaryStructureSelected ( structure )
Change the secondary structure for the selected segment or segments. ) Use "H" for helix, "L" for loop, and "E" for sheet, or "A" to apply the auto structures tool. This command does not change the shape of the protein, it only changes the appearance of the backbone in one of the "cartoon" views.
Use structure.SetSecondaryStructure to set a single segment.
structure.SetSecondaryStructureSelected ( "H" ) -- change selected segments to helix structure.SetSecondaryStructureSelected ( "L" ) -- change selected segments to loop structure.SetSecondaryStructureSelected ( "E" ) -- change selected segments to sheet structure.SetSecondaryStructureSelected ( "A" ) -- automatically set helix, sheet, or loop
Getter commands don't change the protein. They simply provide you with some information about the protein or game. A simple way of using getters is to use them to output information to the screen, so all our examples here are going to use print().
Gets the total number of segments in the protein. The value returned should be used as an upper limit for any function that takes a segment index.
print ( structure.GetCount () )
See also: structure.GetCount
The command current.GetEnergyScore returns the current score.
The command current.GetScore () is the same now, but previously could return a different value for exploration puzzles, which have been deprecated. Recipes use current.GetEnergyScore and current.GetScore interchangably.
print ( current.GetEnergyScore () )
See also: current.GetEnergyScore
current.GetSegmentEnergyScore ( segment )
Gives you the score of a specific segment.
print ( current.GetSegmentEnergyScore ( 18 ) ) -- prints score of segment 18
See also: current.GetSegmentEnergyScore
structure.GetSecondaryStructure ( segment )
Gives you the secondary structure type of the specified segment. The possible values are "H" for helix, "E" for sheet, "L" for loop, or "M" for ligand (or "molecule").
print( structure.GetSecondaryStructure ( 5 ) ) -- prints secondary structure for segment 5
See also: structure.GetSecondaryStructure
structure.GetDistance ( segment1, segment2 )
Gives you the distance in angstroms between any two segments.
print ( structure.GetDistance ( 12, 20 ) ) -- prints the distance between segments 12 and 20
See also: structure.GetDistance
Gives you the total number of bands that have been placed.
print ( band.GetCount () )
See also: band.GetCount
current.GetSegmentEnergySubscore ( segment, score_part )
The score for each segment is made up of several score parts. Some of the most important score parts are Clashing, Packing, Hiding, Bonding, Backbone, and Sidechain. These are the same as the individual components of a score that pop up if you tab over a segment in the game.
The command current.GetSegmentEnergySubscore gets one of the score parts of a given segment.
The score part names are not case-sensitive, so you can specify "Clashing" or "clashing".
print ( current.GetSegmentEnergySubscore ( 5, "Clashing" ) ) -- prints the "clashing" -- part of the score of segment 5 print ( current.GetSegmentEnergySubscore ( 20, "Bonding" ) ) -- prints the "bonding" -- part of the score of segment 20
See also: current.GetSegmentEnergySubscore
structure.IsHydrophobic ( segment )
Returns the logical or boolean value "true" if the segment is hydrophobic.
seg = 4 if structure.IsHydrophobic ( seg ) then print ( "segment " .. seg .. " is hydrophobic" ) else print ( "segment " .. seg .. " is hydrophilic" ) end
See also: structure.IsHydrophobic
help ( [ cmd ] )
If cmd is not specified, prints the complete list of commands to the output window. If cmd is the name of a command, prints the command's arguments, return value(s), and a brief description.
help () help ( current.GetSegmentEnergySubscore )
The second example prints:
number current.GetSegmentEnergySubscore(integer segmentIndex, string scorePart) Get the current score part of the given segment.
See also: help
print ( args )
As seen in some of the examples above, print creates output, which appears in the recipe output window and the scriptlog file.
The print command in Foldit is very similar to the standard print command in Lua, but there may be slight differences.
There are two different ways of using the print command. One involves passing multiple parameters separated by commas:
seg = 4 if structure.IsHydrophobic ( seg ) then print ( "segment", seg, "is hydrophobic" ) else print ( "segment", seg, "is hydrophilic" ) end
This produces the expected output, but the output for each parameters is separated by a tab character. Depending on how you view the output, you may see extra spaces or square boxes between the parameters. One advantage of having tab characters is that allows the output to be copied and pasted in a spreadsheet.
The Lua concatenation operator, ".." (dot dot), can be used for better control over the output. The example becomes:
seg = 4 if structure.IsHydrophobic ( seg ) then print ( "segment " .. seg .. " is hydrophobic" ) else print ( "segment " .. seg .. " is hydrophilic" ) end
In effect, instead of three parameters, each print statement has only one parameter in this version.
The output from this version should look the same regardess of how you view it. No extra spaces are added, but you must be careful to add spaces as needed at the beginning and end of each quoted string.
Unlike some languages, you generally don't have to worry about data types. Lua converts numbers to printable strings automatically. Logical or "boolean" values, such as the one returned by structure.IsHydrophobic, must be converted to strings using the Lua tostring () command.
seg = 4 print ( "segment " .. seg .. " is hydrophobic: " .. structure.IsHydrophobic ( seg ) )
produces an error which terminates the recipe.
Using tostring avoids the error:
seg = 4 print ( "segment " .. seg .. " is hydrophobic: " .. tostring ( structure.IsHydrophobic ( seg ) ) )
corrects the error and produces output like
segment 4 is hydrophobic: true
The tostring command may also be necessary in other specialized cases.
A couple of other tricks may be helpful. If you want output to multiple lines, use "\n".
print ( "This output will\nappear on two lines" )
This output will appear on two lines
A "\t" generates a tab character, which is useful is you want spreadsheet output.
A print () with no parameters produces a blank line, for example
print ( "The next line is blank:" ) print () print ( "The previous line was blank!" )
The next line is blank: The previous line was blank!
See also: print