How To Get Started

There is a lot of material to be covered on the subject of scripting.  Here is a suggested recipe for easing your way into it.

1.  Watch the L27S in action.

Included with the latest release is the Scripted Tremont & Cambridge RR (filename L27s.rrw).  This layout has a single passenger train which makes regular rounds, stopping at several stations along the way.  The train is driven by a train script.  When it reaches each scheduled stop, a junction action at that location kicks in and takes over the train -- parks it in the station, waits for a change of passengers, then moves back out onto the mainline, where the train script again takes control.

In addition to demonstrating train and junction scripts, the L27s has a master script, which does nothing but put a message on the status bar, and illustrate the concept.

Here's how to get the most out of the L27s demo:

  1. Open the layout from the Layouts101 folder in the Layout Chooser.
  2. Use View > Windows > Schedule Window to bring up the window which shows script text output.  Right-click and make sure Show Script Output is checked.
  3. View > Windows > Script Central.  This tabbed dialog shows all the scripts connected to the layout.  Take a minute to browse through and look at them.  If you have plenty of screen space, you should leave Script Central up while you watch the action; if not, take it down after the next step.
  4. Double-click Script 1 in the Scripts tab.  This opens the train script in the Script Editor.  This dialog has the feature that it shows highlights as script lines execute, to give you a dynamic picture of what the script is doing.
  5. Use View > Toolbars > Script Toolbar if necessary.
  6. Position all these windows so they don't obscure the layout too much (good luck), then
  7. Click the Play button on the toolbar.

The train starts to move and so does the script.  Script comments and messages are echoed to the schedule window to keep you informed as the scripts run.  With luck, the train will run all the way around the layout, making three stops, then wait a bit and start over.  And you will have gotten a reasonable idea of what a script can do.

2.  Record a script.

You can create a script without doing any programming or having any knowledge of the script language: just press Record, and let the program generate a script as you operate the train; change speed, throw switches, reverse, uncouple -- every action generates the corresponding script language.  Press Stop when done, and there you have a script you can rewind, replay, save, and study.  If you have the Script Editor up while recording, you can see the script as it gets created. 

It is just that easy to record a script, but here are a few disclaimers.  First, when you replay a recorded script, it may not exactly reproduce your sequence of actions.  You have to cut it some slack as it tries to convert mouse moves into script commands.  Second, the result is not optimized for readability.  For example, varying the train speed while recording often generates a pile of speed-change commands, where in a hand-made script, only a single speed command is needed to do the job.

If you are not the programmer type, you don't need to go beyond this step.  Use script recording to capture the action on your layout, then play it back, or send it to another TP user to play back.

3.  Write a Junction Action.

The low-barrier way to write your first script is to right-click a track junction and create a little action there -- say a one-line script to announce something in the output window.  Bring a car up next to the junction, roll it across, and the action executes.  Do this a time or two and you might find yourself wanting to make fancier actions.

The procedure:

  1. Choose a convenient junction or switch; use the Track or Edit tool, right-click and choose Action...
  2. In the Junction Action Editor, you can choose a triggering device, or leave the default Any Train, then click in the text box to enter your script.  You might start with something like this:   

echo Crossing the junction!

  1. Click OK.  This saves the action to the layout (but not yet to the disk until you save the layout).
  2. Bring up the Schedule Window so you can see the output.
  3. Run a car across the junction, using the throttle.  As soon as the center of an eligible car crosses (in this case the first car of any train), the action should trigger and show the message.  
  4. Go hog wild.  Look at the Reference window in Script Central to get an idea what commands you can use, type one into the text box, run your car across and see what happens.

4.  Write a Train Script

Writing a train script is no harder than writing a junction action, but it involves an additional complexity or two.

The procedure:

  1. Select the train you want to drive and move it into a starting position.  The script will begin running the train from this position.
  2. Right-click any car and choose Train > Script > Edit.  Either that or click the Edit button on the Script Toolbar.  Either way you get the Script Editor, showing a blank script with a machine-generated header.
  3. Type some commands into the text box.  The most reasonable way to start is to give the train some speed and throw some switches to direct its route.  Your code might look like:

speed 20
throw J36 1
at J37 stop

except yours will of course have appropriate junction numbers for your layout.

  1. Click Apply to save the code. 
  2. In the Script Editor, click Rewind.  This highlights the first line of the script, and moves the train to its starting position if necessary.
  3. Click Play.  Off goes your train, until it gets to the destination, then it stops.

A couple of shortcuts:

  1. When the Script Editor is up on the screen, and the cursor is positioned at the next line in the text box, right-click a junction on the layout and you get a little menu of commands: Insert Throw Here, In...  The first adds a Throw statement which causes the switch to go to its current position, ...
  2. You can copy code to the Windows Clipboard and paste it into the Script Editor.  In case you prefer to do your editing in Notepad or elsewhere.

5.  Join the Scripters' Forum

You will surely come up with questions.  The best place to go for answers is our panel of experts.

6.  Become an expert.

Script your layout, or do one of ours, send us the result and we'll post it for others to enjoy.  To inquire, send e-mail.