Scripting syntax (with all details)

At the beginning of a task description, you should tell the computer which keys from the keyboard participants might have to press. This line should be one the first lines in the task description.

Keys given will be associated a keyboard numbers, starting with one. You can use this when saving data. The variable KEY will contain this value when a key has been pressed.

List of all the keys available on all platforms:

The following keys are not availble in the Javascript mode

You can switch the mouse cursor off (hide) or on (show). Look at the following lines you can use in a task.

The table simply refers to a table instruction (which is separately defined from the task, and it will contain information about the different experimental instructions).

Each line in a table will be considered the description of a different experimental condition; therefore, tables allow you to have one task description for different conditions. This way you can vary the color, position, or size of stimuli. It is a key element in PsyToolkit scripts, although you can write scripts without tables as well!

The table row chosen on a given trial is in the variable TABLEROW.

The tablerow will be randomly chosen on each trial by PsyToolkit (depending on what use ask for in the tasklist lines). You can fully override this by using the instruction tablerow followed by a number specifying which tablerow to use.

It is not recommended to use this instructions unless you really know what you are doing.

This function can go wrong if you set a tablerow that is not existing. For example, if your table has four rows, but you give the instruction tablerow 10, it is not clear what would happen.

This is a key instruction, which can show stimuli of the following types:

The number of parameters given to a show instruction can vary.

Imagine you have loaded a bitmap in the bitmaps section of your task description. Now you can show it. Just specify the bitmap, and the bitmap will be shown at screen center. You can also specify the X and Y coordinates (optional).

You can display colored rectangles, specifying the X and Y position as well as the Width and Height. You also need to specify the Red, Green, and Blue values. That means you will have 7 more values!

In the example below, a rectangle is show at position 0,0 and it has both a width and a height of 100 pixels. The red/green/blue values are set to 255/0/0. The maximum value in each of these three color channels is 255. Given that only red is specified, the rectangle will be red.

Show a circle. Similar to show rectangle.

The 3rd parameter is the radius in pixels (thus, the width is twice the radius).

Instead of R G B color values, you can use a color name

Show a line. For this, you need to specify the X and Y coordinates of the beginning and end point of a line.

You can specify the color (using Red Green Blue notation)

Sometimes you want the whole screen to have a specific color. In principle, you could just draw a rectangle the size of the screen. The "show background" function does exactly that. You just give the three color parameters and the whole screen will be filled with that color. Otherwise, it is treated like a normal screen stimulus and it has a number and it can be cleared.

The show text instruction shows text.

If you want, you can specify a font and font size as well in the fonts section

While "show text …​" is for actually displaying the text, you can set the alignment of color separately. That is easy if you for example want to present multiple texts in the same color.

Alternatively, you can use a color name directly in the show text line as follows:

To erase a stimulus you put on the screen with "show", you can erase with clear. The call "clear" takes at least one parameter. The number corresponds to the count of show calls. For example, if you want to erase a particular bitmap which was shown as the second show event in your task, use "clear 2". Alternatively, you can use negative referral numbers to refer to preceding stimuli: -1 refers to the last presented bitmap! Using the negative referrals is actually much easier to use, because that way you do not need to count bitmaps.

The hide functions does exactly what the clear function does, except that this way you can also unhide the stimulus again.

Using hide, you do not change the stimulus count of the stimulus. Sometimes, this can be handy.

It is possible to rotate bitmaps presented with the "show bitmap" command. A good example is given in the Mackworth example in the PsyToolkit experiment library.

The delay instruction pauses the program for the specified number of milliseconds. You will need this function often, for example, if you want to show a stimulus for a specific time interval, or for waiting between trials.

The readkey instruction tells the computer to wait for a keyboard response. The first argument, the correct key, corresponds to the keys in the keys instruction.

In the following example, there are two possible keys in the task (named MyTask), the a and the z key. Imagine that a stimulus requires the z button to be pressed, that is the second key (with a being the first in the line "keys"). The readkey command will now way 3 seconds for a key press. If the participants presses the z key, the STATUS will be set to CORRECT (which equals numerical value 1). If the participants presses the wrong key, it will be WRONG (numerical value 2), and if there is no response at all within 3000 ms, the STATUS code will be TIMEOUT (numerical value 3).

After a call to readkey, the user can use the following variables:

readkeys is completely different from readkey.

Here is an overview of the differences and similarities:

Example use of readkeys

There is also a code example lesson about readkeys.

A more complex function using the readkeys option statements.

Note, by default:

Readkeys options:

Some explanations about the above example:

In the example above, the final readkeys line waits for 10000 ms until people have entered one or more letters (participant pressing the return/enter key ends the entry). If people entered "apple", they status is set to "correct" (i.e., value 1).

The textbox creates a box in which people can enter text. Unlike the readkeys statement, the textbox allows special character entry as well (including Chinese text entry, special characters in European languages, and so on.

You can also use textbox to simply show a long wrapped text.

The textbox was introduced in the 3.4.* series.0 and will be developed further. Currently, a textbox is shown with the instruction textbox new and you can provide multiple arguments. Below is an example in which the following are used: x-position, y-position, width, height, textcolor, background color, textfont size and font family (such as arial or times).

The focus is used for when people need to enter text.

In the following example, the participant needs to enter words followed by enter. The textbox instruction draws a 700 by 500 pixels with a blue background and with white text on it. The text that will appear in it will have size 24 in font Arial.

The textbox is followed by a readkey. If you set the time to 999999 it basically waits for 999 seconds, which is quite long for an experiment.

The full syntax of the relevant functions is as follows

Similar to readkey, you can check if the participant clicked the mousekey, and if so, if the mouse was where it should be. You can also just wait for the mouse to be moved into a certain area of the screen. In fact, you can check if the location of a specific stimulus has been touched with the mouse (bitmap, or rectangle, or text).

Here are the different options

In the following example, we show two rectangles, and we want that the participant mouse the mouse over the green one (the first bitmap), which is positioned on the left (-200). We give maximally 5 seconds, that is 5000 milliseconds.

In the example above, the first rectangle is a grey rectangle that is just a background. Because that rectangle is almost as big as the whole experiment screen, we need to tell PsyToolkit that we do not care about that stimulus in regard to the mouse being over it. To do so, we use range in the readmouse instruction. This means, in this case, only consider if stimulus 2 or stimulus 3 has been hovered over.

In the following example, we have exactly the same task, but we want that the mouse is being clicked as well as in the first stimulus. We add the "l" argument, with "l" standing for the left mousebutton. In Javascript, it is recommended only to use the left mousebutton, because the right mouse button might show a browser-specific menu, which is obviously not something you want.

There is one issue that arises if you have stimuli that overlap each other. Imagine the following situation. You have one big rectangle that is just their to show a clear yellow rectangle, and on top of that is a much smaller rectangle. If you want that people click that second smaller rectangle, you need to tell the computer that you do not care about the first one. The way to do that is to specify the range of bitmaps that you are interested in. See example below:

Finally, there is a special hovering case, where you can ask readmouse only to respond if the mouse hovers over the requested target, and not to respond with error for any other stimuli. For this, you just add the option find.

In the above case, you can hover over the right rectangle, but PsyToolkit will fully ignore this, and only look for the left stimulus. This can be useful in certain situations. For example, if you want that a participant finds one object among many. The participant might hover over all the objects until the person has seen the target object. You could, of course, also do that with a "range", but this is shorted and for this, you do not need to know exactly the numbers for the range parameter, so it makes things simpler.

The drag function allows you to drag a stimulus from one location to another. There are many options to do so. Often it is easiest to look at a simple example first. Best to read the lesson about https:/lessons/drag.html[drag] for detailed examples.

Below are also basic examples, but first an overview. Note that the italic values need to be replaced with numbers of variables. What is in square brackets are various different options. More details further down.

In its simplest possible form, you can have an example like this. Note that you will always need to provide *drag option" lines to tell PsyToolkit which stimulus needs to be dragged.

In this example, you show one stimulus (stimulus number 1) in yellow (yellow is RGB: 255 255 0). You tell PsyToolkit that the stimulus that can be dragged from somewhere is in this cases stimulus number 1. You give up to 60000 milliseconds (that is 60 seconds) for the dragging.

There are more options. For example, you can PsyToolkit that there are more stimuli that can be dragged from. For *drag option from" you can specify multiple stimuli or even an array, as in the example below.

The drag option to specifies the value(s) of one or more stimuli. In its simplest form, you can have an example such as this:

Dragging allows your participant to continue dragging stimuli around the screen until done. When they are done (but before maximum response time) they need to press the exit button. For this, you can specify a specific stimulus.

All the options of drag can also be used for dragging, but there is one additional option.

In the example below, two red and two green rectangles are shown. A fifth yellow rectangle (with the text "Exit" on it) functions as an exit button. You need to drag the red rectangles onto the green ones.

The following variables can be used for accessing information about drag actions. You do not necessarily need these.

DRAGGED contains the number of the stimulus a participant dragged. This is interesting when a participant can choose to drag one out of multiple stimuli.

DRAGGED_ON contains the number of the stimulus a participant dragged onto.

DRAGGED_CHANGED Contains 1 if the participant dragged a stimulus, and 0 if nothing was dragged.

DRAG_OLD_X If a stimulus was dragged, its previous X position before dragging started.

DRAG_OLD_Y If a stimulus was dragged, its previous Y position before

DRAG_X If a stimulus was dragged, its current X position.

DRAG_Y If a stimulus was dragged, its current Y position.

PsyToolkit can show a progress bar. This can be useful if you want to tell people how many trials they have done and how long it will take to finish.

It is actually really easy to show. There are a number of options to color and shape the progress bar the way you like, but the default is a simple narrow horizontal progress bar at the top of the screen.

The command is simple: show progressbar done todo

Whereby the first number is the trials done so far and the second number is the total trials the participant will have to do.

In the example below, the show progress command shows the progress bar. It is followed by the TRIALCOUNT (trials done so far) and the total number of trials (here for example 30).

There is a special set of options that you can set within your task (and not in the options section). Below is an example in which you can set the two colors (one for the color of the trials done and one for the background color, by default these are green and grey, respectively).

These options have the following meaning.

Note, instead of color1 and color2 you can also just write:

Under certain circumstances, you want to ask the participant to click multiple stimuli on the screen. Ideally, you would want to allow the participant to select objects and deselect as well. This is all possible with the function choose.

In short, choose will let the participant click on a range stimuli, show a symbol on top of the stimuli, and when clicked again the symbol will disappear.

It is easiest to learn how this works from an example.

In the following example, there are three symbols shown on the screen that can be selected with a selector bitmap. Options for this command can be set before choose is called with choose option. The participant has 60 seconds (60,000 milliseconds).

Note the following things about the above example:

There are various other options:

Sometimes people want a Likert scale in their experiment. For example, you might show a shopping item and ask people, how likely would you be buying this in the next week on a scale from one to five. This is now super easy to do.

This gives you the most basic type of a Likert scale. By default, the points of the likert scale are yellow circles and left and right, you see a small white box. In reality, you want a lot more. For that, you can give options. First of all, you can select a location with the "option pos" followed by an x and y coordinate.

In the example below, the scale is now shown left of center.

In the example below, we add nicer bitmaps instead of the default drawing symbols. In PsyToolkit, there is the option labels for rate, so that you can make a bitmap with the label texts "not at all" and "very much" or just simple arrows in the example below. The "option items" just specifies the bitmap of the clickable points on the scale.

Also, in the example below we have 7 items and people must make choice within 5 seconds.

Saves variables. Typically, a task ends with a save line.

Used to play sounds. A sound just starts playing the code continues. If you want to do nothing during the sound, you need to have it followed by a delay. You can also stop the sound at any time using the silence instruction.

You can use if to only carry out some commands. This is often needed for showing a feedback message if people make a mistake. The opposite of if is fi.

With if, you can also compare two arrays

Similar to if, you can put code in a "while loop". The while loop is ended with the while-end statement.

Everything between a while and while-end statement will be carried out until the condition on the while line is satisfied.

You can set the font of the next *show text" instruction.

You can end the task at any point in your list of statements in a task. You can even end the current tasklist or the whole experiment. All you need to do is end task , end tasklist , or end experiment

This can be useful, for example, when people are training and you want to stop the block of trials when they made a mistake.

This is, however, a statement that you will rarely need.

timestamp can be used to capture the current time. This can be handy if you are checking the time past in a while..while-end loop. It can also be handy if you are trying to debug code and check if the timing is as expected.

You can get the timestamp-diff between two timestamp variables using the set command as in the example below. Timestamps cannot be directly accessed or used other than through set timestamp-diff

The bitmap is simple. You often want to show a bitmap with an instruction and then wait for a keypress.

As in the task, you can start a sound with sound and stop it with silence

As in tasks, you can put in a delay. Sometimes this is nice for countdowns.

Instead of showing a bitmap and waiting for a key, you can combine this in one command, called message.

Sometimes you want a series of instructions and let the user browse through it. In other words, you have series of pictures (or "pages", hence the word "pager") that you want to show one after another.

The pager command let you do exactly this.

Users can use the arrow keys and use the Q key to get out of it. The space bar will go to the next image/page. Make sure that all these bitmaps are in the bitmap section.

Alternatively, you can use the mouse (or touch) to scroll through the instruction pages. For this, you need to give some more information. If you are a beginner, try the basic pagers as explained above first.

In the example below, we use the pager option to tell the computer the following:

Thus, apart from the instructions, on each screen there are 3 bitmaps, one for going back through the instructions, one for going forward, and one for leaving the instructions. The latter one is only shown once the participant has gone through them all.

Note, for this experiment, you need to have bitmaps for the images: back, next, start, MyInstruction1, MyInstruction2, MyInstruction3.