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)
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
  delay 100
  clear -1

block MyBlock
  tasklist
    MyTask 200
  end

fullscreen

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

In the online version (Javascript), fullscreen does not work in Apple’s Safari browser (Apple won’t allow fullscreen and keyboard input).
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

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,videodir

The options fontdir,datadir,bitmapdir,sounddir,videodir 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 identication 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
  videodir    /usr/local/videos
  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 and videos, although videos are not well supported and currently only work in the C mode. 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 some more.

The bitmaps line has no parameters, and is followed by lines describing the bitmap, each bitmap having a name and 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 extension .png. In the example below, PsyToolkit assumes a file house.png to exist because no further bitmap info is given. This is actually the recommended way of working (it is definitely easiest).

Example of bitmaps and how to refer to them in a task
bitmaps
  house
  funnyface /home/user/funny.bmp
  cookie    /usr/local/cookie.jpeg
  smiley    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 wav file format is the one that is most widely used and recommended for online studies.

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

fonts

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.
In both C and Javascript, 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 sounds 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.

tasks

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

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

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. An integer 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.

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 immedeately need it, and you can write scripts without set.
set a local variable to a value (the $ indicates that it is local)
set $x 10
set a global variable to a value (the & indicates that it is local)
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 11
decrease the value of a variable (default is 1)
set $x 10
set $x decrease # after this, $x has value 9
use a mathematics expression
set $x expression $x / 2 + $a + 1
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
dely 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
get bitmap number of the bitmap currently under the mouse (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 x-coordinate
  set $x bitmap-under-mouse $myMouseX $myMouseY ## $x should be 1

Summary of set

Summary of all set functions.

Set is not needed for beginners! It really allows flexibity 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

    • 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

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

show

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

This is a key instruction, which can show a rectangle, a bitmap, or a text anywhere on the screen. It can also change the background color (show background). The number of parameters given to a show instruction can vary. The show command for bitmap, rectangle, and text, and text, will now be given separately.

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

show background

Note show background (Red,Green,Blue)

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)

show text

The show text instruction shows text. You need to specify a font and font size as well in the fonts section

In the desktop version, you can load True Type Files (TTF). In the web-based version, you can only use three standard types of fonts, namely arial, times, and courier.
Note show text [text](X,Y)(Red,Green,Blue)
Example of show text for Linux
fonts
  MyArial arial.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

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

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

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

readmouse

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

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


[[task-choose]]
==== 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
[source]

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)

TIP: The *choose* command is particularly useful for memory tasks.

[[task-rate]]
==== 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
[source]

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
[source]

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
[source]

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

[[task-save]]
==== save

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

NOTE: 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.

TIP: 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.

TIP: The best place for the save command is at the end of your task
description.

[icon="./syntax.png"]
NOTE: *save* [list of variables]

.Example of save
[source]

save BLOCKNAME RT STATUS

[[task-sound]]
==== 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.

[icon="./syntax.png"]
NOTE: *sound* [sound name (as defined in 'sounds']

.Example of sound
[source]

sound MySoundFile delay 200 silence MySoundFile

[[task-if]]
==== 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
[source]

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

[[task-while]]
==== while

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

.Examples of while loop
[source]

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

NOTE: 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.

==== while

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

.Examples of while
[source]

while $x < 100 increase $x save $x while-end

==== font

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

.Examples of font
[source]

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

[[task-end]]
==== 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
[source]

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

==== sprite

TIP: 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
[source]

bitmaps mystimulus

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

block test tasklust MyTask 1 end

TIP: 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.

TIP: Have a look at the Linux example directory to see how the
commands below work.

|===
| Function name | What it does | example

3+| _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
3+| _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
3+| _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
3+| _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
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
3+| _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
|===

TIP: 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
http://www.psytoolkit.org/download/manual/ultra-keyboard-howto.1.pdf[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.

[[table]]
== 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
[source]

table MyTable 10 2 bitmap1 -10 1 bitmap2

.Example of a table with strings
[source]

table MyTable 10 2 bitmap1 "condition one" -10 1 bitmap2 "condition two"

In a task that uses a table (as instructed with the
xref:task-table[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.

TIP: 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
xref:block-tasklist[tasklist] instruction in xref:block[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.


[[block]]
== 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.

.Example of simple block, calling the stroop task 100 times
[source]

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

[[block-bitmap]]
==== 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
[source]

block Myblock bitmap MyInstruction wait_for_key tasklist strooptask 100 end

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

[[block-sound]]
==== sound

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

.Example of sound in block
[source]

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

[[block-delay]]
==== delay

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

.Example of message in block
[source]

block Myblock bitmap number3 delay 500 bitmap number2 delay 500 bitmap number1 delay 500 tasklist mytask 100 end

[[block-message]]
==== 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)
[source]

block Myblock message MyInstruction tasklist strooptask 100 end message ThankYouBitmap

.Example of message in block (example waiting for key 'b')
[source]

block Myblock message MyInstruction b tasklist strooptask 100 end message ThankYouBitmap

TIP: 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)
[source]

block Myblock message MyInstruction mouse tasklist strooptask 100 end message ThankYouBitmap

[[block-pager]]
==== pager

Sometimes you want a series of instructions and let the browser use
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.

TIP: Alternatively, you can use the mouse instead of the keyboard
(below).

CAUTION: 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
[source]

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.

NOTE: 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
[source]

block Myblock pager option mouse back -200 200 next 0 200 start 200 200 pager MyInstruction1 MyInstruction2 MyInstruction3 tasklist strooptask 100 end

[[block-set]]
=== setting variables

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

.Example of message in block
[source]

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

[[block-tasklist]]
=== 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
[source]

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

NOTE: Repeat_on_error only works when you use tables, random variables
are not set to the same values.

.Example of simple tasklist.
[source]

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 @2 @3 @4 readkey @5 2000 if STATUS == WRONG error ## this tells PsyTookit that this trial is considered an error fi save @1 STATUS RT

block MyTraining tasklist Mytask 10 repeat_on_error end

NOTE: In the example above, you see a red or green rectangle, and 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
[source]

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
[source]

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 immedeatly 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
[source]

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

TIP: 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.

CAUTION: Make sure that you always have an *end* at the end of your tasklist

[[block-maxtime]]
=== 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.

TIP: You can still have instructions before the task list (e.g., as a
xref:block-message[message or pager], they are not counted toward the
maxtime).

.Example of block with maxtime in 2 minutes (notice the m)
[source]

block MyTraining maxtime 2m tasklist strooptask 10 all_before_repeat no_repeat end

.Example of block with maxtime in 100 seconds (notice the s)
[source]

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
[source]

block MyTraining maxtime &MyVariable tasklist strooptask 10 all_before_repeat no_repeat end

[[block-feedback]]
=== 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: link:feedback.html[how to use feedback]

[[blockorder]]
== blockorder

TIP: 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
[source]

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.

TIP: 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)
[source]

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]]
== 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.

TIP: Included files must be in the same directory as the main script
file.

.Example of how to use include
[source]

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

TIP: Included files (like _tablefile.txt_ in the example) should not
include other files using _include_.


[[part]]
== 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.

TIP: _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"
[source]

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]]
== Links to all instructions

(this list is not yet complete)

Options:
xref:options-origin[origin]|
xref:options-origin[bitmapdir]|
xref:options-origin[sounddir]|
xref:options-origin[videodir]|
xref:options-origin[fontdir]|
xref:options-fullscreen[fullscreen]|
xref:options-resolution[resolution]|
xref:options-version[version]|
xref:options-mouse[mouse]|
xref:options-variable[variable]|
xref:options-window[window]|
xref:options-screensize[screensize]|
xref:options-screendistance[screendistance]|
xref:options_vsync_off[vsync]|
xref:options-egi[egi]|xref:options-escape[escape]|
xref:options-parallelport[parallelport]|
xref:options-pcidio24[pcidio24]|xref:options-cedrus[cedrus]|
xref:options-iolab[iolab]|
xref:options-et[eye-tracker]|
xref:options-executable[executable]

Basic instructions:
xref:task-keys[keys]|
xref:task-show[show]|
xref:task-text[text]|
xref:task-clear[clear]|
xref:task-sound[sound]|
xref:task-keys[keys]|
xref:task-readkey[readkey]|
xref:task-delay[delay]|
xref:task-save[save]|
xref:task-table[table]

Medium advanced instructions:
xref:task-readmouse[readmouse]|
xref:task-if[if]|
xref:task-while[while]|
xref:task-move[move]|
xref:task-relocate[relocate]|
xref:task-hide[hide]|
xref:task-unhide[unhide]

Advanced instructions:
xref:task-readkeys[readkeys]|
xref:task-readmouse[readmouse]|
xref:task-keystatus[keystatus]|
xref:task-choose[choose]|
xref:task-set[set]
xref:task-progress[progress]

Block instructions:
xref:block-bitmap[bitmap]|
xref:block-sound[sound]|
xref:block-delay[delay]|
xref:block-message[message]|
xref:block-pager[pager]|
xref:block-set[set]|
xref:block-tasklist[tasklist]|
xref:block-feedback[feedback]

Special instructions:
xref:include[include]|
xref:part[part]|
xref:blockorder[blockorder]