The Foldit cookbook is stored in a file called all.macro, which uses a variation of JSON, a standard data interchange format.

JSON files consist of lists of keyword-value pairs. The pairs can be nested, meaning a value for one keyword can be another list of keyword-value pairs.

For a GUI recipe, each step is represented by an "action" keyword. The value for each action contains the name of the action, and then nested lists for the "ingredients" or arguments needed for the action.

Commands[edit | edit source]

The table below shows the JSON names of GUI commands used in the most recent release of Foldit, along with the names of the arguments. The names of the arguments are peers of the command names. Each argument in turn consists of a list of keyword-value pairs.

GUI command JSON name arg 1 arg 2
Shake Sidechains shake num_of_iterations
Wiggle wiggle num_of_iterations
Local Wiggle Sequence local_wiggle num_of_iterations residues
Freeze lock residues
Unfreeze unlock residues
Set structure set_secondary_structure residues structure
Set amino acid set_amino_acid residues aa
Mutate mutate num_of_iterations residues
Add bands add_bands residues1 residues2
Disable Band disable bands
Enable Band enable bands
Delete Band remove bands
Change Band Strength set_strength bands strength
Clashing Importance behavior importance
Reset Puzzle ActionStandaloneResetPuzzle
Restore Very Best ActionStandaloneRestoreAbsoluteBest
Set Recent Best ActionStandaloneResetRecentBest
Restore Recent Best ActionStandaloneRestoreRecentBest
Quicksave ActionStandaloneQuicksave
Quickload ActionStandaloneQuickload
Comment comment comment

Arguments[edit | edit source]

The table below contains the top-level values for each argument. Many of the arguments consist of these three values:

  • is_defined - 1 if argument value is defined, 0 if not, see below
  • name - data type for the argument, "integer", "real", "text"
  • value - value for the argument

When the "is_defined" key has a value of 0, it means the user has not supplied a required value. It's also possible to see a name key like "residues_undefined", meaning the user hasn't made even a preliminary selection.

The "residues" and "bands" arguments have different sub-types, which are covered in more detail below. They have "varies" for the second and third keywords.

For "add_bands", the "residues1" and "residues2" arguments are the same as the "residues" argument on other commands.

name kywd1 kywd2 kywd3
num_of_iterations is_defined name value
residues name (varies) (varies)
bands name (varies) (varies)
structure is_defined name value
aa is_defined name value
strength is_defined name value
importance is_defined name value
slot is_defined name value
comment is_defined name value

For "num_of_iterations", a value of 0 corresponds to the "until stopped" option in a GUI recipe. This option doesn't have a direct equivalent in a Lua recipe.

For "structure", the internal codes are different than the ones used in Lua. The codes are as follows:

structure GUI Lua
helix 0 H
loop 1 L
sheet 2 E

Residues[edit | edit source]

The "residues" argument has four different sub-types. The "name" value distinguishes these types:

  • residues_all - all residues
  • residues_by_stride - residues by stride
  • residues_ref - a new or existing user pick
  • residues_undefined - user hasn't completed ingredient

The "residues_undefined" type indicates the user has selected a command, but hasn't made the required selections for the residues condition.

For the "add_bands" command, the arguments "residues1" and "residues2" follow the same structure.

The table below breaks down each of these types.

name kywd1 kywd2
residues_by_stride start step
residues_ref ref-id

For "start", the "name" keyword indicates two different options:

name kywd1
single_residue_by_index index
residues_ref ref-id

The "residues_ref" option is the same as the one at the top level of "residues", indicating a new or existing user pick

For "start", the "index" keyword contains:

name kywd1 kywd2 kywd3
index is_defined name value

For "residues_by_stride", "step" contains the following keywords.

name kywd1 kywd2 kywd3
step is_defined name value

Bands[edit | edit source]

The "bands" argument, like "residues", has four different sub-types. The "name" value distinguishes these types:

  • bands_all - all bands
  • bands_connected - connected bands only
  • bands_reference - a new or existing user pick
  • bands_undefined - user hasn't completed ingredient

The "bands_undefined" type indicates the user has selected a command, but hasn't made the required selections for the bands condition.

The "bands" argument is used by commands which work on existing bands. The command "add_bands" does not use "bands".

The "bands_connected" option does not work as expected. Instead of working on bands which connect two segments or residues, "bands_connected" only works on bands which end on a point in space -- known as spacebands.

The table below shows the components of each type. The structure isn't quite as complex as the one for "residues".

name kywd1
bands_reference ref-id
Community content is available under CC-BY-SA unless otherwise noted.