This page is merely meant to look up instructions of the PsyToolkit scripts. It assumes you know more or less what you are looking for. If you are new to PsyToolkit, it is easier to start looking at some of the examples here or more detailed examples in the experiment library.

Other relevant documents:

How to use this experiment-script overview page

This page lists all possible elements of a PsyToolkit script. It will also give a short syntax description. A syntax is a description of how instructions can be used. In the syntax description, the compulsory arguments of an instruction are in square brackets []. The optional arguments in normal brackets (). A | sign indicates different valid values for an argument.

For example, take the example for the instruction "show rectangle". The example below shows that there are 4 compulsory arguments: X,Y,W,H. This is the x-coordinate, the y-coordinate, the width and height. The arguments Red, Green, and Blue are optional (by default, a rectangle is white, but you can give it different colors)

Note show rectangle [X,Y,W,H](Red,Green,Blue|Colorname)
The brackets in the syntax description are, of course, not typed in the real script; it is just a way of describing a syntax. Look carefully at the examples given for each instruction to see on how to use instructions.

structure of scripts

There are different sections in scripts, and each section is separated from others by at least one empty line.
Everything following a hash mark is a comment only for human’s eyes, the computer will ignore it.

The main sections which contain multiple lines each are:

  • basic options describes handy non-default PsyToolkit settings such as screen size

  • advanced options describes advanced options beginners can ignore

  • linux-only options special advanced options when using the Linux version

  • bitmaps/sounds/fonts describes which stimuli to use

  • task can be used multiple times to describe paradigm trials

  • table can be used multiple times to describe experimental conditions

  • block can be used multiple times to run blocks of trials

  • blockorder order of blocks can optionally be set in a different way (advanced users only)

basic options

Whenever you program an experiment, you may want to deviate from the default values. For example, the default screen size of an experiment is 800 by 600 pixels, but you can change this using the option "resolution". The available options are listed below. At the bottom of this section is a complete example.

There are many options, but they are mostly for advanced users. If you are new to PsyToolkit, you at first ignore the options.

resolution

This sets the resolution of the experiment. This default resolution is 800 by 600.

When specifying the resolution, it is width by height, separated only by a space. See example below.
Example of fullscreen (with randomly jumping rectangle)
options
  fullscreen
  resolution 1000 800

task MyTask
  set $x random -300 300 # random x position
  set $y random -300 300 # random y position
  set $mysize random 10 100
  show rectangle $x $y $mysize $mysize   255 0 0 # show red rectangle
  show rectangle -100 -100 $mysize $mysize   green # show green rectangle
  delay 200
  clear -1
  delay 200
  clear -2

block MyBlock
  tasklist
    MyTask 200
  end
You can instead also write the resolution with an x. For example:
Alternative notation (with x)
options
  resolution 1000x800

frame

This sets the size of the box of the experiment in an online experiment when not in full screen mode. This is rarely needed, but it is nice to know you can adjust this.

In the example below, you work with a 1000 800 resolution. But without the frame option, this would be scaled down to 800 by 600 in the non-fullscreen mode. If you want that in the non-window mode, the box appears bigger, you can adjust that with frame.

Example of frame (with randomly jumping rectangle)
options
  fullscreen
  resolution 1000 800
  frame 1000 800
Frame might not be needed often. When you use it, it will most likely have the same numbers as fullscreen.

scale

The scale option allows you to scale the screen. This is practical in fullscreen mode or for resolutions bigger than the default 800 by 600 pixel area. PsyToolkit will always keep the correct aspect ratio.

When does this take effect?

  • When you go into fullscreen (it will scale up)

  • When you have a larger than 800 x 600 resolution and are not in full screen mode (it will scale down)

Example of scale
options
  fullscreen
  scale
  resolution 1600 1200

background color

You can specify the background color of the screen. By default it is black, but you can set it here to a different color. You can either specify it using a color name (one of red,green,blue,white,yellow,pink,purple,black,orange) or a RGB triplet (like 255 0 0 for red), or a hexadecimal six letter/number combination (like FF0000 for red).

Example of background
options
  background color white

task MyTask
  set $x random -300 300 # random x position
  set $y random -300 300 # random y position
  set $mysize random 10 100
  show rectangle $x $y $mysize $mysize   255 255 0 # show yellow rectangle
  delay 100
  clear -1

block MyBlock
  tasklist
    MyTask 200
  end
Other example of using a RGB triplet (in this case white)
options
  background color 255 255 255
Other example of background using a hex code
options
  background color FFFF00

fullscreen

Runs experiment in fullscreen mode. In Linux, this is the default, whereas in the browser it is not.

Example of fullscreen (with randomly jumping rectangle)
options
  fullscreen

task MyTask
  set $x random -300 300 # random x position
  set $y random -300 300 # random y position
  set $mysize random 10 100
  show rectangle $x $y $mysize $mysize   255 255 0 # show yellow rectangle
  delay 100
  clear -1

block MyBlock
  tasklist
    MyTask 200
  end

mouse

By default, the mouse cursor is not shown, because from a psychological point of view it can be a distracting stimulus. But for some experiments, the mouse is needed as a pointing device. This option makes sure the mouse cursor is visible. The only useful value is "on".

Example of showing mouse in an experiment
options
  mouse on
The option only switches the mouse on at the start of the experiment. You can still switch it off later in a task using the mouse hide and mouse show instructions. Click here to read more about those two instructions.

set

This lets you set a global variable. This can be handy if you want to test an experimental parameter (e.g., intertrial interval) to a specific value throughout the experiment. If you do not use the variable anywhere, this set value will just be ignored.

Example of "set" in options
options
  fullscreen
  set &my_intertrialinterval 100

task MyTask
  set $x random -300 300 # random x position
  set $y random -300 300 # random y position
  set $mysize random 10 100
  show rectangle $x $y $mysize $mysize   255 0 0 # show red rectangle
  delay 100
  clear -1
  delay &my_intertrialinterval

block MyBlock
  tasklist
    MyTask 200
  end
Sometimes it is handy to have set some basic parameters in the options as global variables. That way, you can easily find them back. Good examples are intertrial intervals, maximum allowed response times, stimulus size, etc.

start messages

In the web-based version, every experiment starts with a red box and the English message Click to start. Also, depending on the time it takes to load the messages, you will see a message wait a second.

You can change these two messages with the following two options:

Example of changing start messages
options
  startbutton text My own click-to-start message
  loading text My own wait-a-second message

advanced options

var in

When you use PsyToolkit within online PsyToolkit surveys, you can exchange numerical variables between the experiments and a survey.

You can only exchange whole-number numerical variables. That is, numbers such as 12 or 3, but not letters, number-letter combinations, and neither fractional numbers (such as 12.1 or 3.4)

For example, you can have a survey question asking for someone’s age, and then subsequently use the age as a variable in the experiment. You need to specify the survey label. Below is an example.

Example of a survey question first. Note: this is thus not experiment scripting code!
l: sleep
t: range
q: how many hours sleep did you have?
- {min=0,max=10} Select number

l: alcohol
t: range
q: how many glasses of alcohol did you dring?
- {min=0,max=20} Select number

l: the_experiment
t: experiment
- my_experiment

l: information
t: info
q: Your score is {$xxx} and {$yyy}.
In the following experiment, participants are asked to respond to a rectangle. Let’s assume that sleepy people or those with alcohol need more time, we want to give them more time, so we make the maximum time they can respond in longer. We create a new variable MyMaxTime based on their alcohol consumption and there hours of sleep. The more they have drunk or the less they have slept, the higher &MyMaxTime will be. This just shows how you can use the variables
Note that the variables sleep and alcohol are treated as global variables, and need to be preceded by the & sign.
Example of using a survey answer in an experiment
options
  var in sleep alcohol

task myTask
  keys space
  show rectangle 0 0 100 100
  set &MyMaxTime expression 1000 + 100 * &alcohol + 100 * ( 10 - &sleep )
  readkey 1 &MyMaxTime
  save RT

block
  tasklist
    myTask 10
  end
I used spaces, but you can also write this:
Example of expression without many spaces
  set &MyMaxTime expression 1000+100*&alcohol+100*(10-&sleep)

var out

The option var out can be used to save a value created in an experiment directly to the survey. If you do this, the saved value will be available in the questionnaire spreadsheet.

Example of using a survey answer in an experiment
options
  var out my_score
Example of survey question working with this. Note that this script is for online surveys only.
l: my_feedback
t: info
q: Your score was {$my_score}

origin

Visual stimuli are presented on the screen, and you need to give an X and a Y coordinate to place them. The origin option tells the computer where point X=0,Y=0 (or 0,0) is.

By default, the coordinate point 0,0 is at the center of the screen. Alternatively, you can set the top-left corner of the screen as the origin (which was the default in older versions of PsyToolkit).

Example of how to use origin
options
  origin topleft

fontdir,datadir,bitmapdir,sounddir

The options fontdir,datadir,bitmapdir,sounddir let you change the folders where the computer expects the stimuli to be saved. You do not need to specify this if the stimuli files are in the same directory as your scripting code.

This option makes most sense if you work in C or have large experiments.

Linux-only options

escape (C only)

In the Linux Desktop version, this makes it possible to end the program to by pressing the escape key. Please notice that the computer only tests whether the escape button has been pressed at the end of each trial. Hence, if you use this option, and if you want to break out your experiment, you have to hold the escape button (or whatever button you use for escaping) for the duration of at least one trial.

In the browser function, you can always escape out of your experiment, and there this option is not necessary.

parallelport (C only)

This is for advanced coding of the parallel port.

pcidio24 (C only)

This is for advanced coding of the pcidio24 port

cedrus (C only)

This indicates that you have attached a Cedrus keyboard. Optionally, you can specify a model. If you specify a model, the script will only run with that model. That strictness is only necessary in case you want to force people to use a specific Cedrus keypad.

iolab (C only)

It seems this device is no longer produced. PsyToolkit still supports it.

This indicates that you have attached the IoLab device (a special keyboard with push buttons). Optionally, you can specify the voicekey parameters (see psycc -s)

et (Linux only)

Support for the Tobii eye-tracker is being developed. Currently, the code is under development for model tx300. This works only on linux

Example of how to tell PsyToolkit about your Tobii eye-tracker
options
  et tobii 12345
The number 12345 is here an example of a Tobii tracker ID. It is optional to give that identification number.

sprites first (Linux only)

Advanced use only

The option sprites first will draw the sprites before it draws any other stimuli. This means that sprites will be drawn in the background, which is what you want for certain situations.

executable

The filename of the executable program. Per default, this is "experiment", but it can be set with the command line option -o and with this option.

The -o option will override this option. In the online version, this option will be ignored.

egi (C only)

With the host ipname or ipaddress and the (optional) ip port sets up a connection to the Electrical Geodesics, Inc System. This has not been tested well, and is based on old code.

You do not need to use any options if you do not want to.
Example of all basic options
options
  resolution 1024 800
  fullscreen
  mouse off
  set &my_variable 100

vsync on|off

Not relevant for the Web-based version.

Advanced users only. In Linux mode, this is "on" by default, but can be switched off, because some graphics cards do not allow to use the vsync. PsyToolkit will actually complain if it is not available.

If set to "off, the computer does not wait for synchronization of the vsync (this is the default in Javascript). This is handy for testing, since the experiment does not need the root permission during compilation. In C, if you use the -t option, this is the default.

Example of vsync off
option
  vsync off

window (C only)

This lets you run the experiment in a window instead of in full screen. This is good for testing. Note that the full screen mode is the default mode in Linux, unless you run in test mode.

Because PsyToolkit can run in two different programming environments, some functions do not work in all environments. C only functions only run on the Linux version which is based on the C programming language. If you use the online version, you can fully ignore these.

screensize and screendistance (C only)

This lets you set the dimensions of the screen and the eye-screen distance. Units are in millimeters. These numbers are necessary if you want to use the option coordinates polar or if you want to use the report stimulus size command line option. If you use a polar coordinate system (which is rare), all xy coordinates should be specified in 100ths of degrees (thus 100 = 1 degree, 200 = 2 degrees of visual angle). This is not well implemented yet (let me know if you need this).

version

This is only for advanced users. This will only allow to compile a script with the corresponding psycc version. This is practical if you have multiple versions of psycc installed, and when you just want to make sure that the code runs. This command has no effect in the online version.

check_refresh_rate

Linux only. You can check if the refresh rate is as expected, and if not a message will be shown on screen.

This is useful if you have an advanced monitor and you want to make sure the refresh rate is not reset to a lower value by some other desktop manager. Note that only XFCE has a nice way of setting the refresh rate (settings→display).
Example of check_refresh_rate
options
  resolution 1920 1080
  check_refresh_rate 144

In the above example, we set the screen to what is today pretty much a standard resolution (read more about this so-called 'full HD'). Then we tell the computer that we expect that the graphics card and monitor run at a refresh rate of 144 Hz. PsyToolkit cannot set this, but it can check it. If PsyToolkit finds that the screen is not running at the expected refresh rate, it will give a message and then stop.

Example of all basic options
options
  fontdir     /usr/lib/fonts
  datadir     /home/user/mydatadir
  bitmapdir   /usr/local/bitmaps
  sounddir    /usr/local/snd
  origin      topleft
  window
  resolution 1024 800
  screensize 1000 600
  screendistance 500
  coordinates polar
  vsync off
  escape
  egi 10.0.0.42
  parallelport in data out 1 5
  pcidio24 in a b out c_low c_high
  cedrus
  iolab
  executable myexperiment
  set &myinterval 100
  sprites first

loading stimuli

The computer needs to know which stimuli you use. Stimuli are typically images or sounds, and these need to be loaded. You can also load fonts. Below is explained on how to load bitmaps, sounds, and fonts.

Bitmap and sound-file names are not allowed to start with a number, are not allowed to contain spaces or special characters (except underscore).

bitmaps

The bitmaps command lets you define a number of bitmaps you want to use in your experiment. Bitmaps can be of common formats, png, jpg, bmp, and gif (although animations are not shown, instead use videos).

The bitmaps line has no parameters, and is followed by lines describing the bitmap, each bitmap having a name and (optional) a file description.

Do not put anything is quotes, and don’t use spaces in the descriptions or in the filenames.

If you don’t add a filename, it assume that a filename exists with the same name (of type png, jpg, bmp, or gif). In the example below, PsyToolkit assumes a file house.png (or house.jpg, etc) to exist because no further bitmap info is given. This is actually the recommended way of working (it is definitely easiest).

Alternatively, you can have a different filename.

Example of bitmaps and how to refer to them in a task
bitmaps
  house
  funnyface funny.bmp
  cookie    stimuli/cookie.jpeg
  smiley

task MyTask
  show bitmap funnyface
  show bitmap cookie 100 0

Note that for Javascripted experiments in a browser, there are two additional ways to load bitmaps:

1: using the http:// prefix (thus, instead of a full filename, give the URL). This makes sense under very special circumstances, and is not generally recommended, unless you really know what you are doing. The reason for this is that this can speed up download times of online experiments considerably. This because per default, all stimuli are embedded in the HTML file via data:uri, which can lead to large HTML files.

Here is how you do it in PsyToolkit

Example of loading bitmaps from external websites
bitmaps
  house http://www.my-website.com/house.png

task MyTask
  show bitmap house

2: using data:image/ uris

For more information on how data URI works see data URI on Wikipedia

The data uri is only for very rare and special occasions, and is generally not recommended (because it is not really necessary, but there are some unusual technical reasons why someone might want it under super-unusual conditions)
Example of loading bitmaps using a data-uri
bitmaps
  testimage data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAADCAIAAAA7ljmRAAAAGElEQVQIW2P4DwcMDAxAfBvMAhEQMYgcACEHG8ELxtbPAAAAAElFTkSuQmCC

task MyTask
  show bitmap testimage

move

move and relocate are not often used. It is mostly used for basic animations and then are very practical.
move does not give a smooth animation, it is just a change of location. See the simple animations lesson for details.

Sometimes, you want to change the location of a stimulus that you have already created on screen. This can be useful for simple animations.

You can do this with two different functions in tasks:

  1. move

  2. relocate (described next)

The following example shows a stimulus at screen center and after 1000 ms moves the stimulus 20 pixels to the right, while not changing the y location. Thus, the move gives the X and Y amount of change (whereas relocate gives a complete new X/Y position).

Example of moving a stimulus
bitmaps
  smiley.png

task MyTask
  show bitmap smiley
  delay 1000
  move 1 20 0

relocate

Relocate is very similar to move, except that you just give the new coordinates.

Example of relocating a stimulus
bitmaps
  smiley.png

task MyTask
  show bitmap smiley
  delay 1000
  relocate 1 100 150

sounds

This works like the "bitmaps" commands, just to tell the computer which sounds are being loaded. You can use any sound file format, although the mp3 file format is the one that is most widely used and recommended for online studies. MP3 files are much smaller than WAV files (MP3 files are compressed).

Example of sounds and how to refer to them in a task
sounds
  barkingdog bark.wav
  phone      ringingphone.mp3

task MyTask
  sound phone
  delay 300
If you use common file formats mp3, wav, ogg, or flac, you actually do not need to specify the file format, but you can if the file starts with the same as the name you use. So you could make the above code simpler as follows (PsyToolkit will itself figure out the file extension.
Example of sounds and how to refer to them in a task
sounds
  bark
  ringingphone

task MyTask
  sound phone
  delay 300
As for bitmaps, you can also load a sound from a web server (using http://). The advantage is that this leads to quicker loading times.
You can also use sounds in the block, for example to play some music when the participant is doing the task. This can be used to test the effect of different types of sounds, music, background noise on task performance. See sound in a block.
Example, get duration of sound (this does not seem to work reliably across browsers)
set $x duration my_sound
play my_sound
delay $x
Instead of the word sound, you can also write play, it means exactly the same.

sound frequencies

Apart from playing sound files, you can also play specific tones or frequencies. This also uses the sound instruction, but now followed by the word freq. Below are various examples:

Play a 500 Herz (Hz) sinus wave sound for 1 second (1000 ms).
  sound freq sine 400 2000
Play a 400 Herz (Hz) square wave sound for 2 seconds (2000 ms).
  sound freq sine 400 2000
Play a 700 Herz (Hz) triangle wave sound for 1.5 seconds (1500 ms).
  sound freq triangle 700 1500
Play a 600 Herz (Hz) sawtooth wave sound for half a second second (500 ms).
  sound freq sawtooth 600 500

How to stop a frequency sound. For this, you use the silence instrcuction, but you must use a negative number. The last started sound is -1, the one started before that -2, etc. See example below.

Stop a frequency sound before it actual duration
  sound freq sine 400 5000
  delay 500
  sound freq sawtooth 700 5000
  delay 500
  silence -1 # stops the sawtooth
  delay 500
  silence -2 # stops the sine

fonts

By default, without telling the computer what font you want to use, PsyToolkit will use Arial 20 points. You do not need to define a font if you do not want to anything else than Arial of size 20 points.

Here you can describe which fonts to use. You can use built-in fonts (arial, times, courier) or load ttf fonts (since 2.3.3 also in Javascript). If you use them online, you need to upload your ttf just like you upload any other stimuli.

Note that the same fonts go by different names. If you are not familiar with the most common types, check WikiPedia for information about Arial, information about Times New Roman, and information about Courier.
You can use one of the three default font types: arial, times, or courier. If you use one of these three fonts, you do not need to upload or include a font file, because these fonts are already available on computers. On Linux, Arial=FreeSans.ttf, Times=FreeSerif.ttf, and Courier=FreeMono.ttf.
Example of fonts and how to refer to them in a task
fonts
  arial 18
  myfont times 20
  mysmallfont arial.ttf 20
  mybigfont   arial.ttf 40

task MyTask
  font mysmallfont
  show text "hello"
  delay 1000
  font mybigfont
  show text "world"
  delay 1000
  font arial
  show text "Some text in standard arial"
  font myfont
  show text "Some text in Times New Roman"
  delay 1000

See also show text.

videos

You can use videos in your experiment. You need to tell PsyToolkit where the videos are stored on the internet. You cannot store them on the PsyToolkit server itself.

It is easier to upload a video file to the Google Drive or to Dropbox. There is a lesson on how to do this in detail.

You can give the video any name, for example, in the example below clip1 and clip2 were chosen, but it could just as well be my_video1 and my_video2.

Example of a video section with two clips
videos
  clip1 https://www.dropbox.com/s/kzo7sx7hkdai16i/beetle.mp4?dl=0
  clip2 https://www.dropbox.com/s/bzbs6qpk7ht9yyu/frog.mp4?dl=0

tasks

In PsyToolkit, a task (typically) describes the sequence of exactly one trial of an experiment.

This includes showing or playing audio stimuli, waiting for key/mouse presses, time delays, if/then loops and all sorts of other things.

Tasks are the most difficult part of the scripting language, because they involve writing real sequential computer instructions to show stimuli, wait for responses, etc. Lots of things are possible, and there are many different instruction types. Each instruction type is described below.

Before describing the instructions, a number of fundamental elements of the language are described, namely the structure of tasks, variables, and timestamps.

how tasks are structured

Tasks are really used to program what happens in one trial of a experiment paradigm. A task is just a sequence of instructions, ended with an empty line. The instructions contain the following major parts of information:

  • Where a description of the different experimental conditions is. This can be done with the table statement

  • How exactly the participant should respond (e.g., which keyboard keys, or with the mouse). This can be done, for example, with keys and readkey.

  • The stimuli being used, and when and where they should be presented. This can be done with show and sound.

  • Which data should be saved to a file for later data analysis. This is done with the instruction save

Showing stimuli

Showing (or playing audio) stimuli in PsyToolkit is very simple. The following types of stimuli can be shown:

the concept of variables

Like any computer language, you can use variables. There are global and local variables. You can in principle always use global variables. Local variables are only used within one task, whereas global variables can be used anywhere in the task and block code (see also blocks). You can set initial values of global variables in the options.

You can set a variable with the "set" instruction.

Example of setting and using variables
task MyTask
  set $x 100
  set &y 10
  show bitmap FunnyFace $x &y
Variables can only have integer values. That is, an integer, which is a whole number. For example, $x is 100, it cannot be 100.342, because the latter is not a whole number.
The equal sign is not being used to assign values to variables! That is, no "=" symbol like you would do in most programming languages.
Variables are not allowed to start with a number, are not allowed to contain spaces, minus signs, dots, or special characters except the underscore.

Good examples.

  • $MyVariable1

  • $my_variable_1

  • $xyz

The following are NOT allowed!!!!!!!

  • $My Variable 1 (reason: no spaces allowed)

  • $My.variable.1 (reason: no dots allowed)

  • $My-variable-1 (reason: no minus signs allowed)

  • $My*variable (reason: no special characters such as "*" allowed)

  • $123my_variable (reason: not allowed to start with a number)

There are also special types of variables written in capitals, such as RT, STATUS, TABLEROW, TASKNAME, BLOCKNAME, BLOCKNUMBER, BLOCKORDER. They just give you access to important information about a response or the task condition.
Since 3.3.1, you can use text variables, which start with the % character. See example in the set documentation.

the concept of timestamps

Timestamps are a special type of variable, but they are only used in very advanced scripts and are normally not necessary. Whenever you set a timestamp, the current time is being saved.

The set function

With set, you can assign values to variables.

Note set [$&][variablename] [new value, variable, or expression]

As explained about in "variables", the set function can set the value of variables.

A variable is a basic element in any programming language. A variable is simply a symbol which holds a value. For example, x = 10. PsyToolkit can only work with whole numbers as values.
set is a relatively advanced function, and when learning PsyToolkit, you do not immediately need it, and you can write scripts without set.
A global variable is one that remains its value throughout your PsyToolkit script. A local variable is one that is set back to zero every time the task starts again. If this is something you think is too difficult to remember, just use global variables.
set a local variable to a value (the $ indicates that it is local variable) which will be reset to zero automatically at the beginning of the trial
set $x 10
set a global variable to a value (the & indicates that it is a global), this variable will keep the value you set it too, no matter whether you are in a task or a block
set &x 10

In the rest, the local or global nature of the variable is irrelevant for explaining set, and we just work with $x

take the value of other variable
set $x &y
increase the value of a variable
set $x 10
set $x increase 2  # after this, $x has value 12
decrease the value of a variable (default is 1)
set $x 10
set $x decrease # after this, $x has value 9
use a mathematical expression
set $x expression $a * 3 + 4
It is easier to read if you use spaces between the things on an expression line. But in principle, you can do it without spaces.
use a mathematical expression without spaces (possible, but maybe less easy to understand?)
set $x expression $a*3+4
set to random value
set $x random 1 10
set to random value in steps of 2
set $x random 2 100 2
set to random value from specific set of values
set $x random from 1 2 3 5 10
set to value from the pcidio24 IO card (if you have one!) (for advanced users, Linux only)
set $x pcidio24 a # set to value of register A
set to the milliseconds that have been passed since start of experiment (for advanced users)
set $x time-since-start
set to the millisecond difference of two timestamps (for advanced user)
timestamp MyTime1
delay 500
timestamp MyTime2
set $x timestamp-diff MyTime1 MyTime2 # now x should be 500
get the timestamp in seconds and milliseconds (for advanced users)
timestamp MyTime1
dely 2500
timestamp MyTime2
set $x timestamp-seconds MyTime2 # value should be 2
set $x timestamp-milliseconds MyTime2 # value should be 2500
get the time in milliseconds since 1st of January 1970 (for advanced users)
set $x unix-time
save $x

There are two examples of how to get the number of the stimulus currently under the bitmap. The first method is recommended. The second method does the same, but takes more code.

In the example below, there are two stimuli on screen. The $x will get the value where the participant clicked (stimulus 1 is yourface and stimulus 2 is smileyface).

get stimulus number of the stimulus currently under the mouse (method 1)
bitmaps
  myface
  yourface
  smileyface

task test
  show bitmap yourface -100 0    ## first bitmap
  show bitmap smileyface 200 200 ## second bitmap
  readmouse l 1 1000
  set $x UNDER_MOUSE
get stimulus number of the stimulus currently under the mouse (method 2, for advanced users)
bitmaps
  myface
  yourface
  smileyface

task test
  show bitmap yourface -100 0    ## first bitmap
  show bitmap smileyface 200 200 ## second bitmap
  readmouse l 1 1000
  set $myMouseX MOUSE_X # current mouse x-coordinate
  set $myMouseY MOUSE_Y # current mouse y-coordinate
  set $x bitmap-under-mouse $myMouseX $myMouseY ## $x should be 1

You can set text variables. Text variables always start with the % character, just to tell PsyToolkit that we have a text variable here.

You can create a new text variable by pasting different pieces together and then show this. This is particularly useful when giving a participant feedback about RT or numbers of errors, as in the example below.

set text variable
task test
  keys x
  show rectangle 0 0 100 100  255 0 0
  readkey 1 2000
  set $myvar random 1 100
  set %y "Hello " RT " " $myvar
  show text %y
  delay 2000

block testx
  tasklist
      test 2
  end
set variable to duration of sound stimulus (file)
  set $x duration my_sound
set text variable to substring of other text variable; here, take letters 1 to 5
task test
  keys x
  show rectangle 0 0 100 100  255 0 0
  readkey 1 2000
  set $myvar random 1 100
  set %y "Hello " RT " " $myvar
  set %k %y[1,5]
  show text %k
  delay 2000

block testx
  tasklist
      test 2
  end

For substrings, you use an indexing system:

set %text1 "PsyToolkit"

set %text2 text1[1] → text2 is "P" set %text2 text1[-1] → text2 is "t" (last letter) set %text2 text1[-2] → text2 is "i" (second last letter)

set %text2 text1[1,-1] → text2 is "PsyToolkit" (first to last letter) set %text2 text1[1,3] → text2 is "Psy" (letter 1 to letter 3) set %text2 text1[-3,-1] → text2 is "kit" (third last to last letter)

set an array variable

These are for somewhat more experienced users. Make sure you first understand the set instructions.
In PsyToolkit, an array is simply a serie of whole numbers, such as 1 2 3 4 5.

Each array variable is a global variable, that is, they stay the same throughout trials and different tasks.

In short, you can apply the following functions (more detailed examples are further below):

instruction

what it does

example

values

set array to sequence of values

set &&x 4 2 10 -1

sort

sort sequence in array

set &&x sort

range

fill an arrange with a range

set &&x range 1 5

shuffle

shuffle an array’s values randomly

set &&x shuffle

remove

remove one value from an array

set &&x remove first

sample

take n values from an array randomly

set &&x &&y sample 10

uniq

remove all values occuring more than once

set &&x uniq

append

add a value to end of array

set &&x append 10

prepend

add a value to beginning of array

set &&x prepend 10

clear

remove all values of an array

set &&xx clear

value times n

repeat a value (or array) multiple times

set &&x 10 times 5

All instructions in this subsection apply to whole arrays (text or numeric) only. There is a separate section for how to extract values from arrays.

Here are some examples for creating arrays or for taking them apart.

Set an array to some numbers
task test
  set &&my_array 1 2 5 2 4 1 0 10
Remove all values from array (after which it will be empty)
task test
  set &&my_array clear
Fill the array with a range of values, in this case 1 2 3 4 5
task test
  set &&my_array range 1 5
The instruction below removes a value from the array, but you will not know which one (see below for the other remove to do that).
If an array has a value, remove that value (in this case value 3)
task test
  set &&my_array 1 2 3 4
  set &&my_array remove value 3
Remove the first value from the array. For example: 1 2 3 4 becomes 2 3 4
task test
  set &&my_array 1 2 3 4
  set &&my_array remove first
Remove the last value from the array. For example: 1 2 3 4 becomes 1 2 3
task test
  set &&my_array 1 2 3 4
  set &&my_array remove last
Remove a specific position from the array. For example: 10 4 20 100 becomes 10 20 100
task test
  set &&my_array 10 4 20 100
  set &&my_array remove position 2
Remove one position from the array at random.
task test
  set &&my_array remove random
Fill the array with the value 2, repeated 10x (thus becoming 2 2 2 2 2).
task test
  set &&my_array 2 times 5
Fill the array with 3 random values between 5 and 10
task test
  set &&my_array random 5 10 times 3

You can also repeat arrays. Thus, in the following example we have an array &&my_numbers with the content 1 2 3. After doing this times 3, we have 1 2 3 1 2 3 1 2 3.

Repeat an array 10 times
task test
  set &&my_numbers 1 2 3
  set &&my_array &&my_numbers times 3
Sort the values of an array (from low to high)
task test
  set &&my_numbers sort
Sort the values of an array (from high to low)
task test
  set &&my_numbers sort reverse
Remove all the values form an array that occur more than once
task test
  set &&my_numbers uniq
You can also use text arrays, start them with %%, see example below.
Remove all the values form an array that occur more than once
task test
  set %%my_list "Hello" "this" "is" "PsyToolkit"

set a variable to a value from an array

These are for somewhat more experienced users. Make sure you first understand the set instructions.
In PsyToolkit, an array is simply a serie of whole numbers, such as 1 2 3 4 5.
code what it does

locate

find the location of a value in an array

remove

take and remove from array (the first, the last, a random one, or one at a specific array position)

use

use but do not remove from array (the first, the last, a random one, or one at a specific array position)

size

get the number of items in an array

join

set the text variable to the joined elements of text array

mean

get mean value of numbers

roundmean

get rounded mean value of numbers

min

get min value of number array

max

get max value of number array

sum

get sum of number array

sd

get sd value of number array

In the example below, we can set an area to the values 4 5 2 10. In this array, the second value (i.e., position 2) contains 5. Thus, &x will equal 2 after this.

Locate the position of a specific value in an array
task test
  set &&my_area 4 5 2 10
  set &x &&my_array locate 5

In the following example, the global variable &x will get value 4 (the first), and the array &&my_area will be reduced to 5 2 10.

Get and remove a value from the array
task test
  set &&my_area 4 5 2 10
  set &x &&my_array remove first

In the following example, the global variable &x will get value 10 (the last), and the array &&my_area will be reduced to 4 5 2.

Get and remove a value from the array
task test
  set &&my_area 4 5 2 10
  set &x &&my_array remove last

In the following example, the global variable &x will get value 5 (which is at the removed position 2). The array will then be 4 2 10

Get and remove a value from the array
task test
  set &&my_area 4 5 2 10
  set &x &&my_array remove 2

Note, instead of remove you can use the use instruction. The only difference is that the array would not be modified.

Note, you can also remove a value at random.

Get the size of an array (in the example, &x will thus become 4)
task test
  set &&my_area 7 5 2 10
  set &x &&my_array size
Sort and join an array with spaces
task test
  set %%my_array "Smith" "hello" "John"
  set %%my_array sort
  set %my_sentence %%my_array join " "

Summary of set

Summary of all set functions.

Set is not needed for beginners! It really allows flexibility in your code, if you want and need it.
For each set function, you can use local or global variables. Do not worry about the difference between local and global variables; when in doubt, use global variables (starting with the & sign).
purpose example result

basic use

assign value to local variable

set $x 10

$x contains 10 (only whole values are allowed)

assign value to global variable

set &g 12

&g contains 12

assign value from other variable

set &h RT

assuming there was a readkey command earlier, set &h to the value of RT

assign random value

set &x random 1 5

&x contains one value from 1,2,3,4,5

assign random value in steps

set &x random 1 10 2

&x contains one value from 1,3,5,7,9

increase variable’s value

set &x increase

assume &x already contains 5, after this command it will contain 6

increase variable’s value by value

set &x increase 3

assume &x already contains 5, after this command it will contain 8

decrease

set &a decrease

works the same as increase, except it decrease the value

assign value based on expression

set $y expression $x * 3 + 5

assume $x contains value 5, then $y will contain 20

advanced use: time functions

time since start of experiment in ms

set $j time-since-start

if your experiment started 5 seconds ago, $j will contain 5000

calculate difference between 2 time stamps

set $t timestamp-diff MyTime1 MyTime2

Assume that MyTime1 is set earlier than MyTime2, $t will contain difference in milliseconds.

calculate difference between 2 time stamps in seconds

set $t timestamp-seconds MyTime1

the timestamp in seconds

calculate difference between 2 time stamps in milliseconds

set $ms timestamp-milliseconds MyTime1

the timestamp in milli seconds

advanced use: mouse functions

find number of stimulus clicked

set $b bitmap-under-mouse

if in the last readmouse stimulus 5 was clicked, $b will contain 5

find number of stimulus clicked, but only consider certain stimulus numbers

set $b bitmap-under-mouse range 10 15

if in the last readmouse stimulus 11 was clicked, $b will not contain 11. Other stimuli will be ignored. This is handy for overlapping stimuli.

advanced use: other

find number of last shown stimulus

set $c show-counter

if you have shown 10 stimuli, $c will contain 10

advanced use: Linux only

get value from PCI-DIO24 card

set $z pcidio24 a

set $z to the 8-bit value from channel a (value between 0 and 255)

current X position on screen of sprite

set $x sprite-x 2

assuming there is a sprite number 2, set $x to where the sprite is on the screen (x coordinate)

current Y position on screen of sprite

set $y sprite-y 2

assuming there is a sprite number 2, set $y to where the sprite is on the screen (y position)

commonly used instructions

There are many different instructions for showing stimuli, recording and saving responses. Below they are all listed with a short example of their use. This section describes the ones that are most often used, and that you really need to understand.

Before we start, here is an alphabetical list of the most commonly used instructions:

  • presenting stimuli

    • show shows a stimulus on the screen

    • clear removes a stimulus from screen

    • sound plays a sound

  • measuring responses and response times

    • keys tells the computer which keys are being used in a task

    • readkey waits for one keyboard press

    • readkeys waits for multiple keyboard presses

    • textbox allows entry of text, including special characters

    • readmouse waits for a mouse click or mouse movement

    • choose fancy multiple stimuli selection with mouse

    • rate easy way to include Likert scale in your experiment

  • waiting for some time

    • delay wait period in milliseconds

  • saving data

    • save saves data to file

  • telling the computer about experimental conditions

    • table specifies where the experiment conditions are

  • conditionals

    • if do something depending on variable value(s)

    • while do something depending on variable value(s)

    • set set a variable

    • set_array set an array variable

    • set_from_array set a variable to a value from an array

Below, each of these commands is given in more detail.

keys

Note keys [list of keycodes]

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.

Example keys using only two keys
keys a z

List of all the keys available on all platforms:

  • lettes: a to z

  • numbers: 0 to 9

  • special keys: enter capslock tab space end home insert

  • special keys: escape slash backslash quote comma period

  • arrow keys: up down right left

  • numerical keyboard (keypad): kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9

  • number keyboard: kp_period kp_slash kp_star kp_minus kp_plus kp_enter

The following keys are not availble in the Javascript mode

  • shift keys: lshift rshift

  • control keys: lcontrol rcontrol

  • alt keys: lalt ralt

  • logo keys: lsuper rsuper

Mouse on or off

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

Example of how to hide or show mouse in a task
task MyTask
  show bitmap smileyface
  mouse hide
  delay 1000
  show bitmap smileyface
  mouse show
  delay 1000

table

Note table [name of table]

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!

If you have more than one task and more than one table, you need to specify in your task which table belongs to it.

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

Example table
table MyTable

tablerow

This is an advanced function. You normally do not need it.

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.

show

Note show [bitmap|text|rectangle|circle|video](X,Y)(…​)

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

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

show bitmap

Note show bitmap [bitmap](X,Y)

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

Example of show bitmap
show bitmap MyBitmap
show bitmap MyBitmap 200 10
More information about how to show bitmaps is available in this lesson.

show rectangle

Note show rectangle X,Y,Width,Height, Red,Green,Blue

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.

PsyToolkit uses the Red-Green-Blue (RGB) color model. Each color can be specified as a combination of red, green, and blue. For each of these three basic colors, you need to give a value between zero and 255. You can create any color, see RGB model on wikipedia. There are websites where you can create your own colors:
Table 1. Examples of colors in the RGB model:
Color Red Green Blue

White

255

255

255

Pure red

255

0

0

Pure blue

0

0

255

Pure green

0

255

0

Yellow

255

255

0

Grey

128

128

128

Orange

255

128

0

Pink

255

100

180

Example of show rectangle
show rectangle 0 0 100 100 255 0 0

show circle

Show a circle. Similar to show rectangle.

Note show circle X,Y,Radius, Red,Green,Blue

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

Example of show circle
show circle 0 0 100   255 0 0

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

Example of color name
  show circle 0 0 100   red

show line

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)

Examples of show line in yellow color (255 255 0 = yellow)
task testline
  show line 10 10 200 10   255 255 0
  delay 5000
  clear -1
Examples of show line in yellow color (255 255 0 = yellow) and 30 pixels wide
task testline
  show line 10 10 200 10   30   255 255 0
  delay 5000
  clear -1
Examples of show line with separate setting of color
task testline
  line color 150 150 150  ## grey
  show line 10 10 200 10
  delay 5000
  clear -1
Examples of show line with separate setting of color and width
task testline
  line color 0 255 0  ## green
  line width 20
  show line 10 10 200 10
  delay 5000
  clear -1

show background

Note show background (Red,Green,Blue)
There is also the easier way to set this using the option background color.

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.

Example of show background
show background 100 100 100 ## creates a grey background
delay 500
show rectangle 100 200 200 0 0 ## draw red rectangle
delay 1000
clear -1 ## erase the the rectangle
You do not need to clear the background and the background will stay on until next trial (which is most likely what people want)
Instead of an R G B triplet, you can also use a color name.
Example of show background
show background blue ## creates a blue background in a task

show text

The show text instruction shows text.

Basic example of show text for Linux
table MyFirstTable
  10 "some text"
  15 "some other text"

task MyTask
  show text "Some green text"  0 0   0 255 0
  show text @2  0 0   0 255 0
By default, without telling the computer what font you want to use, PsyToolkit will use Arial 20 points. You do not need to define a font if you do not want to anything else than Arial of size 20 points.
There are lots of freely available ttf fonts available on the web. For example via Font Squirrel.

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

Note show text [text](X,Y)(Red,Green,Blue)
Basic example of show text with specific fonts
fonts
  MyArial comic.ttf 20

table MyFirstTable
  10 "some text"
  15 "some other text"

task MyTask
  font MyArial
  table MyFirstTable
  show text "Some green text"  0 0   0 255 0
  show text @2  0 0   0 255 0
The default alignment is "center". That means that if you ask something to presented at, say, position 10,10, that is where the center of the word is. See the example below on how to set the alignment. Also, note that you can set the text color for all subsequent "show text" commands, and here you can use a color word.

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.

Example of text and show text with alignment and color
fonts
  arial 20

task MyTask
  text color yellow
  text align center
  show text "Some text with alignment: center"  0 -100
  text align left
  show text "Some text with alignment: left" 0 0
  text align right
  show text "Some text with alignment: right"  0 100
  delay 10000

block test
  tasklist
    MyTask 1
  end
The following color words are currently implemented: white, yellow, red, green, blue, pink, purple, black, grey, orange, pink.
For "text color", you can also specify the color in three decimal values or as 6 digit hex code. See example below for the same statement of specifying yellow in three different ways. This example makes no sense in a real experiment (because why would you specify the same color 3x in a row?), but just demonstrates how to use the "text color" statement.
Example of text color
  # specify color as word:
  text color yellow
  # specify color as Red Green Blue code:
  text color 255 255 0
  # specify color as Hexadecimal value:
  text color FFFF00

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

Example of color name
  show text "Hello" 0 0 red

show video

Example of video in the middle of the screen
   show video my_clip
Example of a video can be placed just like other stimuli
   show video my_clip -100 100
Example of a muted video (no sound)
   videocontrol my_clip mute
   show video my_clip -100 100

clear

Note clear [bitmap occurrence](list of bitmap occurrences)

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 bitmap counter is reset every trial!
Example using clear
show bitmap redcircle
show bitmap greencircle
delay 500
clear 2 # clears the second presented bitmap
# or
show bitmap redcircle
show bitmap greencircle
delay 500
clear -1 # clears last presented bitmap, that is "green circle"
# or
show bitmap redcircle
show bitmap greencircle
delay 500
clear 1 2 # clears both bitmaps
Sometimes, you want to clear so many stimuli that it is not nice to have to type the numbers in. If they are in a range, you can specify the range. For example, clear range 1 10 clears stimuli 1 2 3 4 5 6 8 9 10.
Rarely, you want to clear the whole screen. This is not recommended for time critical things, because it can be slower that changing small parts of the screen. Sometimes you want to clear the whole screen at the beginning or end of trial. You can use clear screen to do so.

hide/unhide

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.

rotate

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.

Angle is indicated in tenth of degrees. Thus, a 90 degree angle is indicated by 900.
Examples of rotating a bitmap
rotate next 900
show bitmap MyBitmap
Examples of rotating a bitmap which is already on screen
show bitmap
delay 500
rotate 1 900

delay

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.

Note delay [milliseconds]
Examples of delay that shows how to show a stimulus for 200 ms
show bitmap MyBitmap
delay 200
clear -1
The parameter of delay (in the example 200) can be a variable or a table entry as well. Look at the examples to learn how to do that.

readkey

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.

Note readkey [correct key number][maximum RT]

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

Example of readkey
task MyTask
  keys a z
  show bitmap PressTheZkey
  readkey 2 3000

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

  • RT (with the response time in milliseconds, that is the time of the key down event)

  • TT (the time the key has been released)

  • STATUS (with values CORRECT,WRONG, or TIMEOUT, or 1,2, or 3)

keystatus

The keystatus command is for advanced use only and works on Linux only (i.e., not in the web-based system)

Under certain conditions, you want to check the status of the keyboard directly. You can do this with the keystatus command. You can (optionally) specify which key you would condider to be correct.

Example:

Example of readmouse
task checkKey
  keys a l
  show rectangle 0 0 50 50   255 0 0
  timestamp MyTime1
  timestamp MyTime2
  while $x < 5000 ## run while-loop for 5 secs
   keystatus ## read the keyboard status
   if KEY == 1 ## key "a"
     unhide 1 ## display the rectangle
   fi
   if KEY == 2 ## key "l"
     hide 1 ## hide the rectangle if l is pressed
   fi
   set $x timestamp-diff MyTime1 MyTime2 # now x should be 500
   nap ## give the computer some rest in the while loop
  while-end

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

Example of color name
  show rectangle 0 0 100 100 green

readkeys

The readkey function is useful for most experiments, where you need just one key press in response to a stimulus.

For a number of experiments, you want people to be able to type in a word (or some sequence of letters).

The command readkeys lets you do this. Look at the example below to see it.

The readkeys command has many options, so it may look a bit more difficult (see list below).
The command allows for delete character. Return key "ends" the readkeys input.
Example of readkeys
bitmaps
  apple ## a picture of an apple
  empty_box ## an empty rectangle used as letter placeholder

fonts
  arial 20

task my_task
  text color yellow
  show bitmap apple
  readkeys "apple" 10000
  save RT STATUS

A more complex function using the readkeys option statements.

Note, by default:

  • the typed letters will be shown on screen (you can hide them with readkeys option hide)

  • there are no placeholders shown (see example below for how to show placeholders)

  • the font color is white by default (you can set it differently with, for example textcolor yellow)

  • the size of the maximum array is 100 (which is in practical terms way longer than what you could need)

  • the letters will be shown starting at the center of the screen

  • the first defined font (in fonts section) will be used

  • the default spacing of letters will be 25 pixels

Readkeys options:

  • readkeys option size number : how many letters can be typed maximally.

  • readkeys option show : the typed letters will be shown on screen (starting at screen center)

  • readkeys option show x_position y_position : the typed letters will be shown as indicated by the x/y position

  • readkeys option hide : the typed letters will be not be shown on screen

  • readkeys option space number : The letters will be spaced by this number of pixels

  • readkeys option placeholders image : There will be placeholders in the shape of the indicated image (as defined in bitmaps)

  • readkeys option placeholders Width Height : The placeholders will be rectangles of size Width by Height

Here is an example with some of these.
bitmaps
  apple ## a picture of an apple
  empty_box ## an empty rectangle used as letter placeholder

fonts
  my_arial arial 20

task my_task
  text color yellow
  show bitmap apple
  text color red
  readkeys option size 5
  readkeys option show 100 50
  readkeys option placeholders empty_box
  readkeys font font1
  readkeys "apple" 10000
  save RT STATUS WORD

Some explanations about the above example:

  • text color red: The readkeys command will show letters in red

  • readkeys option size 5: Maximally 5 letters can be typed

  • readkeys option placeholders empty_box: The placehold will be the bitmap image empty_box as given by the user in the bitmaps list

  • readkeys option show 100 50: The typed letters will be shown on screen at position 100 50.

  • readkeys option font my_arial: The font my_arial will be used

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

textbox

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.

This is introduced in version 3.4.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).

task my_task
  show text "Enter words" 0 -280
  show rectangle 300 250 100 100 green
  textbox new 0 0 500 400 white blue 30 arial
  readmouse l 2 99999 range 2 2
  set %%my_list textbox
  save %%my_list
Use set to save the text in a textvariable (such as %my_word) or a text array (such as %%my_list).

readmouse

For the non-click version of readmouse, this has changed slightly in version 3.1.0

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

  • Wait until the mouse is clicked and the mouse is in the correct location

  • Wait until the participant moves the mouse to the correct location

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.

Example of readmouse without clicking
task checkMouse
  show rectangle -200 0 40 40  0 255 0 # green rect, left
  show rectangle  200 0 40 40  255 0 0 # red rect, right
  readmouse 1 5000
  save STATUS RT
In the example above, you get a correct STATUS if the left rectangle was moved over (hovered over), and you get STATUS wrong if the right rectangle is moved over.
In case there are more stimuli on the screen, it is recommended you use the range parameter, as shown below.
Example of readmouse without clicking and using range
task checkMouse
  show rectangle 0 0 700 500   100 100 100
  show rectangle -200 0 40 40  0 255 0 # green rect, left
  show rectangle  200 0 40 40  255 0 0 # red rect, right
  readmouse 2 5000 range 2 3
  save STATUS RT

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.

Example of readmouse
task checkMouse
  show rectangle -200 0 40 40  0 255 0 # green rect, left
  show rectangle  200 0 40 40  255 0 0 # red rect, right
  readmouse l 1 5000
  save STATUS RT

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:

Example of readmouse
task checkMouse
  show rectangle -200 0 400 400  255 255 0 # big yellow rectangle
  show rectangle  50 0 40 40  255 0 0 # small red one
  readmouse l 2 5000 range 2 2 # wait for second one being clicked
  save STATUS RT

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.

Example of readmouse without clicking and with find
task checkMouse
  show rectangle -200 0 40 40  0 255 0 # green rect, left
  show rectangle  200 0 40 40  255 0 0 # red rect, right
  readmouse 1 5000 find
  save STATUS RT

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.

drag

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.

Overview of drag

drag option from [&&array or sequence]
drag option to [&&array or sequence]
drag option snap ([left|center|right][top|center|bottom][no_overlap &&array or sequence])
drag option xlim value value
drag option ylim value value
drag maximum_duration

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.

Super simple fully working drag example
task my_drag
  show rectangle 0 0 100 100   255 255 0
  drag option from 1
  drag 99999

block test
  tasklist
     my_drag 1
  end

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.

You can drag the red and green, but not the white rectangle
task my_drag
  show rectangle -100 0 100 100   255 0 0      # red
  show rectangle    0 0 100 100     0 255 0    # green
  show rectangle  100 0 100 100   255 255 255  # white
  drag option from 1 2
  drag 99999

block test
  tasklist
     my_drag 1
  end

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:

Drag the red onto the green rectangle
task my_drag
  show rectangle  100 0 120 120     0 255 0    # green
  show rectangle -100 0 100 100     255 0 0      # red
  drag option from 2
  drag option to 1
  drag 99999
  show text "Now wait 1000 ms" 0 150
  delay 1000

block test
  tasklist
     my_drag 1
  end
To the above exaple, you could have added drag option snap to let the red rectangle snap exactly on the green one. You can even specify whether how you want to snap, here are some examples:

drag snap examples
drag option snap # this snaps to the center by default
drag option snap center center # same, but now explicitly give the horizontal and vertical snap alignment
drag option snap left center # this aligns horizonally to the left but vertically to the center

dragging

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.

Overview of draggin

drag option exit stimulus
dragging maximum_duration

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.

Note that if you do not drag them on the targets, they jump back to their original positions.
Super simple fully working dragging example
task my_dragging
  show rectangle  100 -100 120 120     0 255 0    # green
  show rectangle  100  100 120 120     0 255 0    # green
  show rectangle -100 -100 100 100     255 0 0    # red
  show rectangle -100  100 100 100     255 0 0    # red
  show rectangle 250 0 100 80   255 255 0
  show text "Exit" 250 0   0 0 0
  drag option from 3 4
  drag option to 1 2
  drag option snap center center
  drag option exit 5
  dragging 60000
  save RT

block test
  tasklist
    my_dragging 1
  end

Variables for use with drag and dragging

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

Overview
DRAGGED the stimulus that was being dragged
DRAGGED_ON the stimulus that it was move on (only with "drag option to")
DRAG_CHANGED if a stimulus had been moved at all (1 if changed, 0 if not)
DRAG_OLD_X the stimulus X coordinate when drag started
DRAG_OLD_Y the stimulus Y coordinate when drag started
DRAG_X the stimulus X coordinate of (last) dragged stimulus
DRAG_Y the stimulus Y coordinate of (last) dragged stimulus

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.

Experiments using drag or dragging can be quite complex. Learn how to write these in the lessons section.

progress

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.

Progress bars can distract. If you do an experiment studying visual attention or memory, you need to think about whether you think looking at the progress bar may interfere with the cognitive process you are studying.

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

Example of progressbar
task exampletask
  show progress TRIALCOUNT 30
  delay 1000
  show mystimulus

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

Example of progressbar with options
task exampletask
  progress option size 0 290 600 10
  progress option color1 255 255 0
  progress option color2 128 128 128
  progress option between 5
  show progress TRIALCOUNT 30
  delay 1000
  show mystimulus

These options have the following meaning.

  • size: X position (middle of progressbar), Y position, width, height

  • color1: The color for the trials done (in Red/Green/Blue format)

  • color2: The color for the trials done (in Red/Green/Blue format)

  • between: The space between trials (for example, choose 2 for small gap between each progress point)

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

Example of progressbar with options
  progress option colors 255 255 0    128 128 128

choose

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

Example of choose
bitmaps
  markingsymbol
  house
  ball
  car
  exitsymbol1 ## shown when at least 2 selected
  exitsymbol2 ## shown when not enough are selected

task clickMysymbols
  show bitmap house # bitmap 1
  show bitmap ball  # bitmap 2
  show bitmap car   # bitmap 3
  choose option select markingsymbol
  choose option minselect 2
  choose option exit exitsymbol1 exitsymbol2 350 250
  choose 60000 1 3
  save RT CHOSEN_N CHOSEN_1 CHOSEN_2 CHOSEN_3

Note the following things about the above example:

  • There are three images on the screen.

  • If you click an image, the "markingsymbol" image will be put on top of it

  • If you click it again, this "markingsymbol" will be removed

  • The RT is the response time until the exitsymbol was clicked

  • CHOSEN_N contains number of selected objects

  • CHOSEN_1, CHOSEN_2, CHOSEN_3, etc contains the number of the object. They will always be in numerical order.

There are various other options:

  • choose option minselect: The minimum to be selected objects

  • choose option maxselect: The maxumum to be selected objects

  • choose option sprites: Select from sprites instead of static stimuli

  • choose option keep: Keeps the participant selected selector images on screen (the default is that they are erased immedeately when the choose function is over)

The choose command is particularly useful for memory tasks.

rate

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.

Super simple example of rate
bitmaps
  something_for_sale

task wantit
  show bitmap something_for_sale -200 0
  rate 10000 5
  save RATE RATE_RT RATE_STATUS

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.

Simple example of rate
bitmaps
  something_for_sale

task wantit
  show bitmap something_for_sale -200 0
  rate option pos -200 0
  rate 10000 5
  save RATE RATE_RT RATE_STATUS

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.

Simple example of rate
bitmaps
  something_for_sale
  left_arrow
  right_arrow
  my_rectangle

task wantit
  show bitmap something_for_sale -200 0
  rate option pos -200 0
  rate option labels left_arrow right_arrow
  rate option items my_rectangle
  rate 5000 7
  save RATE RATE_RT RATE_STATUS

save

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

The save instruction is of critical importance, because it makes sure that the information you need for your data analysis is being stored. By default, PsyToolkit does not keep any information (unlike some other experiment software). The user needs to tell PsyToolkit exactly which information is being stored to the data file.
Typically, you will want to save what the current condition is, the current block (if you have more than one block), and at least the response time (RT), and whether the participant responded correctly or not (STATUS). The examples on this website can help you to understand this.
The best place for the save command is at the end of your task description.
Note save [list of variables]
Example of save
save BLOCKNAME RT STATUS

sound

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.

Note sound [sound name (as defined in 'sounds']
Example of sound
sound MySoundFile
delay 200
silence MySoundFile

if

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.

Examples of if
task MyTask
  show bitmap stimulus
  readkey 1 1000
  if STATUS == CORRECT
    show bitmap WellDone
    delay 1000
    clear -1
  fi
  if STATUS != CORRECT
    show bitmap Mistake
    delay 2000
    clear -1
  fi
  if $x == &y
    show bitmap SmileyFace $x $y
  fi
Examples of if with else
task MyTask
  show bitmap stimulus
  readkey 1 1000
  if STATUS == CORRECT
    show bitmap WellDone
    delay 1000
    clear -1
  else
    show bitmap Mistake
    delay 2000
    clear -1
  fi
  if $x == &y
    show bitmap SmileyFace $x $y
  fi
The statement else need to be on its own line

With if, you can also compare two arrays

Examples of if with arrays
task MyTask
  set &a 1 2 3 4
  set &b 1 2 3 4
  if &&a == &&b
    show text "Arrays a and b are exactly the same"
  else
    show text "Arrays a and b are different"
  fi

while

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.

Examples of while loop
task MyTask
  set $mycounter 0
  while $mycounter < 10
    set $x random -200 200
    set $y random -200 200
    show bitmap SmileyFace $x $y
    set $mycounter increase
  while-end
If you make a mistake, the computer might be stuck in the while loop. For example, if you do not increase the value of $mycounter in the above example, the code will be stuck and keep drawing new SmileyFace symbols at random positions.

less often used instructions

Some functions are rarely used or necessary, yet they add to the potential of PsyToolkit scripting.

font

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

Examples of font
fonts
  MySmallFont arial.ttf 20
  MyBigFont arial.ttf 50

task Mytask
  font MySmallFont
  show text "small" 0 0
  font MyBigFont
  show text "small" 0 100

very advanced instructions

end

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

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

Examples of timestamp
task MyTask
  timestamp MyFirstTimestamp
  delay 1000
  timestamp MySecondTimestamp
  set $x timestamp-diff MyFirstTimestamp MySecondTimestamp
  save $x

sprite

Sprite commands do not work in browser/online version. They work only in the Linux (Desktop version).

In PsyToolkit, sprites are a separate type of stimulus (in addition to bitmap, rectangle, circle, and text. Sprites can move around and rotate. This is great for experiments such as multiple object tracking. They have their own commands.

Basic example showing a sprite moving
bitmaps
  mystimulus

task MyTask
  sprite create mystimulus
  sprite 1 display
  sprite move direction 45 5
  delay 2000

block test
  tasklust
    MyTask 1
  end
The speed of moving sprites is based on various factors. Speed depends on the screen update frequency. This just means that if you use experiments on different systems, you might have slightly different sprite moving speeds.
Have a look at the Linux example directory to see how the commands below work.
Function name What it does example

create new sprite

sprite create [bitmap]

create a stimulus and position it at screen center

sprite create MyStimulus

sprite create [bitmap] [x][y]

create a stimulus and position it

sprite create MyStimulus 100 50

sprite create [bitmap] [x][y][angle][speed]

create a stimulus and position it and move it

sprite create MyStimulus 100 50 45 5

displaying sprites

sprite [sprite] display

makes sprite visible

sprite 1 display

sprite [sprite] hide

hides sprite

sprite 1 hide

sprite [sprite] freeze

stops moving

sprite 1 freeze

sprite [sprite] move

makes it moving again

sprite 1 move

moving sprites

sprite [sprite] jump (xpos)(ypos)

change position at once

sprite 1 jump 200 100

sprite [sprite] move (to/towards) (xpos)(ypos)(speed)

set a direction to location

sprite 1 move to 200 100 5

sprite [sprite] move direction (angle)(speed)

move in a direction

sprite 1 move direction -90 4

sprite [sprite] move path (speed) x1 y1 …​ xn yn

move along a set path of locations

sprite 1 move path 3 200 100 -200 100 300 50

sprite [sprite] evade

sprite will not run into one another

sprite 1 evade

sprite [sprite] borders [left][right][top][bottom]

sprite will bump against these set borders

sprite 1 borders -300 300 -200 200

rotating/scrolling sprites

sprite [sprite] rotate [speed in degrees per refresh rate]

Make a sprite keep rotating continuously

sprite 1 rotate -7

sprite [sprite] rotate to [angle] [speed in degrees per refresh rate]

Rotate a sprite gradually

sprite 1 rotate to 270

sprite [sprite] rotate now [angle]

Rotate a sprite

sprite 1 rotate now 45

sprite [sprite] hscroll [speed]

Scroll a sprite within

sprite 1 hscroll -3

changing sprites

sprite [sprite] speed (speed)

set speed

sprite 1 speed 2

sprite [sprite] accelerate (speed change)

adjust speed

sprite 1 accelerate 3

sprite [sprite] bitmap [bitmapname]

change what it looks like

sprite 1 bitmap smiley

command acting on all sprites as once

sprites [delete,freeze,unfreeze,display,hide,evade,bounce(borders,sprites),borders,update] all

act on all sprites in one line

sprites display all

See examples in the Linux packages to learn how to use these commands.

Instructions for special equipment

Special equipment are primarily IO cards and special keyboards. I recommend Cedrus keyboards. If you like, you can build your own keyboard. This saves a lot of money. You can attach it to the parallel port (if you have one). This keyboard is called "ultra" (designed by Felix Frey, University of Leipzig), and a document how to build this is freely available.

cedrus readkey

Wait for a specific key of your USB Cedrus keyboard. Make sure you know which key has which numerical value (you might want to experiment a bit with this, and there is an example programming that shows you the number of each key). On Linux, you can call this using the "testcedrus" command, which comes with PsyToolkit.

tables

Tables have lines and rows. Each time a table is being used in a task, one of its rows is chosen. Each column can be referred to using the @ sign. For example, @2 refers to the second column on the row that is being chosen for a given task trial. In the block, the user can specify how table lines are selected. The default is randomly, but there are alternative ways (for example: fixed order, repeat on trial).

Example of a table
table MyTable
 10  2  bitmap1
-10  1  bitmap2
Example of a table with strings
table MyTable
 10  2  bitmap1  "condition one"
-10  1  bitmap2  "condition two"

In a task that uses a table (as instructed with the table instruction), each column can be referred to with the @ sign. Thus @2 refers to the second column of the table row that has been selected.

Each time that a task is being carried out, only one table-row of the associated table is being selected. By default, a row is chosen randomly. There are other ways to choose table rows (using the tasklist instruction in blocks).

In each task trial with a table, you have access not only access to the columns, but you can also get the number of the tablerow. The variable is called TABLEROW. This can be handy for saving data. If there is a lot of important data in each tablerow that you want to use in your analysis, you want to make sure which TABLEROW was being used.

blocks

In experiments, trials come in blocks. A block of trials means that the participant does, for example, 100 trials of the Stroop task. Instead, you might want to have a break in the middle, so you could create instead 2 blocks of 50 trials. Blocks call tasks, so you really must have at least one block in your PsyToolkit script. Blocks can be complex, but they can also be very easy, like this example below.

Blocks are the best place to add your instructions for participants. Check this lesson about this out.
Example of simple block, calling the stroop task 100 times
block MyBlock
  tasklist
    strooptask 100
  end

showing bitmaps, playing sounds, and waiting for keys

Often, you want to show instructions to participants. You can show bitmaps, and you can show series of bitmaps participants can scroll forward and backwards through (pagers).

bitmap

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

Example of bitmap in block
block Myblock
  bitmap MyInstruction
  wait_for_key
  tasklist
    strooptask 100
  end
Showing a bitmap in a task and in a block is different. Here in blocks, do not put the word show before the bitmap. In tasks you have to. There are good reasons for this distinction (in tasks, stimuli are fast paced, whereas in blocks, they are thought of as instructions).

sound

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

Example of sound in block
block Myblock
  sound welcometune
  bitmap MyInstruction
  wait_for_key
  silence welcometune
  tasklist
    strooptask 100
  end

delay

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

Example of message in block
block Myblock
  bitmap number3
  delay 500
  bitmap number2
  delay 500
  bitmap number1
  delay 500
  tasklist
    mytask 100
  end

message

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

Example of message in block (waiting for space bar, which is default)
block Myblock
  message MyInstruction
  tasklist
    strooptask 100
  end
  message ThankYouBitmap
Example of message in block (example waiting for key 'b')
block Myblock
  message MyInstruction b
  tasklist
    strooptask 100
  end
  message ThankYouBitmap
You can use the mouse key instead of the keyboard. Make sure you instruct this clearly on the message. The participant will then continue when clicking (or touching) anywhere on the instruction bitmap.
Example of message in block (example waiting for mouse button press instead of keyboard)
block Myblock
  message MyInstruction mouse
  tasklist
    strooptask 100
  end
  message ThankYouBitmap

pager

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 instead of the keyboard (below).
Make sure you tell in the instructions how users browse through it and how they get out of it.
Example of pager in a block
block Myblock
  pager MyInstruction1 MyInstruction2 MyInstruction3 MyInstruction4
  tasklist
    strooptask 100
  end

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.

The mouse/touch pager is sometimes more useful (e.g., touch screen experiments).

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

  • Use the mouse for the pager

  • The bitmap named "back" should be presented at position -200,200

  • The bitmap named "next" should be presented at position 0,200

  • The bitmap named "start" should be presented at position 200,200

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.

Example of pager using the mouse in a block
block Myblock
  pager option mouse back -200 200 next 0 200 start 200 200
  pager MyInstruction1 MyInstruction2 MyInstruction3
  tasklist
    strooptask 100
  end

setting variables

Sometimes you want to set a global variable. You can do that just like you would do in tasks (including arrays). For example, you might set the maximum response time to a higher value during training.

Example of message in block
block MyTraining
  pager MyInstruction1 MyInstruction2 MyInstruction3 MyInstruction4
  set &MaxResponseTime 2000
  tasklist
    strooptask 20
  end

block MyRealDatablock
  set &MaxResponseTime 1000
  pager MyInstruction1 MyInstruction2 MyInstruction3 MyInstruction4
  tasklist
    strooptask 100
  end

tasklist

Each block has a task list. This describes which tasks are being called, how many times, and in what order. You might have one or more tasks. It is rare to have multiple tasks, but in taskswitching paradigms this might be the case.

On each line of the task list, you need at the very least provide the name of the task and the number of trials.

Example of simple tasklist
block MyTraining
  tasklist
    strooptask 20
  end

You can specify that you want that whenever people make a mistake, the same trial should be repeated, using repeat_on_error. If you use this, you need to specify what is considered to be an error using the error statement (see example below).

Repeat_on_error only works when you use tables, random variables are not set to the same values.
Example of simple tasklist.
table MyTable
  "condition1" 255 0 0 1 ## respond with "r" to red rectangle
  "condition2" 0 255 0 2 ## respond with "g" to green rectangle

task Mytask
  table MyTable
  keys r g
  show rectangle 0 0 50 50   @2 @3 @4
  readkey @5 2000
  if STATUS == WRONG
    error ## this makes this trial an error for the repeat_on_error process
  fi
  save @1 STATUS RT

block MyTraining
  tasklist
    Mytask 10 repeat_on_error
  end
In the example above, you see a red or green rectangle (presented at position 0,0, which is screen center, and 50px wide and 50px high). You need to respond with the "r" or "g" key. You might wonder why you would need to explicitly specify what an error is if you use "repeat_on_error". This is a good question, because in the above example it is indeed an error if the person responds with the wrong key. But there are experiments in which you actually want that people do not respond (that is STATUS is TIMEOUT). And in some experiments, there is more than one response per trial. The "error" statement gives you full control over what an error is and what not.

In some experiments, you might want that all participants carry out the trials in exactly the same order. You can just run through each line of your task table. You use the fixed option for this.

Example of simple tasklist
block MyTraining
  tasklist
    strooptask 20 fixed
  end

In some experiments, you might want that participants do at least a certain number of trials correct. You use the correct option for this. In the example below, the participant needs to have done 10 trials correct, but after 100 trials it will stop no matter how many the participant did correct. In the allcorrect variant, they must be consecutively correct.

Example of simple tasklist
block MyTraining
  tasklist
    strooptask 10 correct 100
  end

block MyTraining
  tasklist
    strooptask 10 allcorrect 100
  end

Finally, you sometimes want that trials do never repeat. There are three ways to get this in the tasklist statement

  • all_before_repeat : do all trials as in the table, randomly selected, but run them all before chosen again

  • no_repeat : never immediately repeat a condition from the table (i.e., the same row of a table will not be repeated in next trial)

  • fixed : run trials in the order as they are in the table

In the following example, there are only three entries on the following list. They will not be repeated until they are all done. You can explicitly add that you never want any repeat.

Example of tasklist
table MyTable
  bitmapBlue
  bitmapRed
  bitmapGreen

task strooptask
  table MyTable
  keys space
  show bitmap @1
  readkey 1

block MyTraining
  tasklist
    strooptask 10 all_before_repeat no_repeat
  end
If you have fixed in consecutive blocks, but use the same task and table, you will continue at the table row where you had left. This is a handy feature in case you have many trials you want to go through, but sometimes people need a break.

You can use the tasklist line option equal to ensure equal numbers of each table row are done. Ensure that the number of trials is a multiple of the table rows. Thus, if you have 4 table rows (that is, "conditions" in your experiment), you will have to have at least 4 trials, or 8 or 12 or any other multiple of 4.

Example of equal
block my_block
  tasklist
    my_task1 16 equal
  end
Make sure that you always have an end at the end of your tasklist

maxtime

You can set the maximum duration of a block (in milliseconds, seconds, or minutes). It is very simple. Here is an example of a block that can last for maximally 2 minutes.

You can still have instructions before the task list (e.g., as a message or pager, they are not counted toward the maxtime).
Example of block with maxtime in 2 minutes (notice the m)
block MyTraining
  maxtime 2m
  tasklist
    strooptask 10 all_before_repeat no_repeat
  end
Example of block with maxtime in 100 seconds (notice the s)
block MyTraining
  maxtime 100s
  tasklist
    strooptask 10 all_before_repeat no_repeat
  end
Example of block with maxtime, with variables you must specify it in milliseconds
block MyTraining
  maxtime &MyVariable
  tasklist
    strooptask 10 all_before_repeat no_repeat
  end

feedback

Feedback can be used to create feedback to the participant, for example about the average response speed. Creating feedback is part of the "block" structure. Feedback is described in a separate document, because it is of advanced use: how to use feedback

blockorder

Advanced use

By default, blocks are carried out in the order they are described in your code. You can alter this order by rearranging the block code, but there is an easier and quicker way: blockorder.

Using the blockorder statement, you can list the blocks you want to do and the order you want them in.

The idea behind this function is just speed of coding, and ease of changing the order (for example for counterbalancing).

In the following example, imagine there is code for three blocks, called training, test1, and test2. The following example show how to set the order of these blocks in different ways.

Example of how to use blockorder
blockorder
  training
  test1
  test2

Most importantly, you can have more than one blockorder. When you have more than one blockorder, PsyToolkit will choose one at random. Which blockorder will be chosen will be stored in the variable BLOCKORDER. By default, this variable contains value 1, but if you have given, say, 3 blockorders, this value can be between values 1 and 3. Below is an example of this use.

In the example below, the computer will choose one of the two blockorders at random. That is what the computer will do when it see two blockorders. This is great for counterbalancing, for example if you want that some participants start with one task and others with the another task.
Example of how to use blockorder (note that these tasks do not do anything meaningful)
task color_task
  keys a l
  readkey 1 1000
  readkey
  save BLOCKORDER BLOCKNAME TASKNAME RT

task shape_task
  keys a l
  readkey 1 1000
  readkey
  save BLOCKORDER BLOCKNAME TASKNAME RT

blockorder
  training
  color_task
  shape_task

blockorder
  training
  shape_task
  color_task

include (advanced use only)

You can include another file into your script. This can be useful if you work with very large tables which you want to store in a separate file. Any line starting with include followed by a filename will use that filename at that place in the script.

Included files must be in the same directory as the main script file.
Example of how to use include
table My_Large_Table
  include tablefile.txt

task some_task
  table My_Large_Table
  show bitmap @1
  delay 100

block test
  tasklist
    some_task 10
  end
Included files (like tablefile.txt in the example) should not include other files using include.

part (for advanced user)

You can write "snippets" of a few lines and include them elsewhere in your script. This is handy if you have multiple tasks or blocks which are broadly the same except for a few lines. This way can use a part instead of re-typing the whole script.

part just replaces the text into your code. The main aim is to have shorter more efficient code without repetitions of the same stuff.
Example of how to use "part"
part showAnimatedSquare
  show rectangle 0 0 50 50  255 255 0
  delay 100
  show rectangle 0 0 100 100  255 255 0
  delay 100
  show rectangle 0 0 150 150  255 255 0
  delay 100

part removeSquare
  clear -1 -2 -3

task some_task
  keys space
  part showAnimatedSquare
  readkey 1 1000
  part removeSquare
  delay 100

task another_task
  keys a
  part showAnimatedSquare
  readkey 1 5000
  part removeSquare
  delay 200

block test
  tasklist
    some_task 10
  end

block test
  tasklist
    another_task 10
  end

Overview of all the system variables

Below a quick overview of almost all the "system" variables that you can use in your experiment script. They are described in detail in the text, but here they are all together. They typically all contain a numerical value, except for TASKNAME, and BLOCKNAME. The latter two are only of use in the save instruction. The choose-related variables are not listed. They all need to be written in capitals.

RT

last response time, from readkey or readmouse

STATUS

from readkey(s)/readmouse, can be CORRECT, WRONG, TIMEOUT (or 1, 2, 3)

KEY

the key that has been pressed in last readkey/keystatus (a number)

UNDER_MOUSE

the number of the stimulus the participant clicked on

MOUSE_X

the X position of the mouse in last readmouse statement

MOUSE_Y

the Y position of the mouse in last readmouse statement

TABLEROW

randomly chosen once per trial

TASKNAME

the name of the task the trial is in

TRIALCOUNT

the number of trials so far in any task

BLOCKNUMBER

the number of the current block. Starts with 1.

BLOCKNAME

the name of the current block the trial is in

BLOCKORDER

Is normally 1, but if multiple blockorders defined, gives the number of the randomly chosen blockorder

RATE

The chosen value of rating scale

RATE_RT

The RT of the rating process

RATE_STATUS

will be 1 if rated, or 3 if there is a timeout (there is no correct response, of course)

SHOW_COUNTER

Example of show counter
task my_task
   show rectangle 0 0 100 100   0 255 0  # green rectangle
   show rectangle -200 0 100 100   255 0 0  # red rectangle
   show rectangle 200 0 100 100   0 0 255  # blue rectangle
   show text SHOW_COUNTER ## this will be 3
   delay 1000
   clear SHOW_COUNTER ## delete last shown stimulus
SHOW_COUNTER repaces the show-counter set option. It is rarely needed, but in advanced code with many stimuli, it can help to later clear stimuli from the screen (because you might loose track of stimulus counter numbers).

Links to all instructions