A puzzle setup file is optional for a basic Foldit private puzzle. A puzzle setup file can enabled advanced features that are required for some puzzles.
The information here is adapted from the supplementary information section of Creating custom Foldit puzzles for teaching biochemistry, published in Biochemistry and Molecular Biology Education in January 2019.
Format
A puzzle setup file consists of keyword-value pairs, and uses the same format as other Foldit configuration files, as shown in this example:
version: 1
{
"chain_cutpoint" : "37||57||86||97||"
"backbone_locked" : "1||9-37||38-43||57||58-65||72-86||87||97||98-105||116-126||"
"jump_locked" : "1-126||"
"sidechain_locked" : "1||9-37||38-43||57||58-65||72-86||87||97||98-105||116-126||"
"move_tool_mode" : "segment"
}
In this format, both keywords and values are quoted, and a colon separates a keyword from its value.
The example uses the keywords "chain_cutpoint", "backbone_locked", "jump_locked", "sidechain locked", and "move_tool_mode". These keywords are explained or at least referenced below.
Naming
Puzzle setup files use the extension ".puzzle_setup", for example, "example_pdb.puzzle_setup".
Types
The values in a puzzle setup file can be one of several types:
| Type | Description | Example |
| reslist | A list of residue indices, formatted as a residue index, a pipe ("|"), a value, and then another pipe; then repeat.
Multiple residue indices with the same value can also be formatted with the starting and ending residue index separated with a dash. Some keywords, such as "backbone_locked", use only the residue indices, and no values. A double pipe ("||") separates the indices for these keywords. The message "residue range has odd count" appears when there's a problem with a reslist keyword. Each residue index or range of residues must be followed by a pipe, even if there's no value specified. |
"2|val1|3|val2|8|val3|" "14-108||" |
| int | an integer | "145" |
| real | a real value | "3.5" |
| bool | a boolean value, integers can be used for formatting | "0" "1" |
Keywords
A puzzle setup file can contain keywords that include the following :
| Keyword | Type | Description | Example |
| notes | reslist of string | notes that will appear in residue info | "notes" : "3-5|click here|" |
| can_design | reslist | which residues can be designed | "can_design" : "3-5||" |
| can_delete | reslist | which residues can be deleted | |
| can_insert_after | reslist | which residues can have another residue inserted after them | |
| can_insert_before | reslist | which residues can have another residue inserted before them | |
| can_delete_any_inserted | bool | should deletion of any inserted residues be allowed | "can_delete_any_inserted" : "0" |
| min_actual_length | int | the minimum length allowed by deletions | "min_actual_length" : "15" |
| max_actual_length | int | the maximum length allowed by insertions | |
| backbone_locked | reslist | which residues will have their backbone locked | |
| sidechain_locked | reslist | which residues will have their sidechain locked | |
| jump_locked | reslist | which residues will have any jump attached to them locked | |
| chain_cutpoint | reslist | where to insert additional cutpoints within a chain | |
| seg_cutpoint | reslist | a cutpoint will be inserted after this residue, with no new chain, and the cut will be constrained as if it were a peptide bond with ideal constraints | |
| sidechains_always_show | reslist | which sidechains to always show fully, regardless of visualization settings | |
| residue_weights | reslist of real | a weighting to apply to the per-residue scoring | "residue_weights" : "3-5|0.5|" |
| replonly | reslist | residues to only score the repulsive term, by applying the RepulsiveOnlyMover and REPLONLY variant to them | |
| detect_disulfides | bool | should disulfides be automatically redetected as structure changes | |
| can_share | bool | if set to "0", players cannot share solutions | |
| allowed_macros | string | if set to "none”, allows no macros, if set to “gui” allows only gui macros, if set to “all” allows gui and script macros | |
| parent_pids | comma separated ints | users can load in solutions from these puzzles | |
| upload_macro_runs | bool | automatically upload data to server whenever a player uses a recipe | |
| use_loop_hash | bool | if set to "1", enables the Remix tool (LoopHash) | |
| use_cut_tool | bool | if set to "1", enables the cut tool | |
| use_disulfide_tool | bool | if set to "1", enables manual making and breaking of disulfides | |
| use_rama_map | bool | if set to "1", enables the rama map | |
| enable_blueprint | bool | if set to "1", enables the blueprint tool | |
| move_tool_mode | string | ||
| hide_constraints | bool | if set to "1", prevents the red constraint lines from being drawn for the puzzle | |
| user_cutpoints_only | bool | ||
| starting_score_check | real |
Under "allowed_macros", the reference to GUI macros is obsolete. All macros (recipes) are now scripts written in Lua. It's not clear if the "none" setting for this keyword is working.
Many other keywords are possible, but there's no known list of them all. There are a number of unencrypted .puzzle_setup files in a typical Foldit installation. These files are used for Campaign and Education puzzles, and some other features, such as Dojo mode. They may contain keywords not listed above. Many of these keywords enable or disable certain Foldit features.
Observed keywords
The table below shows keywords found by scanning the unencrypted .puzzle_setup files used for the Campaign and Education puzzles. Many of these keywords are also found in the list above, which is based on a published paper.
The "Example" column shows some of the values found in the .puzzle_setup files. When there are multiple discrete values, a vertical bar separates them, for example "0" | "1", indicating at least one value of "0" and at least one value of "1".
The type of keywords has been identified based on the types found in the preceding table.
Most of the observed keywords appear to be type bool, and seem to relate to enabling or disabling Foldit features on specific puzzles. Many of the keywords show only the "0" value or the "1" value, which probably indicates the default associated with the keyword.
There are also a number of keywords which use the reslist type.
There are a few keywords which are comma-separated lists, URLs, or other types.
Keywords that begin with "gui" probably involve Foldit's original interface, and so, may be obsolete.
In some cases, there may be more than one keyword which appears to relate to the same feature. For example, there's the keyword "actions/ActionRebuild", but then "ActionRebuild" also appears under the keyword "banned_actions".
Since there is no authoritative source for this information, testing is the only way to discover exactly what a given keyword does.
While several keywords reference "actions", there's no known list of all possible values. Values like "ActionsJumpWidget" and "ActionCartLoopHash" remain obscure.
| Keyword | Type | Description | Example |
| actions/ALIGN_GUIDE | bool | "1" | |
| actions/ActionBandAddDrag | bool | "1" | |
| actions/ActionBandDelete | bool | "0" | |
| actions/ActionBandEnableAll | bool | "0" | |
| actions/ActionCartLoopHash | bool | "1" | |
| actions/ActionDeleteResidue | bool | "1" | |
| actions/ActionGlobalMinimize | bool | "1" | |
| actions/ActionGlobalMinimizeSidechains | bool | "1" | |
| actions/ActionIdealize | bool | "0" | |
| actions/ActionIdealizeSS | bool | "1" | |
| actions/ActionInsertCut | bool | "1" | |
| actions/ActionInsertResidue | bool | "1" | |
| actions/ActionLigandMMFF | bool | "0" | |
| actions/ActionLocalMinimizePull | bool | "1" | |
| actions/ActionLockCopy | bool | "0" | |
| actions/ActionLockToggle | bool | "1" | |
| actions/ActionPullSidechain | bool | "1" | |
| actions/ActionRebuild | bool | "1" | |
| actions/ActionRebuildPROTEIN | bool | "0" | |
| actions/ActionRepack | bool | "1" | |
| actions/ActionRepackDesign | bool | "1" | |
| actions/ActionRotamerPicker | bool | "0" | |
| actions/ActionSecStructFloatMenu | bool | "1" | |
| actions/ActionShowBlueprintPanel | bool | "0" | |
| actions/ActionShowNoteTool | bool | "0" | |
| actions/ActionShowStructureTool | bool | "1" | |
| actions/ActionStandaloneResetPuzzle | bool | "1" | |
| actions/ActionThreadCut | bool | "1" | |
| actions/ActionTweak | bool | "1" | |
| actions/LIGANDVIEW | bool | "0" | |
| actions/MinimizeNotes | bool | "0" | |
| allow_extended_dofs | bool | "1" | |
| allowed_macros | "none" | ||
| backbone_locked | reslist | "1-22||31-66||" | |
| banned_actions | "ActionRebuild,ActionRebuildPROTEIN,ActionRepack,ActionRepackDesign,ActionGlobalMinimize,ActionGlobalMinimizeBackbone,ActionGlobalMinimizeJumps,ActionGlobalMinimizeSidechains,ActionLocalMinimize,ActionLocalMinimizePull,ActionTransform,ActionJumpWidget,ActionIdealize,ActionIdealizeSS" | ||
| building_block_cnstr_weight | int | "100" | |
| can_delete | reslist | "186-201||216-259||" | |
| can_delete_any_inserted | bool | "1" | |
| can_design | reslist | "2||4-10||12-14||17-27||30-35||37-39||41-47||49-50||52-58||60-62||65-75||78-83||85-87||89||92||" | |
| can_design_ligand | reslist | "92||" | |
| can_design_ligand_reaction | reslist | "118||" | |
| can_insert_after | reslist | "185-201||215-259||" | |
| can_insert_before | reslist | "186-202||216-259||" | |
| chain_cutpoint | reslist | "37||57||86||97||" | |
| detect_disulfides | bool | "1" | |
| enable_blueprint | bool | "1" | |
| gui/disable_action_options_tab | bool | "1" | |
| gui/disable_advanced_mode | bool | "1" | |
| gui/disable_interface_switch | bool | "1" | |
| gui/disable_pull_pie_menu | bool | "1" | |
| gui/disable_save_load | bool | "0" | |
| gui/disable_screenshot | bool | "0" | |
| gui/disable_view_options | bool | "1" | |
| gui/hide_main_menu_on_start | bool | "1" | |
| gui/simple_undo | bool | "1" | |
| gui/simplified_filter_display | bool | "0" | |
| gui/start_with_selection_interface | bool | "1" | |
| gui/use_new_bubble_format | bool | "0" | |
| hide_aa_icons | bool | "1" | |
| hide_constraints | bool | "1" | |
| jump_locked | reslist | "1-126||" | |
| max_actual_length | int | "259" | |
| min_actual_length | int | "125" | |
| move_tool_mode | "segment" | ||
| notes | reslist | "1| Toggle the guide by opening up the View Options and changing Show Guide checkbox |5| Hint: Build secondary structures with the secondary structure tool [L] |19|Hint: Try using cutpoints here. |38|Hint: Try using cutpoints here |53| Toggle notes on/off using hotkey 1" | |
| parent_pids | int | "2008925" | |
| puzzle_setup | "intro_standard" | ||
| residue_weights | reslist | "117|6.0|" | |
| sidechain_locked | reslist | "1-185||203||206-207||210-211||214||" | |
| sidechains_always_show | reslist | "1||4||" | |
| use_cut_tool | bool | "1" | |
| use_loop_hash | bool | "1" | |
| use_rama_map | bool | "1" | |
| user_cutpoint | reslist | "12||21||29||35||44||" | |
| wiki_url | "https://foldit.fandom.com/wiki/Intro_Puzzles/Close_the_Gap" |