IntroductionCreate New WindowDisplay LabelsConfigure TrainsRepeat Similar RunsRun Train(s)End TrainThingUpdating LoopEnd RunABORTIdleStartingTransitionRunReturnParkingErrorsMust Select OneSelect Color OnceMore than you Want to KnowDirection of Path


This software simulation of the Train Thing originated near the beginning of this project. For a longer discussion of the genesis see the introduction in the Documentation tab of the main menu. The simulator is one of a software 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 (Graphical User Interface) is a little clunky in places.

Depending on your browser when you hold your mouse over any of the options or help icons, a one-line window will open with a short explanation of that option.

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

There is a Simulator Section on the Bulletin Board where, registered visitors, can ask questions, make comments, suggestions or report errors regarding the simulator.

Quick Start On the simulator drop-down menu, there is a screenshot video illustrating the following quick start procedure.

Semulator controls screen shot

Create New Window

Open second window. Screen ShotAfter reducing the width of your browser window, click this <Create Second Window> button to open a second browser window filled with the graphics of the Train Thing layout. Adjust the size of the new window so both windows are 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.

Two windows open. Screen Shot

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.

With the radio button "Select Above" selected, you can check or un-check individual boxes at the top and then click <Update Labels Displayed>. Alternatively, 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.

Note: The signal labels will not be displayed if the "Display Signals" is not also selected.

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

Configure Trains

Assign train to path detail screen shot

There are two ways to configure which of the four paths are followed by trains during a simulation run.

When you click <Run Train(s)> colored trains not selected here will be magically 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 parking locations. In either case the Initialize State 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 then click <Run Train(s)>.

  1. First the entered simulation configured will be run for a random number of steps (out of the parking lot, 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. This will repeat until the simulator is stopped.

During a "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, due to the choke point exiting the parking lot into CW figure-eight paths, the order determined by the color of the trains is lost. The color of the train is looked at by the software only when getting back into the parking lot. Obviously, the RED 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 RED (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 Simulator forum of the Bulletin Board.

Run Train(s)

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 at least one "Train Color" or selecting the same "Train Color" more than once will result in an error condition.

End TrainThing

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

Updating Loop

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

0.        Stopped

1.        Idle

2.        Starting

3.        Transition

4.        Run

5.        Return

6.        Parking

In system states 2, 3, 5 & 6 temporary paths are followed by a train to move from the parking lot, to their assigned path and from their assigned path back to the parking lot. A train is switched from its current path to its next path when the next two sections of track in the current path match two sections of track in the next path. 

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 options available in the "Stopped" state. After configuring a simulator run in the Initialization window, clicking <Run Train(s)> will change the simulator to the "Starting" state (2) below and start the Updating Loop program.

1.  The "Idle" state is entered from the "Parking" state (6) when <Repeat Runs> was selected, the random number of run steps were completed in "Run" state (4) and all trains are parked in state 6. The next simulator run is configured similarly to the one selected in "Stopped" state (0). The same number of paths are randomly selected, direction randomly assigned and assigned to a randomly selected colored trains. A random number of steps, between 5 and 20, are selected for the "Run" state. When configured, the state is changed to "Starting" (2). See "Idle" for details of this process. 

2.  In the "Starting" state each train is moved along a path to exit the parking lot and enter a large CW figure-eight loop. If the train's assigned path is a small oval or small figure-eight, at the appropriate time the train then switches from a large to a small CW figure-eight path. Trains assigned to a large path follow a large CW figure-eight path until the parking lot is empty. This avoids a train running into back of the parking lot or blocking the exit from the parking lot. (Ok so this can't happen in the simulator. But remember this tool is a prologue to a hardware implementation.) When all trains are out of the "parking lot" all tracks are available and the simulator goes to the "Transition" state (3). See "Starting" for details of this state.

3.  In the "Transition" state trains are switched from CW figure-eight paths given in state (2) to the path assigned in the "Stopped" or initialization state. This may be a two-step process depending on the final direction assigned. When all trains are following their assigned path, in the desired direction the simulator advances to "Run" state (4). Step wise details are in "Transition".

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

For details of which train goes when see "Run".

5.  In the "Return" state each train is moved from their assigned path to a large or small CCW figure-eight depending on their assigned level. Depending on the assigned direction this may be a two-step process. When all trains are following a CCW figure-eight, the state is changed to "Parking" (6). Details of this state can be seen at "Return".

6.  In the "Parking" state each train is moved, in order, from the temporary CCW figure-eight path into the right-hand end of the parking lot. If all four trains are in use, the RED train is first moved to a large figure-eight path and then into the parking lot. This avoids congestion in the large figure-eight path. When there are three or fewer trains to be parked, all trains are moved to a large figure-eight and in order moved into the parking lot. When all the trains are parked the simulator does one of two things: 

This process is detailed in the "Parking" section.

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 "Return" state 5. In preparation for parking the trains. Trains running small oval or figure-eight will move to a small CCW figure-eight. Similarly trains running a large oval or figure-eight will move to a large CCW figure-eight.

When all trains are following a CCW figure-eight, the simulator will change to the "Parking" state and move the trains, in order, to the parking lot. When all trains are parked, the simulator will return to the initialization or "Stopped" state ready to run another simulation or exit.


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 or "Stopped" state. Keep in mind that there are two programs running: the update program and the display graphic program. 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.


The idle state (1) was added to the simulator options to assist in testing all the combinations of paths and number of trains.

From the initialization screen, the "Stopped" state, the update loop is entered in the "Starting" state as normal. The "Run" state is reached as normal. However, in the "Run" state, a predetermined number steps are executed and the state automatically advances to the "Return" state as if the <End Run> button was pressed. When all the trains are parked in the "Parking" state, the simulator comes to this "Idle" state instead of returning to the initialization screen/"Stopped" state.

Each run in the <Similar Runs> mode have the same number of trains as configured on the initialization screen. Each new configuration is randomly selected effectively using two 'hats'. One hat contains the 4 train colors. The second hat contains tokens for the 4 paths, small and large figure-eights, small and large ovals.

A path is selected from one hat and a color from the other. Then a 'coin' is flipped to assign CW or CCW direction to the train path. This process is repeated until the required number of trains have been configured. A new random number of run steps is selected for the next simulation. All simulator status data elements are updated, the simulator state is advanced to the "Starting" state and the new simulator is run as described above.

This process is repeated until the <ABORT> or <End Run> buttons are pressed.


After a simulation run is configured either in the stopped state or the idle state, running the simulation begins here.

Each train is assigned two initial paths:

  1. A short CW path including the 4 blocks of track in the parking lot and the 2 blocks of track at the left end of the large figure-eight.
  2. A large CW figure-eight path.

All trains are cycled through and moved forward if it can within the rules. A train may move forward within the current block or move to the next block in its currently assigned path.

Moving within the current block.

Each control block of track has 5 locations representing moving along the block of track. The train can be located at either end of the block, on one of the two IR sensors represented by the black dots on the track, or between the two IR sensors. The exceptions to this are the 4 short "parking places" which have only 1 IR sensor, the only place a train can be located.

A train enters a control block at one end, moved to the first IR sensor, then between the two IR sensors, to the second IR sensor. Sense the end of the current block is the same location at the beginning of the next block the rules for changing blocks are checked (below) and if the rules are met the train moves to the beginning of the next block. Within the parking lot trains move from the IR sensor in the current block to the IR sensor in the next block if the block is not occupied.

Moving to the next block.

There are only two rules controlling whether a train can move forward to the next block in its current path.

  1. A train can move to the next block if:
  1. If the train is entering the two curved blocks of track at the left or right end of the display or entering the "X" in the middle of the display a train can move to the next block if:

If a train can move the current block of track is turned on and displayed in green. If the train is moving to a new block, logically we don't know where the train is between the last IR sensor on the current block and the first IR sensor on the next block. So both the current and next block are turned on and displayed in green. If the train is blocked this is indicated by displaying the current block in red.

Change to next path.

When two paths are assigned to a train, a current path and a next path, each time a train is cleared to change block a check is made if the train can change paths. The train changes paths when:

For example, in the "Starting" state each train starts with two paths assigned, see above. As a train is ready to exit the parking lot the next two blocks in its path match two blocks in the large CW figure-eight, so its current path is switched to the large CW figure-eight.

Add a next path

At this same time a check is made if another next path needs to be assigned. In the starting state, if a train was initially assigned either a small figure-eight or a small oval, as soon as the train is out of the parking lot, a small CW figure-eight path is assigned as the next path.

When all configured trains are out of the parking lot, the state is advanced to the Transition state (3).


In the transition state trains are moved from the large or small CW figure-eight path assigned in the starting state (2) to the path assigned during the stopped (0) or idle (1) state.

Following the rules for changing paths, a train can switch from a CW figure-eight to either a CW or CCW oval. And from an oval back to a CCW figure-eight. In this way all trains are moved to the final assigned path and are ready for the Run state (4).

If there are two trains on a given level, large or small, and the figure-eight train needs to run CCW care must be taken that when both trains are switched to the oval path that they are going in the same direction.

As soon as all trains are following their configured path in the desired direction the simulator state is advanced to the Run state (4).


As soon as the Run state is entered the <End Run> button is displayed along with the <ABORT> button.

In the Run State all trains are following the path and direction assigned by the user in the Stopped State (0) or randomly in the Idle state (1). 

All trains continue looping around the assigned path until one of the two buttons are pressed or if in the "Repeat Run" mode the specified number of steps have been completed. When the steps are completed in the "Repeat Runs" mode or the <End Run> button is pressed the simulator advances to the Return state (5). As in all states pressing the <ABORT> button stops the simulator and returns to the initialization screen.


In the return state, all trains are moved to a CCW figure-eight path in preparation for moving into the parking lot. The return state's function mirrors the function of the Transition state, migrating each train from their assigned path and direction to a CCW figure-eight.

As in the Transition state a CW figure-eight train, if present, can be changed to either a CW or CCW oval. Trains following an oval path can be changed to a CCW figure-eight following the rules defined earlier.

When all trains are following a CCW figure-eight path the simulator advances to the parking state (6).


In the Parking state, each train is moved, in order, from their current CCW figure-eight path into the right-hand end of the parking lot and stopped in their assigned parking place. When all trains are parked one of two actions is taken:

The steps to move all trains from their current large or small figure-eight to the parking space are:

  1. If four trains are running in the simulation the red train is:
  1. When there are three or fewer trains to be parked, move any train following a small CCW figure-eight path to a large CCW figure-eight path.
  2. In color order, red, orange, yellow & green, move trains from a large CCW path to the short ending path to park the train.

Steps 2 and 3 can be followed at the same time depending on the color and location of each train.

When all trains are parked the simulator goes to the Stopped or Idle state as described above.


There are only two user input errors that are detected:

Must Select One

Cause of error screen shot

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

A simulation running no trains doesn't make much sense.

The error was detected when no trains were found to update. 

Reminder of error screen shot

By selecting at least one color for a path before clicking <Run Train(s)> will avoid this error.

Select Color Once

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

When <Run Train(s)> is clicked, the error is detected and the simulator is stopped.

Obviously a train cannot follow two paths.

Reminder of error screen shot

By selecting a color only once before clicking <Run Train(s)> will avoid this error.

More than you Want to Know

I know I need to write some words for here.

Direction of Path

For the figure-eight paths, CW and CCW are defined on the left end of the figure.

Clockwise figure eight defined.