Foldit creates and uses a large number of files. This article describes the file naming conventions and directory structure that Foldit uses. The Windows version of Foldit is used as a baseline.
Throughout this article the term "directory" is equivalent to the term "folder", meaning a collection of files and other directories.
Foldit directory
On Windows, Foldit is installed to a single directory. All data files used in game play are stored within this directory. Screenshots created in the client are stored in a separate directory, by default the Windows desktop. The screenshot directory can be changed in options.txt. Recipes can be loaded from and exported to separate directories.
Unlike many Windows applications, Foldit is relatively portable. The Foldit installation directory can simply be copied to create a separate installation, which may be desirable when running multiple client on the same machine. There is little or no dependency on the Windows registry. An uninstaller, uninstall.exe, is created when Foldit is installed. The uninstaller will probably reference the original installation directory.
The Foldit installer may add files under the main Windows directory, so it's best to install Foldit once on each machine. After the initial installation, Foldit directories can be copied freely between machines.
Most files are created in the "top level" of the Foldit directory. On Windows, this might have the path:
c:\Foldit\
assuming that's where Foldit was installed.
For the purposes of this article, the "Foldit directory" is the directory from which a particular client is running.
Program files
The main Foldit executable is foldit.exe. This file does not change with new Foldit releases.
Foldit clients will download new Foldit release as they become available. A new Foldit release can create three new directories in the Foldit directory:
- binary (for example, cmp-binary-534dfcea8d6891d0d1cf00eaabd9f0f1)
- resources (for example, cmp-resources-30f143a66688c2217ee896e577fea1df)
- database (for example, cmp-database-cac5f89f6a3e41d011cb430d73d6fb1b)
The binary and resources items also have baseline directories (cmp-binary-00000000000000000000000000000000 and cmp-resources-00000000000000000000000000000000), which like foldit.exe, do not change with new releases.
A set of three "pointer" files in the Foldit directory contain the unique portion of the current binary, resources, and database directories. They are version-binary.txt, version-resources.txt, and version-database.txt. For example, version-binary.txt might contain "534dfcea8d6891d0d1cf00eaabd9f0f1", referring to the directory cmp-binary-534dfcea8d6891d0d1cf00eaabd9f0f1.
The old binary, resources, and database directories are deleted and the three pointer files are updated by the Foldit client as a new release is installed. There does not appear to be a way to manually download and install a new release. After one client updates through the normal process, however, the updated directories and pointer files can be copied from that client's Foldit directory to other Foldit directories.
Text files
The Foldit directory contains several text files. Text files can be read and an in some cases modified using Windows Notepad or a similar text editor.
Many Foldit text files contain lists of keyword-value pairs separated by a colon, for example:
version: 1
{
"PDB URL" : "http://fold.it/portal/files/puzzle_pdb/puzzle_post_966.zip"
"PDB2 URL" : ""
"categories" : ""
"constraints URL" : ""
"current" : "0"
"description" : ""
"difficulty" : "Intermediate"
...
}
verify: 3d19740cb5b266c73018803396a5394f
Files like this one, with a "verify" keyword at the end appear to be have been digitally signed, and will probably be rejected by client if you change their content.
On the other hand, the file options.txt consists of keyword-value in the same format, but lacking the "verify" keyword at the end. Files like this can be modified directly by the user.
The file options.txt contains most of the key Foldit settings. Many of these settings can be changed using the Foldit client, but some require editing options.txt directory. For example, the "update_group" keyword determines whether the Foldit client uses the "main" or developer preview "devprev" update group, which in turn controls when a new release is downloaded. The "update_group" keyword must be changed using an external text editor.
The file theme.txt contains color codes and related information for various aspects of the Foldit GUI interface. Like options.txt, theme.txt doesn't have a "verify" keyword, and be changed outside of Foldit.
The file hotkeys.txt contains hotkey (keyboard shortcut) settings. These can be changed under "Configure Keyboard Shortcuts" in the General Options menu. The file hotkeys.txt can also be changed outside of Foldit.
The small file mlog tracks things whether the user has agreed to the terms and conditions in "offline" mode. (The other functions of this file are unknown.) Unlike options.txt and other "text" files, mlog appears to be a "binary" file, not intended to be easily readable by humans. There's is a readable "VRFY" near the end of the file, which probably indicates the file is digitally sign, similar to "verify" keyword in some text files. The "VRFY" identifier also appears in solution files, with the ir_solution extension.
The Foldit client creates several text output files that are primarily useful for debugging. The files stdout.txt and stderr.txt seem be related the standard output and standard error facilities of the C programming language and its descendants. These files are normally empty. The file log.txt contains the type of information normally written to standard output/error. The file debug.txt is created in the event of certain types of client errors, and is apparently part of an automatic error reporting system.
The file irc-ignore.txt apparently can contain a list of IRC users to be ignored. It's unclear if this list can be maintained by the client, or whether an external text editor is required.
The file news.txt apparently contains the web addresses (node numbers) of the news updates to be displayed by the Foldit client. For example, the value 2001722 in news.txt refers to http://fold.it/portal/node/2001722.
Log files
The file log.txt is overwritten each time Foldit starts. The contents are mainly useful for debugging purposes, and includes information such as the startup parameters and the version of the Foldit software in use. In the event of a crash, log.txt may contain a stack traceback showing where the error occurred.
For some puzzles, log.txt may contain large numbers of warning messages, apparently generated by the underlying Rosetta software.
For example, you may see many messages similar to these for a symmetry puzzle:
core.conformation.symmetry.SymmData: [ WARNING ] Setting jump_group JGSS: [master 1] 2:0 3:0 core.conformation.symmetry.SymmData: [ WARNING ] Setting weight of master jump ( jump-id=6 ) to 1.0 (was undefined)
When creating a feedback problem report, it may be helpful to include log.txt.
For some crashes, a separate file error, debug.txt, is generated. This file contains a capsule summary of the error, somewhat more meaningful than a stack traceback. Apparently, debug.txt is automatically uploaded to the Foldit server when the crashed Foldit client is restarted. Unfortunately, many crashes do not generate a debug.txt.
Sample debug.txt:
version: 1
{
"backtrace" : ""
"build_id" : "20180516-f28783403a-win_x86-devprev"
"crash_id" : "de609c68-5dc6-41a1-9216-de0c1b95b202"
"current_actions" : "ToolBridgeAction\,ActionGlobalMinimize"
"current_tool" : "Selection Interface"
"file" : "interactive/application/actions/cart/PoseLoopThreadActionCart.cc:463"
"machine_id" : "14931bc1-9c75-4276-b8c1-3f4a06dece46"
"macro_id" : "-1"
"message" : "asymmetry introduced by ActionGlobalMinimize"
"player_id" : "476462"
"puzzle_id" : "2005288"
"puzzle_running_time" : "204"
"running_time" : "139905"
"timestamp" : "1527275069"
}
verify: a6e1e422cc0be336a34a54fec8b96d0c
Scriptlog files
The Foldit directory can contain one or more scriptlog files, which are formatted as XML, with the file extenstion .xml. Scriptlog files contain the output of Foldit recipes, which are scripts written in the Lua programming language.
Scriptlog files are named as follows:
scriptlog.*trackname*.xml
where *trackname* is the current track name. The default track is named "default", so the "scriptlog.default.xml" is the default scriptlog file.
Within a given track, the scriptlog file is overwritten each time a another recipe is run. In the Foldit client, the "Tracks" button on the "Undo" menu controls changing tracks.
Despite the XML extension, most recipe output is just text, enclosed within the "Foldit:ScriptOutput" tag. Scriptlog files can be read using Notepad or a similar text editor.
The Foldit functions recipe.SectionStart, recipe.ReportStatus, and recipe.SectionEnd do create XML tagged output. These functions are not used in many recipes, however.
Recipe files
The Foldit cookbook is stored in the file all.macro. This file can be copied between Foldit clients to simplify cookbook maintenance. The all.macro file is text file, but contains a "verify" keyword, which may be a digital signature. Normally, all.macro is maintain by using the Cookbook in the Foldit client.
A similar file, single.macro, contains one recipe, which appears to be the last recipe downloaded by the Foldit client.
User files
The top level of the Foldit directory contains two user-related files. The Foldit user's numeric user id, left padded with zeroes to ten position is used in naming these files:
*userid*_ir_user This is text file, with "verify" keyword which appears to contain digital signature. It contains the Foldit user's screen name and password. The password is in plain text, not encrypted. *userid*_ir_ach This is text file, with "verify" keyword which appears to contain digital signature. It tracks the user's "achievements" such as the user's top scores (top 10/20/30), solutions shared, and total moves.
Puzzle files
Each puzzle or contest played creates a number of files. This number can potentially be quite high.
The key element in naming puzzle-related files is the Foldit "node name" for the puzzle in question. The node name is the basis of the puzzle's web page address. For example, for puzzle 1174, the web page is http://fold.it/portal/node/2001693, so the node name is "2001693". For file and directory naming purposes, node names are padded on the left with zeroes to ten places, so "2001693" becomes "0002001693".
Puzzle setup files
When a new puzzle is loaded by a client, several files of different types are created in the top-level of the Foldit directory. Using puzzle 1174, node "2001693" as example, the files are:
- 0002001693.ir_puzzle
A text file, ir_puzzle contains the description of the puzzle, and the download information. For example, 0002001693.ir_puzzle refers to http://fold.it/portal/files/puzzle_pdb/puzzle_post_1200.zip. The zip file in turn contains the remaining files in this list. Although readable, the ir_puzzle file contains a "verify" keyword with what appears to be a digital signature, so it's likely not modifiable.
- 0002001693.ir_puzzle.ocmdline
The ocmdline file is a binary file, and is likely encrypted. Its function is unknown. The ".ocmdline" extension suggests it by contain the command-line options used to start Foldit. A human-readable version of these arguments appears in log.txt under "args used".
- 0002001693.ir_puzzle.ofilters
The ofilters file is a binary file, and is likely encrypted. Its function is unknown. The "ofilters" extension suggests it may contain the settings for the filters or conditions used in a puzzle.
- 0002001693.ir_puzzle.opdb
The opbd file is a binary file, and is likely encrypted. The ".odpb" extension suggest its content may be similar to the Protein Data Bank (PDB) format used by rcsb.org.
- 0002001693.ir_puzzle.opuzzle_setup
The opuzzle_setup file is a binary file, and is likely encrypted. Its function is unknown.
- 0002001693.ir_puzzle.owts
The owts file is a binary file, and is likely encrypted. Its function is unknown.
- 0002001693.ir_puzzle.sym
The sym file is a text file, and appears to contain information about the symmetry structure of the puzzle. See .sym format for details. The sym does not contain a "verify" keyword, so it's likely modifiable.
Puzzle gameplay files
Foldit creates files with the extension ".ir_solution" during gameplay. These files are created automatically at certain points, and also when players save or share and solution, and when players download a shared solution. These files are around 100 KB each, and the largest and most numerous gameplay files.
The ir_solution files are binary, and may be partially encrypted. Some tags or eyecatchers may be visible with a text editor, however.
For example, the file puzzle_2001693_time_1452207979.ir_solution contains some identifiable information:
SOLN� META Score 13896.872� 1174 solo best
The SOLN eyecatcher may identify this as a "solution" file. "Score 13896.872" is the name of shared solution, and "1174 solo best" is its description.
One group of ir_solution files is created in the top level of the Foldit directory. These have the format:
puzzle_*puzzlenode*_time_*timestamp*.ir_solution
where *puzzlenode* is the node name for the puzzle, for example "2001693" for puzzle 1174 (in this case, the leading zeroes are omitted), and *timestamp* is a value such as "1452207979", as seen in debug.txt and other Foldit files.
The ir_solution files created in the top level of the Foldit directory appear to be associated with manual saves and shares.
Additional ir_solution files are created under the "puzzles" directory, which is a sub-directory of the Foldit directory. For example the puzzles directory might have a Windows-style path of:
c:\Foldit\puzzles
The puzzle directory in turn as a sub-directory for each puzzle played. For example, for puzzle 1174, the path might be:
c:\Foldit\puzzles\0002001693
This directory in turn has subdirectories, such as:
c:\Foldit\puzzles\0002001693\*userid*\*trackname*
where *userid* is the Foldit user's unique numeric id, and *trackname* is the name of the current track.
The lowest-level directories of this hierarchy contain ir_solution files such as:
- autosave.ir_solution
- autosave-best.ir_solution, autosave-best-improver.ir_solution
- autosave-creditbest.ir_solution, autosave-creditbest-improver.ir_solution
- autosave-recentbest.ir_solution, autosave-recentbest-improver.ir_solution
- quicksave.ir_solution for the first quicksave slot
- quicksave2.ir_solution, quicksave3.ir_solution, quick4.ir_solution, and so on, for the remaining quicksaves
Regardless of location, it appears that ir_solution files are never deleted by the Foldit client.
The autosave ir_solution files appear to be generated automatically by the Foldit client, which the quicksave files appear to be generated by the Quicksave recipe function (save.Quicksave or the older quicksave function). The quicksave interface allows for 99 quicksave slots.
temporary gameplay files
Foldit clients may "hang" or stop responding, after certain problems with Foldit server (at fold.it). This can happen even after the server has resumed normal operation.
The client may run normally until it attempts to communicate with the Foldit server. Sometimes, attempting to upload a shared solution (that is, a solution that you intend to share) can cause a hang. Closing and restarting the client may be the only way to resolve the hang. This may leave orphaned ir_solution files, such as:
upload_tmp_UNIQ-86ad1f3d-d4d1-4ba8-a1fc-d441a9666a0f.ir_solution
It appears these "upload_tmp" ir_solution files are deleted after a successful upload, but are never cleaned up after a failed download.
Some additional ir_solution files may have been created in previous version of the client:
- macro_start.ir_solution
- macro_end.ir_solution
update files
Each time Foldit starts, it checks for software updates. If an update is available, the Foldit client starts to download it automatically. The user may choose to skip the update, in which case a partial zip file is left behind. Usually, only a "binary" zip file is left behind, for example:
'''cmp-binary-win_x86-47b3e462d77cde5897b37de9ae27765f.zip'''
An update may also involve zip files for the properties and database directories, so it's possible these files would be left behind after a skipped update.
These extra zip files don't really pose a problem, since they'll be overwritten and eventually deleted when you accept the update. If you manually update by updating one client, then copying updates, the leftover zip files may persist.