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 Arlington in action.

Included with the release is the Arlington RR (filename arlington_s.rrw).  This layout has a set of scripts which automatically run the Local along its route. At each stop, a Junction Action takes control of the train, pulls it into the station, waits while passengers exchange, then pulls it out again and turns it back over to the main script.

Instructions for running the demo:

1. Open Layouts\Scripts and Puzzles\Scripting examples\Arlington RR in the Layout Chooser.
2. Use Tools > Schedule to bring up the window which shows script text output.  Right-click and make sure Show Script Output is checked.
3. Open Script Central using the button on the Script toolbar.  This dialog shows the scripts and junction actions on the layout, and a page of notes.  Browse around if interested.
4. Double-click Script 1 in the Scripts tab.  This opens the train script in the Script Editor.  This dialog highlight script lines as they execute, to give you a dynamic picture of what the script is doing.  (Note that it follows only the main train script, not the junction actions.)
5. Arrange windows on the screen so you can see all.  (If tight for space, close Script Central.)
6. When ready, click on the toolbar: Stop All (if not dimmed), Rewind All (just to be sure), then Start All.  Then sit back and watch.

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!

3. Click OK.  This saves the action to the layout (but not yet to the disk until you save the layout).
4. Bring up the Schedule Window so you can see the output.
5. 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.  
6. 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.

4. Click Apply to save the code. 
5. In the Script Editor, click Rewind.  This highlights the first line of the script, and moves the train to its starting position if necessary.
6. 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.