Lua Scripting Tutorial (Beginner 2)

Introduction

This tutorial is a continuation of Lua Scripting Tutorial (Beginner 1). It builds on the skills and knowledge you will have acquired in Beginner 1, such as downloading and running a script from the web and using an output window.

Beginner 2 Goals

In Beginner 2, you will work with some scripts that require the select interface.  This will help us lead up to being able to look at and modify Lua scripts for the first time.  Although you will not do much substantial modification of scripts in this tutorial, it will set the stage for learning all about Lua commands

in Beginner 3.   By the end of this tutorial, you should be able to:

This script requires the select interface!

• Run scripts that require the select interface
• View and understand error messages related to the select interface
• Open and view a script
• Modify an existing script and save it
• Understand how to use two basic commands: print and select_index_range.

Using the Select Interface with Scripts

As we mentioned in Rebuild SCRIPT 1.00 Beginner 1, some scripts require the use of the select interface

. You can usually determine whether this is the case for a particular script that you get from the web by looking carefully at its description. 

Using the select interface

In the new interface in Foldit, you can select one or more segments of a protein. These selected segments become the target of all the in-game controls you use from then on -- likewise, if you run a script, only these selected segments will be affected.  Of course, you can always "deselect" these segments and select new ones if you want!

Like many tasks you can do in Foldit, it is possible to select and deselect segments by hand with your mouse or within a script by using a special statement.  Let's see how it works to select segments by hand:

Segments turn purple when they're selected.

1. With the game open, download theBeginner Rebuild SCRIPT 2.00  from the web.
2. Switch to the “New Interface” if you're not using it already. You'll always need to use the new interface if you run a script that requires select, but don't worry – if you hate it, you can switch back to the old interface in between running scripts.
3. We want to select about five or six connected segments of the protein. Hold down shift and click on the segment where you'd like to start and then click on the segment where you'd like to end.  Or you can use control shift and drag to select the segments.  They will puff up and turn bright blue/purple!
4. Make sure all those segments are connected to each other and that you have no other segments selected. Then open an output window and go ahead and run the script.

What is this script doing? You might notice that it looks pretty similar to our other automated rebuild script. In fact, we'll find out that it is almost identical – the only difference is that in our new script, we can pick our own segments to auto-rebuild, whereas in the earlier script, segments 1-10 were picked for us.

Directions for using the select interface

Oops! Forgetting to use Select

In Beginner 1, we looked at an output window

. Let's see an example of why this little window is so important when you're running scripts by intentionally making a mistake to see what happens.

The error we get when forgetting to use select isn't very informative!

1. ake sure that there are no segments that are selected – if there are any, deselect them using the same shift-click technique you learned.
2. ith an output window open, run the script again.
3. hat happened? You should see an error message in pink text in the output window.  Although it's not very informative, it does tell us that we made an error by not selecting any segments ("bad argument ... (invalid selection)").
4. o ahead and fix that error by selecting connected segments and then rerunning the script!

The error message explains what we did wrong, but note that it isn't always very informative – in fact, for non-programmers, it can be downright confusing!  There are many different messages you might get – for now, you should just be comfortable understanding error messages related to select and knowing how to fix them.

Editing a script

Looking at Your First Script

In Beginner 1, we noted that a script is like a recipe for baking a cake – a series of simple, step by step instructions that need to be followed in order. For a cake recipe, our instructions might be “sift flour”, “beat eggs”, “mix flour and sugar” and so on. For a fold-it script, our instructions, which we call commands, might be “wiggle”, “shake”, “add bands”, “rebuild”, and so on. However, we need to state these instructions in a very specific way that looks complicated to humans but is simple to understand for computers. For example, “add bands between segment 5 and 10” might have to be stated: band_add_segment_segment(5, 10).

So let's open a script and see what these commands look like.

Editing a script

1. We're going to look at our first beginner script, Rebuild SCRIPT 1.00 http://fold.it/portal/recipe/1929, so locate it in your list of scripts (or download it if you haven't already).
2. Hover over the script with your mouse and click the little icon that looks like a notebook ("edit recipe").  
3. You will see a plain text window pop up over the top of foldit.
4. Take a close look and see if you can figure out what is going on in the script. You are not going to understand it all, but you should notice the words “rebuild”, “wiggle, “shake”, and the like. You may also notice phrases that you saw pop up in the output window!   They will look like this: print("you're running your first script!"). Finally, look closely at this line: select_index_range(1,10) -- what is happening here?
5. Close that script and now open the second beginner script again.  Study the text. Can you see how the two scripts are different?

Edit a script using a plain text editor.

The two scripts are identical except for two lines. Our beginner 1 script had these lines:

deselect_all()
select_index_range(1,10)
which, as you can guess, tells the computer to first deselect anything that is currently selected (wiping the slate clean -- always a good idea in a script that will be using select, just in case the user has some segments selected by mistake!) and then to select segments 1 through 10 on the protein. Our beginner 2 script is missing these lines.  Therefore, it did not work unless we went in and selected segments by hand.

To be continued!