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.

See Lua Scripting for more on how to write Foldit recipes in Lua. There's also a series of tutorials, starting with Lua Scripting Tutorial (Beginner 1).

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.

A few of the more complex and infrequently used commands are omitted. See Foldit Lua Functions (V1: Foldit Lua Functions (v1)) for a complete list.

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.

Doer Commands

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 )

Shakes the sidechains of the protein for iterations rounds. Shake generally requires only one iteration to finish its work, but two iterations are commonly used to be on the safe side.

structure.ShakeSidechainsAll ( 2 ) -- shakes for two rounds

See also:

(V1: do_shake)

structure.WiggleAll ( iterations, [backbone], [sidechains] )

Global wiggles sidechains and/or backbone for the specified iterations.

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

See also:

(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

(V1: do_local_rebuild)

structure.MutateSidechainsAll ( iterations )

Mutates all mutable parts of the protein. Mutate is only allowed for design puzzles.

structure.MutateSidechainsAll ( 3 ) -- mutates for three rounds

See also:

(V1: do_mutate)

Setter Commands

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.

absolutebest.Restore ()

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.

absolutebest.Restore ()

See also: absolutebest.Restore

(v1: restore_abs_best)

recentbest.Save ()

Saves the current version of the protein as your "recent best".

recentbest.Save ()

See also recentbest.Save

(V1: reset_recent_best)

recentbest.Restore ()

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.

recentbest.Restore ()

See also: recentbest.Restore

(V1: restore_recent_best)

puzzle.StartOver ()

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.

puzzle.StartOver ()

See also: puzzle.StartOver

(V1: reset_puzzle)

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

(V1: 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

(V1: 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

(V1: band_add_segment_segment)

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

(V1: band_set_length)

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

(V1: band_set_strength)

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

See also:

(V1: band_disable)

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

See also:

(V1: band_enable)

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

See also:

(V1: band_delete)

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

See also:

(V1: do_freeze)

freeze.UnfreezeAll ()

Unfreeze all segments.

freeze.UnfreezeAll () -- unfreeze backbone and sidechains of all segments

See also: freeze.UnfreezeAll

(V1: do_unfreeze_all)

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

(V1: set_behavior_clash_importance)

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

See also:

(V1: select_index)

selection.Deselect ( segment )

Deselect the specified segment.

Use selection.DeselectAll () to deselect all segments.

selection.Deselect ( 14 ) -- deselect segment 14

See also:

(V1: deselect_index)

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

(V1: select_index_range)

selection.SelectAll ()

Select all segments in the protein.

selection.SelectAll ()

See also selection.SelectAll

(V1: select_all)


Deselects all segments in the protein.

selection.DeselectAll ()

See also: selection.DeselectAll

(V1: deselect_all)

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

See also:

(V1: replace_ss)

Getter Commands

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().

structure.GetCount ()

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

(V1: get_segment_count)

current.GetEnergyScore ()

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

(V1: get_score)

current.GetSegmentEnergyScore ( segment )

Gives you the score of a specific segment.

print ( current.GetSegmentEnergyScore ( 18 ) ) -- prints score of segment 18

See also: current.GetSegmentEnergyScore

(V1: get_segment_score)

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

(V1: get_ss)

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

(V1: get_segment_distance)

band.GetCount ()

Gives you the total number of bands that have been placed.

print ( band.GetCount () )

See also: band.GetCount

(V1: get_band_count)

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

(V1: get_segment_score_part)

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" )
  print ( "segment " .. seg .. " is hydrophilic" )

See also: structure.IsHydrophobic

(V1: is_hydrophobic)

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

(V1: 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" )
  print ( "segment", seg, "is hydrophilic" )

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" )
  print ( "segment " .. seg .. " is hydrophilic" )

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.

For example:

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".

For example:

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

(V1: print)