Syntax of the scripting language

$ psycc -s

PsyToolkit Version 1.9.4

This is an overview of all commands of the PsyToolkit scripting
language. Commands can have parameters (arguments).  Obligatory
arguments are in [].  Optional ones in (). Lines with # are
commentary.

----------------------------------------------------------------------

options  (this section is optional)
  bitmapdir [path]
  datadir [path]
  fontdir [path]
  videodir [path]
  sounddir [path]
  resolution [width][height]
  fullscreen
  window
  render standard|doublebuffer
  transparency [on]
  screensize [width][height]
  screendistance [distance]
  coordinates [cartesian|polar]
  origin [center|topleft]
  centerzero (to be deprecated, replaced by origin)
  vsync_off
  version [version number]
  parallelport [in|out]  [data|1|14|16|17]  [in|out]  [data|1|14|16|17]
  egi [host](port)
  pcidio24 [in|out]  [a|b|c|c_low|c_high]  [in|out]  [a|b|c|c_low|c_high]
  cedrus (RB-530|RB-730|RB-830|RB-834)
  iolab (voicekey duration silence trigger gain1 gain2 micpassthrough)
  ultra
  mouse [on]
  escape (key)
  variable [name][value]
  executable (path)[name]

bitmaps (this section is optional)
  [bitmapname] (path)[filename]

sounds (this section is optional)
  [soundname] (path)[filename]

fonts (this section is optional)
  [fontname] (path)[font-file-name] (fontsize)

# videos (this section is optional) 
#   [videoname] (path)[filename]

table [tablename] (table sections are optional)
  [tablerows](...)

task [name] (there must be at least one task)
  # c functions
  c [ one line of c code ]
  c-begin ( followed by new line and lines of c code )
  c-end
  c-file [filename]
  # visual and auditory stimulus functions
  clear [number(s)] | screen
  draw [on|off]
  font [fontname]
  show bitmap [bitmapname] (xpos ypos)(width height)
  show text [string] (xpos|ypos)(red green blue)
  show rectangle [x y w h red green blue]
  show video [videoname] (once|loop)(xpos)(ypos)(width height)
  # videocontrol [videoname]  # continues next line...
  #   [stop|pause|resume|play|on|loop|once|move|clear](xpos)(ypos)(width height)
  sound [soundname]
  silence [soundname]
  # sprites functions
  sprite create ([&$][variable])[bitmapname]([xpos][ypos])(direction)(speed)(hide)
  sprite [sprite] [bitmapname](xpos)(ypos)
  sprite [sprite] freeze|move|hide|display
  sprite [sprite] jump (xpos)(ypos)
  sprite [sprite] move (to|towards) (xpos)(ypos)(speed)
  sprite [sprite] move direction (angle)(speed)
  sprite [sprite] move path (speed) x1 y1 ... xn yn
  sprite [sprite] speed (speed)
  sprite [sprite] accelerate (speed change)
  sprite [sprite] bitmap [bitmapname]
  sprites [delete|freeze|unfreeze|display|bounce(borders|sprites)|update] all
  # control functions
  if [conditional expression]
   [...]
  fi
  while [conditional expression]
   [...]
  while-end
  end [task|tasklist]
  # condition selection related function
  table [tablename]
  # time related functions
  delay [time]
  nap
  timestamp [timestampname]
  # keyboard functions
  keys [list of keycodes] # use only once at top of task description!
  keystatus [correct# in keyslist 1..n]
  readkey [correct# in keyslist 1..n][maxtime]
  # mouse functions
  mousestatus
  readmouse (l|m|r)[bitmap|sprite][maxtime](range begin end)
  mouse [show|hide](x y)
  # choose with mouse functions 
  choose option select (bitmap)
  choose option maxselect (number)
  choose option exit (stimulus#)
  ## choose option show (rectangle red,green,blue | bitmap bitmapname)
  choose [maxtime](stimulus_numbers...)
  # special device funtions
  parallelport [set|clear][pinnumber](pinnumber)(pinnumber)(etc)
  pcidio24 set [a|b|c] [value 0-255]
  send_egi [code label duration]
  cedrus readkey [button][max time]
  cedrus status
  cedrus clear
  cedrus reset
  iolab readkey [button][max time]
  iolab status
  iolab clear
  iolab reset
  ultra readykey [button][max time]
  ultra status
  # variable setting functions
  set # does not all fit on one line, therefore on multiple lines:
     [$|&]
     [variablename]
     [
       [integer_value]                     | 
       [$|&][other-variable-name]          |
       random[lowest][highest](stepsize)   |
       random from (...)                   |
       expression [...]                    |
       c-expression [...]                  |
       increase|decrease (value)           |
       pcidio24 [a|b|c]                    |
       time-since-start                    |
       timestamp-diff [1][2]               |
       timestamp-seconds [timestamp]       |
       timestamp-milliseconds [timestamp]  |
       bitmap-under-mouse (x y) (up|down)(from [value])(to value)
     ]
  error
  # data output function
  save [valuelist] # this should be last statement in a task description!

message [bitmapname](key)

block [blockname] (repetitions)
  bitmap [bitmapname]
  bitmap_from_file [filename]
  c [ one line of c code ]
  clear screen
  message [bitmapname](key)
  pager [bitmapname](...)
  set
  &[variablename][int_value|random[lowest][highest](stepsize)|c-expression|increase|from-file]
  system [systemcall]
  maxtime [msecs]
  tasklist
    [taskname][n]                      
    [taskname][n](fixed|no_repeat|all_before_repeat)
    [taskname][n](correct[maxn])(allcorrect[maxn])(repeat_trial_on_error|repeat_task_on_error)
  end
  wait_for_key (key)
  continue_repeat_keys (continue key)(repeat key)
  feedback
    
  end

feedback
  label [xpos][ypos][text]
  text [xpos][ypos][mean|sum][c?] (; prefix [text] ; postfix [text] ; select c? == value)
  lineplot [c?] ( ; color c? )
  xyplot [c?][c?] (; select c? == value )
end

-------------------------------------------------------------------------------

SPECIAL VARIABLES AVAILABLE IN TASK:
  RT          last response time, from readkey or readmouse
  TT          release time (time it takes to release the key. TT > RT)
  EXTRT       same as RT, but measures by external keyboard (Cedrus or IOLab)
  EXTTT       same as TT, but measures by external keyboard (Cedrus or IOLab)
  STATUS      from readkey, can be CORRECT|WRONG|TIMEOUT
  TABLEROW    randomly chosen once per trial
  KEY         the key that has been pressed in last readkey/keystatus
  KEYPRESSED  1 if key is pressed, 0 if not; currently only for IoLab & Cedrus
  MOUSE_X     the X position of the mouse in last readmouse statement
  MOUSE_Y     the Y position of the mouse in last readmouse statement
  VSYNC_DELAY the time waited for a vsync signal (available following
              each show command)
  BLOCKNAME   the name of the current block the trial is in
  BLOCKNUMBER the number of the current block. Starts with
              1. Important note: unlikely event that there is more
              than one tasklist in a BLOCK (not recommended), the
              BLOCKNUMBER is still increased.

CONDITIONAL EXPRESSIONS IN IF AND WHILE STATEMENTS
  at least 3 seperate parameters can be used, for example: RT < 5

  parameters 1 and 3 can be variables or values.  Variables can be
  local or global variables, or special variables.

  parameter 2 is something like "==" (but even "=" is allowed).

  operators in conditional expressions can be.
  and , or you can use &&
  or , or you can use ||

VARIABLE REFERAL
  variables defined in set should start with $ or &
  $ are local variable (used in one trial only)
  & are global variable, which can also be set in the block section
  values chosen from a tablerow should start with @

TABLE ENTRIES CAN BE ONE OF THE FOLLOWING
  strings with " "
  integers
  bitmaps/sounds

XPOS and YPOS specify the position of stimuli on the screen.  Specify
  a number in accordance with the chosen coordinate system.  Or use
  CENTER, for choosing the screen centered position (for X
  and/or Y).  Per default, coordinates are cartesian with 0,0 being the
  top left corner.  The option centerzero make 0,0 the center of the
  screen.  In polar, 0,0 is the screen and the coordinates are in
  1/100th of a degree.

EXPRESSION 
  You can "set" values using a formula. All common functions are
  supported (see documentation). You can also use PsyToolkit local and
  global variables or special variables (e.g., RT or STATUS) and table
  entries (assuming they are not strings).

C-EXPRESSION (REPLACED BY EXPRESSION SINCE 1.4.3 AND NOT RECOMMENDED)
  You can use plain c.  Refer to script variables with a ^, for example
  set $x c-expression abs 100 + ^RT - ^$myvariable
  This will take the RT from the last readkey
  Make sure that they are at least 1 spc apart from other c-code!
  Do not use a semicolon at the end of the expression (although it
  does not hurt).

KEY CODES
  -- shift keys --
  lshift rshift
  -- control keys --
  lcontrol rcontrol
  -- alt keys --
  lalt ralt
  -- logo keys --
  lsuper rsuper
  -- special keys --
  enter capslock tab
  space end home insert
  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
  kp_period kp_slash kp_star kp_minus kp_plus kp_enter
  -- alphanumerical keys --
  a to z, 0 to 9