Script Command Reference

EDITS IN PROGRESS ...

The TrainPlayer Script Language is designed for simplicity and readability.  It consists of just a small vocabulary of commands and conditions, but also allows access to any item on any menu.

An instruction consists of one or two clauses:

[wait-condition] [command]

where a wait-condition pauses script operation for a certain period of time or until a given event occurs, after which the command is executed and the script proceeds to the next line. 

Both parts are optional, but at least one must be present.  If a wait condition is not given, the command is executed immediately.  It a command is not given, then once the wait condition is satisfied, the script goes on to the next line.

Blank lines in a script are ignored, as are comment lines beginning with asterisk, double backslash, or pound (* or // or #) followed by at least one space.  Commands in scripts are case-insensitive.

A wait condition starts with AT, AFTER, or ON, followed by a clock time, junction number, station name, or keyword.  When a script is running and a wait condition is encountered, the train continues moving, but the script does nothing further until the given event occurs or the specified time elapses.  When that happens, the script goes on to the next command or next line and continues executing.

Red items are new in Version 5.3.

Also of interest: Richard Fletcher's Word doc, TrainPlayer Scripting Reference


Commands

command

action

notes

Forward

set direction to forward; no effect if train is already going forward 1,2

Reverse

set direction to reverse; no effect if already in reverse 1,2

Speed <mph>

set speed to value in mph; begins moving if stationary 1

Stop

decelerate to a stop 1,2

Uncouple <slot>

uncouple at slot (1=behind first car, 2=behind second, ...) 1,2,3

Uncouple <car>

uncouple between car and engine 1,2,3

Uncouple <car> <car>

uncouple between pair of adjacent cars 1,2,3

Throw <jxn> [pos]

throw switch; if position is specified, throw to that position 4,20

Set <var> <value>

set system or user-defined variable to value 5, 26

<label>:

word ending with colon is a label for goto 6

Goto <label>

jump to statement after label 6

Autopause <secs>

pause specified number of seconds on certain events 7

Echo <string>

display string in schedule window 8

Rotate <ttbl> <jxn>

rotate turntable to specified junction 9
Train <train> select specified train 21
Load [options] load or toggle load status of specified cars 22
Unload [options] unload specified cars 22
If   24
Else   24
Elseif   24
Endif   24
Drive   25
Enddrive   25
Let v = v1 [op v2] set variable by arithmetic on pair of values 29
Input <var> [prompt] set variable by prompting for value; no change in value if cancel 30

Wait Conditions

condition

waits until

notes

AT <jxn>

lead car of train crosses junction

10

AT <(t j d)>

lead car of train crosses exact spot (dist d from jxn j on track t)

10, 19

AT <h:m[:s]>

specified time is shown on layout clock; h:m required, secs optional

11

AT <station>

lead car of train enters named station

12

AFTER <jxn>

last car of train crosses junction

10

AFTER <(t j d)>

last car of train crosses exact spot

10, 19

AFTER <h:m:s>

specified actual time has elapsed on wall clock

11

AFTER <station>

last car of train leaves station

12

ON STOP

train comes to a complete stop

13

ON COUPLE

train couples with another car

14

ON THROW <jxn>

specified switch is thrown by any means

15

ON TABLESTOP

turntable finishes rotating

16

ON KEY [key]

user presses any key or specified key

17, 23

Definitions

symbol definition notes

jxn

number of junction or switch; may be preceded by J

18

(t j d)

exact position: on track t, d percent of the way from jxn j

19

h:m:s

hours:minutes:seconds on 24-hour layout clock or wall clock

11

station

name of a station on the layout

 

mph

speed in miles per hour; metric not available

 

slot

car position within train: 1=behind lead car, 2=behind 1, etc.

3

car

car identifier, as shown in label box of car props or by show car-ids

3

pos

switch position: 0 or 1 for normal switch, higher for multi-way

20

var

variable name as found in settings section of registry

5

value

value of settings variable

5

label

line of script to which a goto statement may jump

6

secs

seconds to pause after stop, reverse, couple

7

string

any string of text; quotes not required

8

ttbl

number of turntable, as shown by tooltip or properties

9

System Variables

symbol definition notes

$TIME

current time of day (h:m:s in 24-hour format)

 

$DATE

today's date (mm/dd/yyyy)

 

$LAYOUT

name of active layout

$CAR

label of selected car (if any)

 

$TRAIN

name of selected train

 
$SPEED speed of select train in MPH (KPH if metric)  
$KEY numeric code of last key hit on keyboard 27
$X_TRAIN name of "crossing" train -- train owning calling script 28
     

Examples

statement

description

at 15:30 speed 10

when clock says 3:30PM, set speed to 10MPH; start train if not moving

after 0:0:10 stop

wait 10 seconds, then stop train

at J35 throw 99 1

when train crosses junction 35, throw switch 99 to the 1 position

on couple forward

after coupling occurs, set train direction to forward

after edville speed 40

after last car of train leaves Edville, accelerate to 40 MPH

uncouple B13

uncouple on side of car B13 closest to engine

uncouple B05 F12

uncouple on side of car B05 closest to car F12

echo "reached harbor dock"

print string in schedule window

autopause 3

from this point on, pause 3 secs after every stop, uncouple, or direction change

set AccelFactor 20

set the global acceleration factor to 20

rotate 321 96

rotate turntable #321 until its bridge track hits junction #96

Notes:

  1. Command applies to the train being driven by this script
  2. When autopause is in effect, a pause is inserted before and/or after this action
  3. Uncouple can be specified by a single integer, giving a "slot position" relative to the lead car.  This varies with the train's direction, so is confusing and not recommended.  Better to specify a single car ID -- the car uncouples from whichever neighbor closer to the engine -- or ID's of two coupled cars, which uncouple between them.
  4. THROW with no position throws a switch to its next position, as when you click it on the layout.  To throw to a specific position, use tooltips to identify the desired position (usually 0 or 1) and include that in the command.
  5. SET is an advanced command for changing program preferences from a script.  The variable name is any name from hkcu\Software\TrainPlayer\TrainPlayer\Settings, and the value is whatever value is accepted by that variable.  Details are not documented.  Most are true/false (1/0), strings, or numeric values.  For more info, write support.
  6. GOTO jumps to the named label, which must appear elsewhere in the script.  A label is a word followed by a colon on a line by itself.
  7. AUTOPAUSE causes a delay of the given number of seconds before and/or after these operations: forward, reverse, stop, uncouple.  The effect remains in effect until another autopause command.  To cancel, enter autopause 0 (zero).  An advanced preference can be used to have "autopause 2" in effect for all scripts.
  8. ECHO prints a string of text to the schedule window.  An advanced preference can be used to automatically echo all comment lines to this window.
  9. ROTATE takes a turntable number and the number of a junction on its rim.  It begins rotation of the table until the bridge track hits the specified junction.  Rotate should be followed by ON TABLESTOP if you need to wait until rotation ends before proceeding.
  10. A car crosses a junction or track position when its midpoint crosses, not its leading or trailing edge.  By the time it crosses, it is too late to throw that switch, i.e., "AT J35 THROW J35" will not work.
  11. AT <TIME> waits until the layout clock reaches the specified hour, whether or not the clock is on display.  AFTER <TIME> is a way of waiting a while in real time before continuing.
  12. AT/AFTER <STATION> happens when the lead or last car enters or departs a station.  This occurs when the car crosses the rectangular area of the station.  To see station areas and names, click the Station tool.  Two-word station names must be surrounded by double quotes.
  13. ON STOP waits until a train has coasted to a stop.  This usually follows a stop command, so next command doesn't start while the train is still decelerating.  Has no effect if train is already at a stop.
  14. ON COUPLE waits until the current train couples with another.  The script is then operating the enlarged train.
  15. ON THROW is a way to coordinate activites of two scripts.  One can be waiting for a throw of some arbitrary switch, and the other can throw it when the time comes.
  16. ON TABLESTOP waits until a rotating turntable stops.  You do not specify a turntable number, so only one can be rotating at a time.  This condition usually follows a rotate command.
  17. ON KEY pauses until the user presses any key.  This should be preceded by an echo command indicating that the script is waiting for a key, otherwise the user will wonder why the script it stalled.
  18. In most commands and conditions, a junction number may be preceded by J for readability.  The exception is in a (t j d) position indicator.
  19. (T J D) indicates an exact position on the layout.  T is the number of a track section, J a junction at one or the other end of T, and D a distance, in percent of the length of T.  An optional "r" after D can be used to indicate which direction the train should be headed at this position (used when repositioning a train in a Go To Command action).  For example, if the junctions at the end of track 6 are numbers 10 and 12, then (6 10 40) is a point 40% of the way along the track starting at the 10 end.  Expression must be enclosed in parentheses.  Values may be separated by space or comma.  Junction number must not be preceded by J.
  20. A switch position is 0 or 1 for a normal two-way switch, or a higher value for multi-way switches.  The value corresponding to a particular configuration must be determined using a tooltip.  Or you can use an insert command to let the program determine the value and insert it into the script.
  21. The TRAIN command was introduced in Version 4.2.  It selects a specified train as if you had clicked on it.  The argument can be (a) a train name, (b) a numeric train id (as seen in the Train Properties dialog), or (c) the car-top label of any car, in which case the train selected is the one containing that car.  Examples:  
    train Broadway Local selects train named "Broadway Local"
    train 44 selects train with id=44
    train X68 selects train containing car X68
  22. LOAD and UNLOAD change the loaded status of a specified set of cars.  Command format is:  
    Load|Unload [TOGGLE] [Car|Cut|Train] ID[,ID...] [loadname]

The command indicates whether you want to load or unload the given cars, or toggle their current status (use Load Toggle).  The car set is specified by a keyword followed by one or more identifiers.  The keyword TRAIN can be followed by a train name, or not; if no name is given, the current train is assumed.  Keywords CAR and CUT can be followed by a comma-delimited list of car ids; in the case of CUT, all similar cars surrounding the named car are included in the set.  If a loadname is given at the end of the command, it replaces any load currently associated with the named cars.

load car X44 load given car with its default load
load cut H22 gravel load all cars around H22 with given load
unload train Freight2 unload all cars of given train
load toggle car X44,H22,H24 toggle load status of given list of cars
  1. ON KEY can now be followed by an argument indicating which key must be pressed to terminate the wait.  If no argument is given, then the wait ends when any key is pressed; otherwise the wait continues until the specified key is pressed.  The key is given by (a) a letter or digit, (b) a function key name (F1 to F12), or (c) a numeric value representing a Windows Virtual-Key Code.  Examples:  
    on key waits for any key
    on key A waits for press of 'a' or 'A'
    on key F2 waits for press of F2
    on key 27 waits for press of ESC
  2. IF/ELSE/ELSEIF/ENDIF
  3. DRIVE/ENDDRIVE
  4. SET can be used to create and set user-defined variables: SET <variable name> <value>
  5. Key codes
  6. Crossing train
  7. LET combines two values using + - * or / (for numeric values) or + (for strings).  The format is:

    LET var = val1 [op val2]

    var is an existing or new variable -- same as in SET
    val1 and val2 are values, literals or @-references
    op is an operator, one of: + - * /

    Op and val2 can be omitted, in which case this is the same as a SET -- assigns a value to a variable
    If val1 and val2 are both numeric (integer or floating), then you can use any operator and will get a numeric result; otherwise, if either value is a string, you can only use + to concatenate the two.
    The = sign is required.  val1, op, val2 must be separated by spaces.

    Examples:

    LET v2 = 9 + 6
    LET v2 = @v1 * 6.3
    LET v2 = @v1
    LET v2 = "a string" + @v1
  8. INPUT brings up a prompt dialog and waits for response.  The result is copied into the specified variable.  The command may include a prompt string; if omitted, a default string is used.

Menu Commands

The set of commands available for scripting is not limited to the commands listed above.  Any command on the menu can be used in a script.  Executing a menu command from a script causes the same action as choosing it from the menu.

To specify a menu command, enter the names as they appear in the menu, starting with a main menu item (File, Edit, etc.), followed by a submenu item (File Open, Edit Copy, etc.) and a third if the menu goes deeper.  If an item at any level consists of more than one word, the item must be enclosed in quotes.

As a shortcut, you do not need to spell out all the words in full.  You may abbreviate a menu item to its first few characters, just enough to distinguish the command from others.  For example, "view toolbars customize" may be shortened to "vi to cu."

Popup menu items are available also, Car, Layout, Switch, Turntable, Track, Circle, Horn, Station.

Many menu commands do not make sense in the context of a script.  Some bring up dialogs, which are not scriptable.  Some duplicate functions available using Train Commands.  Some are toggle switches, but since a script does not have a way to know the current setting, results are unpredictable.  Context menus often need to reference a point on the layout -- where you right-clicked to bring up the menu -- but since a script cannot supply this, context menus may do nothing or work unpredictably.

ARGUMENTS.  Some menu commands bring up prompts asking the user for information.  In scripting, for certain commands, the information can be supplied as an argument.  Train > Name is an example.  Others are under development.

Menu Command Examples

file save

bring up File Save dialog to save the current layout

view "zoom in"

magnify view

view tool cust

bring up Tools Customization dialog

car "add car" reefer

insert a refrigerator car at current insert point of selected train

tools "enable yard mode"

turn on Yard Mode operation

train new

create new four-car train at default location

window "tile horiz"

if multiple document windows are visible, tile them

train freight1

select train Freight1

train speed double

double speed of selected train
train name "SF Express" change name of selected train