The wiki reference pages Foldit Lua Functions and Foldit Lua Functions (v1) are automatically generated from the output of the help command in the Foldit client.
This is a two-stage process. The first stage is to run the help() command in the Foldit client. The help() command with no arguments produces a list of all functions in the Foldit Lua interface. The second stage is to run a help command for each function name listed in the first stage.
The resulting output can then be formatted into wiki markup.
Support for version 1 of the Foldit Lua interface was added 20 March 2017. The options needed for version 1 are listed in bold.
The steps involved are:
Obtain help() output
- Run the help() command with no arguments in the Foldit client. This produces a list of function names in the client's scriptlog.
- Version 1: the output of the help() command is different for version 1 and version 2. You must use a version 1 recipe to produce the list of version 1 functions.
- The help() output looks like this:
void print([arg1,...,argN]) boolean absolutebest.AreConditionsMet() number absolutebest.GetEnergyScore() number absolutebest.GetExplorationMultiplier() ...and so on...
- Double-check the help() output.
In the version 2 output, structure.TweakRotate is missing the opening parenthesis for its argument list, which causes problems when generating a help command for it. The current output is
void structure.TweakRotateinteger segmentIndex, number angle)
- Manually update this line to read:
void structure.TweakRotateinteger(segmentIndex, number angle)
- Also in version 2, three functions are missing opening and closing parentheses on their function lists:
bool filter.ConditionSatisfiedstring name number filter.GetBonusstring name bool filter.IsEnabledstring name
- Manually update these lines to read:
bool filter.ConditionSatisfied(string name) number filter.GetBonus(string name) bool filter.IsEnabled(string name)
- Version 1: the help() output does not require any corrections.
Generate the detailed help commands
- Using the Lua program "LuaHelp2Help", or a similar tool, transform the help() output into this format:
help ( print ) help ( absolutebest.AreConditionsMet ) help ( absolutebest.GetEnergyScore ) help ( absolutebest.GetExplorationMultiplier ) ...and so on...
- The transformed help () output should have one help command per function name.
- Run the transformed help() output as a script in the Foldit client.
- The new script log output should have two lines per function name:
void print([arg1,...,argN])</nowiki> Print values to the output window and log file. boolean absolutebest.AreConditionsMet() Return whether the absolute best pose satisfies all conditions. number absolutebest.GetEnergyScore() Get the score for the absolute best pose. number absolutebest.GetExplorationMultiplier() Get the Exploration multiplier. If the current puzzle is not an exploration puzzle, returns 0. ...and so on...
- Each function has two lines in the output. The first line is the function's signature as before, and the second line is a brief description of the function.
- Again, double-check the results. At present, in version 2, the help for behavior.GetFiltersDisabled and behavior.SetFiltersDisabled returns the signatures and descriptions of their deprecated counterparts. These need to be manually corrected. For example, the detailed help output contains two instances of the lines:
boolean behavior.GetSlowFiltersDisabled() (Deprecated - use GetFiltersDisabled) Return whether slow filters are currently disabled. If they are, CPU intensive filters are skipped and your score will not officially count.
void behavior.SetSlowFiltersDisabled(boolean setting) (Deprecated - use SetFiltersDisabled) Set whether slow filters should be disabled. Turn on to skip some CPU intensive filters. Turn off to get credit for your score.
Update one instance of each set of lines to read:
boolean behavior.GetFiltersDisabled() Return whether slow filters are currently disabled. If they are, CPU intensive filters are skipped and your score will not officially count.
void behavior.SetFiltersDisabled(boolean setting) Set whether slow filters should be disabled. Turn on to skip some CPU intensive filters. Turn off to get credit for your score.
- For version 2, TweakRotate and other functions need the opening and closing parentheses added as in the previous phase.
- Version 1: the output does not require any corrections.
Generate the wiki page markup
Using the program "LuaFunctions" or a similar tool, the detailed help() output can be transformed into the wiki markup for the Foldit Lua Functions page.
The output from "LuaFunctions" can be used to replace the wiki page.
The programs LuaHelp2Help and LuaFunctions have been shared as Foldit scripts. If run in the Foldit client, they produce a message explaining that they are standalone programs, and not regular Foldit scripts.
These two programs are intended to be run in a Lua command-line environment. The Lua for Windows package was used to create these programs.
Both programs ignore XML tags, so they can be run using a Foldit script log as their input.
LuaHelp2Help is a simple reformatting of the "help()" output.
LuaFunctions is more complex. Internally, it includes a list of V1 equivalents of the V2 functions, and a description of each function namespace, such as "absolutebest", "structure", and "band". The program also has a list of functions which the author believes are not implemented.
Version 1: LuaFunctions now includes a list of V2 equivalents of the V1 functions.
Detailed procedure
The following procedure was used to update the wiki page on 10 May, 2016.
Version 1: the options required for generating the version 1 functions wiki page have been included.
These steps were performed in a Windows environment with the "Lua for Windows" package installed. The "lua" command at a Windows command prompt invokes the Lua interpreter.
In the examples below, most of the quoted strings are for clarity and emphasis. In most cases, these quoted strings should be retyped without quotes. One exception is when a file name containing spaces is used as a command-line argument, in which case the quotes are required.
The same steps need to be repeated for both version 1 and version 2. Use "v1" and "v2" in the output file names to keep the two versions separate.
- Create a work directory (folder) for the files. Create a new directory each time an update is required, using the release number as part of the directory name. For example, "20160502-30496ba116-win_x86-devprev" is the current release. The current release is available via the "General Options" button on the "Menu" menu. The "Copy" button of general options copies the release id string to the clipboard. The directory name might be something like:
c:\Foldit\Foldit Functions\20160502-30496ba116-win_x86-devprev
- In the Foldit client, download the current version of the two standalone Lua scripts:
Lua Help2Help 1.0 -- http://fold.it/portal/recipe/101069 Lua Functions 1.2 -- http://fold.it/portal/recipe/102310
- In the Foldit recipe editor, use "Save As" then "Export" to save "Lua Help2Help" and "Lua Functions" to the work directory. The names "Lua Help2Help 1.0.lua" and "Lua Functions 1.2.lua" are used here, but names without spaces may be used.
- In the Foldit client, create a track called "help". Recipe output will go to "scriptlog.help.xml". Tracks are created via the "Tracks" button of the "Undo" menu.
- In the Foldit recipe editor, click "New (ScriptV2)". Enter the command "help()" in the editor window. Click "Run".
- Version 1: use the recipe V1 help command to generate the first stage output.
- Copy "scriptlog.help.xml" to the work directory and edit it with the editor of your choice.
- Locate the function "structure.TweakRotate". Add a left parenthesis between "TweakRotate" and "integer" so the line reads:
void structure.TweakRotate(integer segmentIndex, number angle)
- Locate the other problem functions and adjust their entries to read:
bool filter.ConditionSatisfied(string name) number filter.GetBonus(string name) bool filter.IsEnabled(string name)
- Version 1: no manual edits required.
- Save the modified "scriptlog.help.xml". (It's not necessary to remove the XML tags.)
- At a command prompt in the work directory, enter the command (note that the quotes are required here):
lua "Lua Help2Help 1.0.lua" scriptlog.help.xml >LuaHelp2Help.v2.out.txt
- Version 1: use "v1" in the output filename:
lua "Lua Help2Help 1.0.lua" scriptlog.help.xml >LuaHelp2Help.v1.out.txt
- Edit "LuaHelp2Help.v2.out.txt" and copy all lines to the clipboard. (Check that the last line says "0 invalid lines".)
- In the Foldit client, create a new track called "Help2Help". Recipe output will go to "scriptlog.Help2Help.xml".
- In the Foldit recipe editor, click "New (ScriptV2)" and paste in the lines from copied from "LuaHelp2Help.out.v2.txt". (Alternately, use "Load", "Import' to load "LuaHelp2Help.out.v2.txt".) Click "Run" to run the recipe.
- Copy "scriptlog.Help2Help.xml" to the work directory and edit it.
- As in a previous step, update "scriptlog.Help2Help.xml" to add a left parenthesis after "TweakRotate".
- Version 1: no manual edits required.
- Still in "scriptlog.Help2Help.xml", change one entry for "SetSlowFiltersDisabled" to "SetFiltersDisabled" and remove the "deprecated" comment. Similarly, change one instance of "SetSlowFiltersDisabled" to "SetFiltersDisabled" and remove the "deprecated" comment. Save the updated "scriptlog.Help2Help.xml".
- Version 1: no manual edits required.
- At a command prompt in the work directory, enter the command:
lua "LuaFunctions 1.2.lua" scriptlog.Help2Help.xml LuaFunctions.out.v2.txt 20160502-30496ba116-win_x86-devprev
- Version 1: add "V1" at the end of the command line:
lua "LuaFunctions 1.2.lua" scriptlog.Help2Help.xml LuaFunctions.out.v1.txt 20160502-30496ba116-win_x86-devprev V1
- Edit "LuaFunctions.out.v2.txt" and copy all lines to the clipboard.
- On the wiki page Foldit Lua Functions, click the down arrow next to "Edit" then "Classic Editor" from the dropdown. In the classic editor, select the "Source" tab. Delete all the existing text and paste in the contents of "LuaFunctions.out.txt". Use the "Preview" button to preview the page, then click "Publish" if the results look OK.
- Version 1: update Foldit Lua Functions (v1) with the contents of LuaFunctions.out.v1.txt