Main Train ThingIntroductionCreate new WindowDisplay LabelsConfigure TrainsRepeat Similar RunsExecutionRun Train(s)End Train ThingUpdating LoopEnd RunABORTErrorsMust Select OneSelect Color OnceMore than you Want to Know

Stylized Train Thing


This software simulator of the Train Thing originated near the beginning of this project.  For a longer discussion of the genesis see the introduction in the Documentation.  The simulator is one of a SW developer's worst nightmares; A "one-time-use" or tool for personal use, that has a ribbon put on it and then given to the client.  The simulator was written for personal amusement, then developmental use, so the GUI is a little clunky in places.

Alongside many options is small icons Question icon - link to contextual help  Clicking on the icon will open this contextual help document to information about that option.

There is a simulator section in the Bulletin Board where you can make comments, suggestions or report errors.

Quick Start There will also be a screen shot video illustrating the following quick start procedure.

Semulator controls screen shot

Create new Window

Click this <Create Second Window> button first to open a second browser window filled with the simulator graphics of the Train Thing layout.  Adjust the size of the new window so it is fully visible.

Originally the thought was that with a second display attached to my PC the window with the graphics could be moved to the second screen freeing the laptop screen for the control screen and IDE (Integrated Development Environment) to write the software.

Display Labels

Label display control screen shot This section of the initialization screen lets you select which labels are displayed on the simulator graphics.  Many of the labels were originally displayed for development but they "clutter" the screen now.

You can check or un-check individual boxes at the top and then click <Update Labels Displayed>.  Or you can use the radio buttons at the bottom to select "All" or "None" of the labels, then click <Update Labels Displayed>.Changes will immediately take effect in the graphics display window.

Display options are retained until you <End Train Thing>.  Choices can be changed any time this screen is displayed.

Configure Trains

Assign train to path detail screen shot

This section of the Initialization screen is used to select which of four paths are followed by a train in a simulation run. You can select 1 to 4 paths: Small figure-8, Large figure-8, Small oval and/or Large oval.  Each path can be run in a Clockwise or Counter Clockwise direction by clicking the appropriate radio button.

To activate a path, select the color of the train you want to follow the path from the drop-down menu.  Use a color only once; Logically a train can only follow one path.  And of course, it does not make sense to run the simulator without selecting any trains/paths.

When you click <Run Trains> colored trains not selected here will magically be removed from the display.

By default, the "Single Run" radio button is selected.  In this mode, the colored trains you select will exit the 'Parking Lot' and follow the assigned path.  This should run forever or until you end the run by selecting <End Run> or <ABORT> on the next screen.

Select <End Run> and the trains will find their way back to the 'Parking Lot'.  <ABORT> will rudely stop the simulation run and place the trains back in their beginning locations.  In either case the initialize screen will again be displayed.

See <Repeat Similar Runs> for details of repeat runs.

Repeat Similar Runs

This was a last-minute addition for testing.  Select 1,2,3 or 4 paths/trains above for the simulation run; Select the <Repeat Similar Runs> radio button and the click <Run Train(s)>

  1. First the entered simulation configured will be run for a random number of steps. (out of the parking, random number of run steps, then back to the parking lot.)
  2. The simulator will randomly select the same number of paths, CW/CCW and randomly assign each path to colored trains.
  3. This new random simulation will be run for a random number of steps, as in step 1.
  4. Steps 2 and 3 will repeat until the simulator is stopped

During an "Run" the process can be stopped by clicking <End Run> or <ABORT>

This "feature" was added to help in testing.  Keeping in mind there are:

That is 632 tests to run.  Booooring.  So, I added random testing.

It may look like there are more runs using different colored trains.  However, the color of the train is looked at by the software only when getting back into the parking lot.  Obviously, the BLACK train must be parked first.  Otherwise the permutation of paths is accounted for in the numbers above.  

In the beginning the order of the paths appeared to be important.  If path "A" is assigned to BLACK (first) or GREEN (last) is different.  Anecdotally, both runs seem to fall into a pattern after executing in the 'Run' mode for a while.

Please record any different analysis on the Bulletin Board.


Run Train(s)

Options to start simulator screen shot When a simulation run has been configured, and <Single Run> (default) or <Repeat Similar Runs> have been selected click <Run Train(s)> to start the simulation.

Not selecting as least one "Train Color:" or selecting the same "Train Color:" more than once, will result in an error condition

End Train Thing

When you are ready to exit the simulator, there are two things you should do to cleanup your computer display and return to the Train Thing main menu (Part of the clunky GUI)

Updating Loop

This simulator has 8 states.  The current state is shown in the upper left corner of the display.

0.   Stopped

      1. Idle
      2. Parking Lot
      3. Transition
      4. Interim
      5. Run
      6. End
      7. Wrap It Up

0.  The "Stopped" simulator state is entered when the simulator is started, or after the <ABORT> or <End Run> buttons are clicked.  See the Introduction for option available in the "Stopped" state.  After configuring a simulator run, clicking <Run Train(s)> will change the simulator to the "Parking Lot" state (2).

1.  The "Idle" state is entered from the "Rap It Up" state (7) when the <Repeat Runs> was selected and the random number of run steps was completed in state "Run" (5).  The next simulator run is configured similarly to the one selected in state "Stopped" (0).  The same number of paths are randomly selected and assigned to a randomly selected colored train.  A random number of steps, between n and m, are selected for the "Run" state. When configured the state is changed to "Parking Lot".

2.  In the "Parking Lot" state each train is moved along a transitional rout to move the train from its parking place to its assigned or interim rout.  When all trains are out of the "parking lot" block 14 of the track is available and the simulator goes to the "Transition" state.

3.  The "Transition" state continues moving the trains along their transitional rout until all trains are looping on their assigned or interim rout.  Then the simulator is advanced to state "Interim".

4.  In the "Interim" state trains assigned to routs on the large oval are moved from their interim looping routs to their final assigned routs.  This additional step for trains running on the large oval are to keep those trains out of the parking lot or from blocking other trains from exiting the parking lot.  To do this the one or two trains assigned to the large oval are given a transitional rout to an interim path of a CW large figure-8.  A one or two step process is used to migrate these trains for CW large figure-8s to their original path on the large oval.  When this process is completed, the simulator is advanced to the "Run" state.

5.  In the "Run" state each train follows its assigned endless loop until one of three events occur:

6.  The "End" state is a 12-step process to move all trains from their assigned loop to a CCW Large figure-8 path.   (If this had not turned out to be a 12-step process, I would have made it so.)

       When all trains are looping a CCW large figure-8, the state is changed to "Rap It Up"

7.  In "Wrap It Up" state ("End" state step 13) as each train loops past the entrance to the parking lot, it's check to see if it can be parked.  When all trains are parked, the simulator goes to the "Idle" state (1) if the <Repeat Runs> option was selected, in (0), and the random number of run steps were completed.  Otherwise, the <End Run> button was clicked and the simulator returns to the "Stopped" state (0),

End Run

When the simulator is in the "Run" state the <End Run> button is visible.  Clicking <End Run> will change the simulator from the "Run" state to the "End" state.  The "End" state is a 12-step process to move the locos back to the parking lot in an orderly process adaptable to any of the up to 698,880 possible simulator states when the button was clicked. When all locos are parked in order, the simulator displays to the "Initialization" screen and the "Stopped" state.


The <ABORT> option is always visible during updating loop operation.  Clicking <ABORT> will rudely end the updating operating loop and return the simulator to the initialization screen/ state.  Keep in mind that there are two programs/scripts running; the update script and the display script.  Clicking <ABORT> will not be detected / take effect except while the update script is running, so click the button "slowly" or it may not be effective.


Must Select One

Cause of error screen shot

To generate this error, you have clicked <Run Trains> without selecting any "Train" colors first.  

Error message screen shot

The error was detected when no trains were found to update.  click <Return> to go back to the Initialization screen to correct configure a simulation run.

Reminder of error screen shot

Returning to the Initialization screen there is a reminder of your previous error.

By selecting at least one color for a path before clicking <Run Trains> will avoid this error

Select Color Once

Example of error screen shotThe screen shot at left shows an example of how this error could be generated, the "Train Color" for two paths is the same.

Error message screen shotWhen <Run Trains> is clicked, the error is detected and the simulator is stopped.

Clicking <Return> will return to the Initialization screen where a correct simulation can be configured.

Reminder of error screen shotReturning to the Initialization screen there is a reminder of your previous error.

By selecting a color only once before clicking <Run Trains> will avoid this error

More than you Want to Know

Simulator status screen shot

While the simulator is in the "Updating Loop" several lines of data are displayed.  This information was uses during development and troubleshooting.  There are two types of information:

System Status   The top line of data includes four data:

1.  First the System State, in the case at left 2, 'Parking Lot", The System states 0-7 are described in Updating Loop.

2.  Second System Sub-state, here "00" by default. How the sub-state is used depends on the state of the simulator.

3.  Next is a flag identifying whether the run state will be stopped manually.  By default, the flag is TRUE. If the <Repeat Run> option was selected the flag would be FALSE and the number of trains in this run would be set.  If <Repeat Runs> was selected and during the Run state the <End Run> button was clicked this would set to TRUE. The System State would be set to End.  When all trains are parked, this flag is used to go to the Stopped or Idle state.

4.  This is 0 by default.  If <Repeat Run> was selected, this would be set to the number of trains in this simulation run.

Train State For each train running in the simulation two, or three, lines of status are displayed,  First is a dump of the state of the train before update starts; A line showing the track block the train is on, next block and 2 blocks out;  A Third line is displayed if the train is blocked.

Train State:  The state of each train is maintained in an array indexed 0-3.  Train 0 runs the small figure-8 path, train 1 large figure-8, train 2 small oval and train 3 large oval.  If a selected a color is assigned with a direction.

Coming path:  Where the train is going.  The next two blocks on the train's path are looked at to see if the train can proceed to the next block or if the train's path is blocked.  As shown above for the BLACK train which is moving within a block, the current and next blocks are the same.

If the train is blocked, a line with the reason is displayed. In the example above, train 2 is blocked for reason #1,

  1. The next block is occupied.
  2. The block after next is occupied and the train is headed towards the current train.  Whether the second block is occupied is important when approaching the ends of the layout where two blocks are adjacent
  3. The crossover in the middle is blocked by a train crossing the other way.
  4. Switches needed by the train are in use by another train.