Working With Scripts

All scripts are blocks of text. The interesting part is what happens inside the text -- the commands, waits, logic. This page is not about that. Here we treat scripts as black boxes, describing how to create, access, and manage them.

Much of what you need to do with scripts can be done in Script Central. There you can create, delete, browse, view, and edit all types of script. The rest of what you need to do is described below on this page, according to script type.

All scripts except subroutines are layout dependent, and stored as text blocks within the layout file. When you modify a script in one of the script editors and click OK or Apply, the changes are saved in memory. They are not permanently saved to disk until you use File Save or File Save As to save the layout file.

Working with Train Scripts

A train script is attached to an engine. This is the original type of script dating back to TP 2.0. You might think of it as a little robot which sits in the cab and drives the train, following a prescribed list of instructions. A train script is normally used to direct a particular train through a series of operations, for example running its daily route, or performing a switching task.

Creating: select a train having an engine, then: (a) right-click any car and choose Train > Script > Edit from the context menu; (b) choose Train > Script > Edit from the main menu; or (c) click the Edit button on the Script Toolbar. All of these bring up the Script Editor, displaying the script attached to the train. If the train has no script, a new empty one is created.

When you create a script on a train, it becomes attached to the engine, and sticks with it during later couplings and uncouplings. If the train has more than one engine, the script attaches to the leading one -- the frontmost one in the current direction of travel. If the train is not moving, the position of the Forward/Reverse switch is consulted to see which direction it is heading.

Editing: select a train having a script, then proceed as for creating, above.

Note: To see which trains on the layout have scripts, look in the Train Tree (shown at right) or the Scripts tab of Script Central.

Deleting: use Script Central, or see note:

Note: Most scripts can be deleted by erasing. In a script edit window, right-click and choose Select All, then Delete (or press Ctrl-A, Del), then click OK or Apply to save the empty script. This will delete it and remove it from the script list.

Playing back: select a scripted train and: (a) choose Train > Script > Play from the context menu or main menu; (b) click the Play button on the Script Toolbar; or (c) open the Script Editor and click Play.

If there is more than one scripted train on the layout, clicking Play on the Script Toolbar starts them all. The other methods start only the script on the selected train.

If you have already been running a script, before you can start it again you will need to rewind it to the beginning. This will move trains back to their starting points, and will revert the layout to an earlier state, and may cause unexpected surprises. Read about the Rewind Point.

Recording: Script recording is a way to create and develop a script without doing any programming. It creates a train script based on your actions operating that train. It does not apply to junction actions or the master script, though you can create script code by recording which can be pasted into any type of script.

To create a recording:

Choose the train you want to record, and move it into a suitable starting position.
It is a good idea to set the Rewind Point to the current situation, so you can rewind back to here later. You can do this using Script Central, Settings tab.
Click the Record button on the Script Toolbar. The bulb lights in red, indicating that recording is now active.
Operate the train as usual. All operations using the train controls are recorded; most hand-drag operations are recorded also, except for speed changes.
When finished, click Stop on the toolbar. This terminates recording and saves the script.
To play back, click Rewind, then Play. Or bring up the Script Editor so you can follow along.

Disclaimers: recording isn't a perfect science, and may not capture all the action exactly as you expect. It is intended to capture simple action sequences, and to provide starting points for developing your own scripts.

Debugging: Once you have developed or recorded a script, and you are playing it back, something is likely to go wrong. Figuring out what's wrong and fixing it is not usually easy, and the program doesn't provide much in the way of tools to help you, but here are some suggestions:

1. Watch the script run. Bring up the Script Editor before starting the script, so you can see what line is being executed when the trains go awry.

This applies to train scripts. For a junction action, wait until a car or train crosses the junction to trigger the action, then bring up the Script Editor. (Warning: do not use rewind or replay when watching a junction action.)

2. Use Go To Statement. In the Script Editor, right-click a line of the script and choose Go To Statement from the context menu (shown at right). The script will position to that line and start execution there on the next Play. This gives you a way to run a part of the script over and over.

Warning! it is up to you to make sure the trains are in the right places to be starting at the indicated statement. Some statements are more suitable than others as starting points.

Working with Junction Actions

A junction action is attached to a junction, activated when a given car or train passes across it ("triggers" it). The trigger can a particular car or train, or any, or a particular type; for details, see Junction Action Editor.

When triggered, the script attaches itself to the crossing train and starts executing. Once it has carried out all its instructions, it stops and turns control back over to the train. You might think of a junction action as a robot sitting at a trackside location; when it sees the appropriate train come by, it climbs into the cab and takes over, runs until the end of the script, then climbs off and goes back to wait for the next one.

Creating: Creating a junction action requires TrackLayer. Using the Track or Edit tool, right-click a junction and choose Action... This brings up the Junction Action Editor, where you can define one or more actions to occur at the junction.

Once a junction action has been created at a junction, it is displayed with a little circle symbol, as shown at right. The symbol does not appear when the Run tool is active.

Editing: bring up the editor as above, or edit using Script Central.

Deleting: use Script Central, or see note.

Playing back: the script starts running when the triggering event occurs -- when the center of a specified car passes across the junction in a specified direction. The action script attaches itself to the crossing train, runs to completion, then detaches.

Notes regarding triggering of junction actions:

To prevent an action from triggering, mark it as disabled, using either Script Central or the Junction Action Editor.
By default, a junction action does not trigger when you drag a train across by hand, you must drive using the throttle. This behavior can be changed in the Settings tab of Script Central.
An action will not trigger if it is already running from a previous triggering. If one train starts an action, other trains crossing the junction are ignored until the action completes.

Working with the Master Script

The master script is a special script attached to a layout, designed to run automatically when the layout is opened. There is only one master script per layout. It can serve to initialize variables, provide information to the user, or start trains or scripts into action.

Creating: use Add Master Script on the context menu in Script Central, as shown at right. Brings up the Script Editor, creating a new empty master script. This command is dimmed if a master script is already defined for the layout.

Editing: edit the master script directly in Script Central, or launch the Script Editor from there.

Deleting: Use Script Central, or see note.

Playing back: by default, the master script starts automatically as soon as the layout is opened, and it runs to completion. You can prevent this from happening by disabling the master script, using the Enabled toggle on the context menu. If you want to rerun the master script, bring it up in the Script Editor, click Rewind, then Play.

Working with Subroutines

A subroutine is a named batch of code residing outside of any script, which can be called in and used when needed. That is, instead of having ten lines in a script to perform some action -- say reverse an engine using a turntable -- you could replace it with a single line calling a ten-line subroutine named something like "ReverseViaTurntable". Subroutines make for cleaner code, help organize complex tasks, and have other benefits.

A subroutine is stored in a text file, located in a special folder, the Scripts folder in your TrainPlayer data directory. If you build up a collection of these, you can browse and edit them in Script Central.

Creating: the program does not have a mechanism for creating a subroutine. Just use Notepad or other text editor, create a text file, and store it in the Scripts folder in your TP App Data directory. Any text file in this folder or its subfolders shows up in the Subroutines tab of Script Central.

The name you give the file becomes the command used to call the routine (minus the .txt extension). The name should be one word, no spaces (underscores ok) and should be descriptive of what the routine does.

Editing: you can edit a subroutine directly in Script Central, or right-click and choose Edit in Notepad. After you edit a subroutine and save its file, the changes will go into effect the next time the routine is called.

Deleting: you can delete a subroutine (a) using Script Central, or (b) by deleting the file using Windows Explorer.

Working with Procs

A proc (short for "procedure") is a subroutine not stored in its own file but embedded in a larger script. A proc statement in a script defines a block of statements and gives it a name; the end of the block is indicated by endproc. The thereafter, any script can call the proc by name to execute that block of statements.

Procs are typically defined inside the master script; they are recognized as soon as the layout is opened, and can be called by any scripts therein. Procs defined inside other scripts are not recognized until the containing script has been run once and the proc statement encountered.