Foldit file and directory structure

(This article is a work in progress as of 12 January 2016.)

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-binary.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 update a client manually. After one client updates, 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 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" update group 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.

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.

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. The all.macro function is normally controlled through the recipe dialog 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 Folidt 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 asser'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.

• 0002001693.ir_puzzle.ofilters

The ofilters file is a binary file, and is likely encrypted. Its function is unknown.

• 0002001693.ir_puzzle.opdb

The opbd file is a binary file, and is likely encrypted. The ".odpb" extension suggest its content may be suitable the Protein Data Bank (PDB) format used by rcsb.org.

• 0002001693.ir_puzzle.opuzzle_setup

The ofilters 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 is a text file, and appears to contain information about the symmetry structure of the puzzle. 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
• quicksave2.ir_solution, quicksave3.ir_solution, quick4.ir_solution, and so on

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

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

Some additional ir_solution files may have been created in previous version of the client:

• macro_start.ir_solution
• macro_end.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.