Demo

Toolbar

Playing

Recording

Authoring

 Editor
 Tooltips
 Car IDs
 Click Insert
 Click Goto
 Rewinds
 Advanced

Reference

 Commands
 Conditions
 Menus

Scripting is a means of automating railroad operation.  A script is a set of instructions attached to a train, telling it where and how to travel.  You can create a script by typing instructions, or by recording train moves, or a combination of both.  When you run the script, the instructions are executed and the train moves accordingly.  While one or more trains is being run by script, you can be operating others manually.

Several script-related devices are new in 3.0, as shown in the screen shot below.  Under the Train menu is a Script submenu, with functions duplicated on the Script toolbar.  Choosing Edit brings up the Script Editor, where you can enter commands or watch them execute.  As the script runs, status messages are shown in the Schedule window.

Watch the demo

TrainPlayer 3.0 Beta is delivered with one scripted layout: the Cerro Azul RR, a long-time favorite of switchback and mountain railroad fans.  To see the script in action, choose the new No. 47 entry from the Layouts dialog, as shown here.  Notice that in TrainPlayer 3.0, when you click an entry, you see a little preview.

Whenever you open a layout having a script, you are notified by the word SCRIPTED on the status bar, and an alert telling you about the script:

To play the script, click the Play button.  The Schedule window comes up and the script begins operating.  Sit back and watch.  If all goes well, a switcher engine will deliver empty hoppers to locations on the mountainside, and return with two gondolas full of ore.

To learn more, click the Edit button.  The Script Editor comes up, where you can view the script, edit it, play, stop, or rewind it, watch the commands as they execute.  Most scripts have comments at the top describing the operations to be carried out -- for a challenge, try running through these operations yourself before playing the script.

Check "Don't show this message again" if you do not wish to see this alert on opening a scripted layout.  You can bring it back if you change your mind later.

To stop the script, click Stop on the toolbar, or press ESC.  To resume where you left off, click Play again.  To start over at the beginning, click Rewind, then Play.

The Script Toolbar          

After you have seen the Scripted Layout alert a time or two, you can dismiss it and use the Script toolbar instead.  Buttons work as follows:

• Record: begin recording.  Button turns red when recording, green when playing back.  Clicking this button while recording has the same effect as clicking Stop.  Button is dim if selected train has no engine, and thus cannot be scripted.  If the selected train has no script, Record will create one; if there is a script, recorded commands will be inserted into the existing script after the current command.

• Rewind: move trains, switches, and script back to starting positions.  For more information, see Rewind Points.

• Stop: when playing back, stop train and script instantly.  When recording, stop recording, do not stop train.

• Play: begin playing script at current command.

• Edit: open Script Editor window for the script on the selected train.

Stop and Play buttons affect the current train/script only, unless you change a preference in the Advanced dialog, in which case they apply to all trains and scripts.

When you click Stop, trains do not coast to a stop -- they stop instantly.  If you then click Start, the trains will pick up where they left off, but not instantly -- they come up to speed as usual.

  Play a script

If you tried the demo, you basically know how to play a script.  This section contains additional notes and details.

To play a script:

1.  Open a scripted layout.  Before you can play a script, you must open a layout which has one.  If a layout has any scripts at all, it will display SCRIPTED on the status bar.  If you do not see this, then there are no scripts you can play.

2.  Locate a scripted train.  There can be more than one script per layout, each associated with a particular train.  You can configure whether the Play button will start all of them at once, or just the one on the selected train.  If the Play button is dimmed, it means the latter option is in effect, and the currently selected train does not have a script.

3.  Examine the script.  Even if you're not planning to edit a script, you might want to take a look at it.  For one thing, it might begin with comments telling what it is supposed to do.  To view the script, click Edit Script in the alert dialog or on the toolbar, or choose Train > Script > Edit.  If the selected train does not have a script, this action creates a new script.  Details about the Script Editor are given below.

4.  Rewind.  A script will not start correctly unless trains are in the expected positions.  The Rewind command puts them there.  If you have moved some trains around, click Rewind to put them in place before playing the script..

5.  Play.  To begin playing a script, click the Play Script button on the alert dialog or the toolbar, or choose Train > Script > Play.  The recording light on the toolbar turns green, the Schedule window comes up, and the script begins.

6.  Stop.  To stop or pause, click Stop on the toolbar or press ESC.  Both the script and the train stop immediately.  To resume, click Play, or to start over, click Rewind, then Play.

7.  Drive.  You can operate trains while a script is running, including operating a scripted train.  However, if you obstruct or tinker with a train being driven by a script, the script is not likely to run correctly afterwards.

  Record a script

The easiest way to develop a script is by recording.  Press Record, operate your layout a while, press Stop, and you have a playable script, captured as you were driving.  Click Rewind, then Play, and you can sit back and admire your moves.  If you have the Script Editor on display, the commands appear as they are being recorded, and afterwards you can edit them in the same window.

To record a script:

1.  Get in position.  Put the trains where you want them, then use File Save or Save As to store the arrangement in the layout file.  When you distribute a script, its starting point should match the train positions when the layout file is opened.

2.  Practice.  Plan your operating scheme, maybe go through some of the moves, so you can do them smoothly while recording.  You can work out one sequence at a time, record it, then go on to the next.

3.  View the window.  If you want to follow along, bring up the Script Editor before you start recording.  While you're at it, you might enter comments indicating what operations you plan to carry out.  Include car IDs in these comments so the program can highlight the indicated cars.

4.  Begin recording.  Click the Record button on the toolbar.  It turns red, and the recorder is now running.  But take your time -- this is not a tape recorder, there are no wheels running, it doesn't actually record until you do something.

5.  Operate.  Operate as you normally would, using mouse and keyboard.  The recorder captures speed and direction changes, uncouplings, switch throws, and turntable rotations.  Recording is not time sensitive, so if you pause between moves, it will not affect playback.

6.  Stop or pause.  Click the Stop button on the Script toolbar.  Recording will stop.  You can then rewind and play back what you recorded, or click Record again to continue recording where you left off, or both.

7.  Save the recording.  To save the recorded script, save the layout.  There are other methods too, described below.

8.  Edit.  The recording mechanism is not perfect, nor probably were your operations.  To make repairs or polish the script, you can edit it by hand, or record over bad sections.  Both require some familiarity with the command language; read on.

  Author a script

Developing a script by hand is an exercise in programming.  It's not for everyone.  But the language is not hard to understand, the program provides tools to help with the job, and if you're a model railroader then you are likely to be of a do-it-yourself mindset, so why not give it a try?  With a little practice you can type out a whole series of operations in a few minutes.

A script is a series of commands, stored in a text file.  Each command carries out an operation you would normally do with the mouse: sets the speed, changes the direction, throws a switch, etc.  Most commands are preceded by a wait condition telling the command when it should execute, say when the train gets to a certain spot.  When the script runs, it starts at the first line, waits until the first condition is met, executes the first command, goes to the next line, and so on.  A line without a wait condition executes the command immediately.

As an example, say you are operating a loco in a yard, and your job is to pick up a car from the adjacent track.  You would crank up to a slow speed, pull forward past the switch, stop, throw the switch, back up until you couple, then stop.  In a script, this sequence of operations would look like this:

speed 5

after J22 stop

throw J22

reverse

speed 5

on couple stop

The speed command gets the loco underway and accelerates to 5 MPH.  After it passes the switch labelled J22, the stop command is executed, and the loco decelerates to a stop.  Switch 22 is then thrown to its alternate position, the loco goes into reverse, accelerates to 5 MPH, continues on until it couples with something, then stops.

If this makes sense to you, then you're ready to write scripts.  Refer to the reference section for details about command syntax, read the next parts about tools to make the job easier, then start typing some commands into the Script Editor and see if you can make something happen.

The Script Editor

The Script Editor consists of a few buttons and a text box.  The text box is for viewing and editing the script.  The top three buttons are conveniences -- they work the same way as the corresponding buttons on the script toolbar.  The Advanced button brings up a dialog of advanced scripting options, described in a later section.

Each script has its own editor window.  When you click Edit Script, the window and script which come up are for the current train.  To see a script for a different train, select the train and click Edit Script again.

Tooltips

In developing a script you will need to know the numbers of tracks, junctions, turntables, and cars.  TrainPlayer 3 makes these available via tooltips.

To use tooltips:

1.  Enable tooltips by making sure Tools > Show Tooltips is checked.

2.  If the Run tool is active, you see a tooltip when you hover the mouse pointer over a car or a switch.  If the Track or Edit tool is active, you also see tooltips over track sections, turntables, and non-switchable junctions.

3.  If a tooltip does not show up, it may be because a dialog or other window has the focus.  Click anywhere in the layout window so it becomes active, and try again.
 

Car IDs

Labelling of car tops in TrainPlayer 3 is much improved over earlier versions.  For one thing, car labels now look "painted on," so they rotate with the cars.  For another, the display of the labels is now a car property, saved in the layout file and retained between sessions.  Finally, car label display can now be turned on or off for specific cars or trains.

To show or hide a car label, choose one of the subcommands under Train > Show Car IDs.  One affects only the selected car; another affects all cars of the selected train; the third affects all cars.  All are toggles.

Click To Insert

When developing scripts by hand, you often need to enter junction or switch numbers and positions.  TrainPlayer can do this for you when you right-click a junction or switch. 

With the Script Editor window visible, and the edit cursor positioned where you want the insertion to go, right-click and choose one of:

• Insert junction number: inserts J followed by the number of the switch or junction. This is typically used when entering an AT or AFTER condition to cause an action at a junction.

• Insert throw here: inserts THROW followed by the switch number, followed by the current switch position, then carriage return.  This will ensure that the switch goes to its current position when the script executes that statement.

• Insert throw alternate: inserts THROW, switch number, then the other position of the switch, i.e., where it would be if thrown.  This is a shortcut for throwing the switch, then inserting "throw here."

Go To Statement

If you right-click a line in the script text window, the menu includes a command Go To Statement.  This means advance the script pointer to this statement, so the next time you begin playing, it starts here.

This is not quite as handy as it sounds.  Moving the script pointer does not move the trains, so unless the trains are in the right places, starting the script from an arbitrary statement will not work well.  However, there is a detail which can get around this in many cases: if the line you select has a position indicator -- an AT (T,J,D) wait condition specifying a precise location -- then the train will jump to that location when you choose the command.  The train and script will be in synch, and playback will work as expected.

But there is another detail.  This is not a rewind.  The train which jumps is the current train, with its current consist of cars.  If you have done some coupling or uncoupling since the script ran past that statement, then jumping back to it may not restore the original arrangement.

  Rewind Points

In the context of TrainPlayer, "rewind" means "set up the trains in preparation for an operating session."  Normally when you open a layout file it is already in this situation -- everything is in the right place to start, so you can just hit Play.  Now suppose you play the script partway through, lose interest, and decide to do a bit of track repair.  You move some track around, then save your changes.

Oops.

At this point the trains are in random positions.  If you overwrote the original file, you lost data about where they were, and you no longer know where the rewind should go.  The script will no longer work.

To deal with this, TrainPlayer 3 introduces the concept of a "rewind point."  This is a snapshot of the positions of all movable objects: trains, switches, and turntables.  You can save a rewind point to a file, play with the trains a while, then retrieve the file to put everything back the way it was.  These actions are done with the Save and Load buttons in the Advanced Scripting dialog.

A rewind point is saved automatically the first time you play or record a script.  It is carried around with the layout, and saved in the layout file.  This means you can save the layout with trains in random positions, and you will still be able to rewind to the initial point.

If you change your mind about the starting locations and want to move them around a little, use the Reset button in the Advanced Scripting dialog.  Reset erases the current saved rewind position, so the next time you begin to play or record, a new one is created.  Caution!  If you carelessly erase a rewind point and don't know where the trains need to go, you could render the script useless.

Advanced Scripting Dialog

Clicking the Advanced button in the Script Editor brings up a dialog of useful buttons and options for script authors.

• Train and switch positions:  click Save to save the current situation of all trains, switches, and turntables to a file in xml format.  Click Load to read and return to a saved situation.  This is handy when you need to return moving objects to where they were at some point in the script, without saving the entire layout.

• Toggle IDs of affected cars:  if the comments at the top of a script include any car ID's, then this button will toggle the display of ID's on those cars.  For example, in the block of comments entitled "Daily Ore Run on the Cerro Azul" (see screen shot at top of page), six cars are identified by their IDs -- click the Car IDs button to show or hide labels on those six cars.

• Reset starting positions:  click Reset to erase the rewind point associated with the layout, so that a new one will be created the next time you start the script.  This is an advanced feature, to be used with caution.  For details, see the section about Rewind Points.

• Save script to layout file:  click Update to save modifications you have made to scripts, but save no other aspects of the layout.  For more info, see notes.

• Show script announcement on opening layout:  display an alert when a scripted layout is opened.  This brings the alert back if you chose "do not show again" at some point in the past.

• Echo script comments in schedule window:  display in the schedule window all commented lines as the script runs.  This option can also be changed by right-clicking in the schedule window and choosing "show script."

• Use autopause in all playback:  act as if "autopause 2" has been inserted at the top of every script, generating 2-second pauses at stops, reverses, etc.

• Start/stop commands apply to selected script only:  if checked, clicking Play or Stop will affect only the script of the current train; if unchecked, will play or stop all scripts.

Notes

1. A situation file saves not only train positions, but also train and car properties.  If you change a property of a car or train -- say its name or label -- then restore a previously-saved situation file, your changes will be lost.

2. What the Save Script button does is take the current set of scripts and implant them into the layout file, replacing the previous set of scripts while leaving track, train, and other data intact.  This is useful during script development, when you want to save your text edits often, but not keep overwriting the layout file with trains in random positions.
    

Language Reference

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.

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.

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.