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

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.

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

24. IF/ELSE/ELSEIF/ENDIF
25. DRIVE/ENDDRIVE
26. SET can be used to create and set user-defined variables: SET <variable name> <value>
27. Key codes
28. Crossing train
29. 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
30. 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.