PC-Rail Development Guide

PC-Rail Simulations - Development Guide

Updated 18/08/25 (changes in red)

This Guide is provided to assist new developers understand where to start and the main stages to work through. It will still be necessary to refer extensively to the full documentation at www.pcrail.co.uk/develop/DevGuide.htm.

To clarify the stages of development, please see the list of Development Stages.

Throughout your development, try to adhere to the principle that "Everything should be made as simple as possible, but not simpler." (Attributed to Einstein; a formulation of the principle of Occam's_Razor).

Planning (Stage 1a)

You should first ensure that you have a reasonable understanding of the Network and Signalling sections of the Logical Data Model. This explains the basic principles of the data design.
Initially you need only be concerned with the two most basic "entities", Node and Track. You should therefore read and understand:

the Data Definitions for the Node and Track data files. For now you can limit you attention to the fields with a value of 1 shown in the "Required" field.

the Network Shape page of the documentation, up to the end of the "Limitations" section.

It will probably also be helpful to look at the contents of the node and track data files in the sample data supplied with the PC-Rail Plus software.
You will almost certainly need to draw out your required layout on paper before beginning to set up any data for your new simulation. This is best done on squared paper. Note that your layout must consist only of straight track sections (no curves). See sample drawing.
Next you need to work out the row and col values for each node in your layout. If your layout has lines which "disappear" to the left of the layout, as most do, choose a suitable positive col value (e.g. 1000) to correspond to the left side of the required display. It is probably best to include signal nodes at this stage.
You can also decide the positions of other display items (platforms and text) at this stage, or leave this until later, in which case you should ensure that you leave enough space for them. As the PC-Rail Plus software can generate train describers for you, it is best to leave these for now.

Setting up the data

You are now ready to begin work on creating your simulation. You will be probably be using the PC-Rail Plus Builder software and should refer to the Help file which is provided for details on its main features. Even if you are creating your data without using PC-Rail Plus, you will find useful information in the Help file.

You should first use the New facility in PC-Rail Plus to set up your new project, as this takes care of creating a set of empty data files with the required formats. Then you can use the Edit option to open the software's Editor function which has many facilities for adding your data to these files, and editing it as required but you can, if you prefer, make use an external dbf file editor (e.g. CDBF) for doing this.

An option is also provided to import data which has been created in spreadsheet (xls) files using the XLS function. In this case you must ensure that the files to be imported have the correct columns, according to the documented Data Definitions.

It is recommended that you proceed as follows:

Stage 1b:

Set up the data for the Node and Track data files, using the information which you have already prepared.
Adjust the size of the layout display window by amending the values held in the Parameters data file, especially the values of c0 and lycols..
Set up the data for the Text data file, positioning the displayed text as appropriate.
When you are satisfied the layout is complete and you are satisfied with the display in the Edit window, run the Check facility to identify any errors needing correction. You should repeat this at each stage as you add further data.
Use the Editor's Generate facility to automatically generate data for:

Fringes and Yards (Node and Track data)
Train Describers

Make any required amendments to the positioning of signal and point labels and train describers.

Advice from our most experienced developer, Peter Dean:
It is not worthwhile spending all day entering data before you do a check - even in the initial stages, as you are bound to get lots of errors shown, some of which are real and others simply through non-entry of data. It will then take much longer to sort out what is wrong than it took to enter the data. It is much easier to do everything in small steps and get each step correct.

Stage 1c:

Create the data for other data files, referring to the relevant Data Definitions for each data file:-

Location data
Platform data
Line data

Enter data to the Track data file for the line field (relating to the records in the Line file) and the maxspeed field.
Use the Editor's Generate facility to automatically generate Track Circuit data. The track circuit numbers will be stored in tc field of the Track data file. Carefully review the results which are displayed - it may be necessary to add additonal 'T' type Nodes, or to remove others which are not needed.
When you are satistfied that no further changes will be needed to the Node and Track data, you can begin to set up the Route and Subroute data. Begin by using the Editor's Generate facility to automatically generate Auto routes. You will then need to enter the required data for all remaining routes - see the Data Definitions for further information. Make use of the Check facility to identify errors in your data.
When you are satisfied that all your Route and Subroute data is correct, you can proceed to complete the data which depends on it:

Generate route notes (stored in the rnote field of the Route data file), and further edit these as required.
Generate the Routeplan data.
If required, enter data to the Multiroute data file.

Enter the scaling data, i.e. the values of the scale field in the Track data file. This can be done at an earlier stage if you wish, but is one of the more time consuming tasks and no other data depends on it. Use of the Scaling data input facility of the Track Builder will minimise the time taken.
Write the User Information - see Appendix 1 below.
You have now essentially completed your simulation. Run a final Check of your data, and of course Save any final amendments.

Checking the simulation (Stage 1d)

Run the simulation from PC-Rail Plus main screen. It is almost certain that this will reveal many things that you will wish to adjust or correct, but you can repeat the process as many times as you wish.
Test the setting of all routes and the manual operation of all points.
Run the test timetable which was automatically generated when you created your simulation data. If errors occur, check and amend any of your data which might be causing the problem.
Create short timetable(s) for use in testing the simulation (this may be part of the full timetable to be included later) - see below.

Sharing your data (Stage 2 onwards)

Optional

You do not have to involve anyone else if the simulation is for your own use only, although it is always useful. If you wish others to help by with comments, suggestions, etc, or to involve them with the testing of your simulation, you will need to make your simulation data available to them. They will then be able to run the simulation through PC-Rail Plus.

See Appendix 2 below for details of how data is exchanged.

The following stages are not applicable to simulations developed for your own use only.

Simulation Testing and Debugging (Stage 3)

Once this stage is complete, the simulation is regarded as finished, subject only to minor changes which are found to be required during final testing.

Writing the Standard Timetable (Stage 4)

While running the simulation, use the Timetable Editor to set up the standard timetable for the simulation.
In most cases, the standard timetable for a simulation should contain at least 250-300 trains and should be for a weekday service.
For guidance notes, please see: Creating Timetables.pdf.
The timetable notes to accompany the timetable are an important aid to users.

Note: It is inadvisable to spend time writing the standard timetable before this stage, since any changes to the layout data (especially line and location data) may cause problems in running the simulation.

Timetable and Operation Testing (Stage 5)

The simulation is now complete and its operation needs to be extensively tested. Feedback is needed by the Developer to make any further changes required, which by this stage should be to the timetable only.

Review and full checking of complete simulation(Stage 6)

Although all signficant issues should have been resolved by now, full checking is required to identify any outstanding issues prior to release. In particular:

The completed simulation should be fully reviewed to identify any cosmetic issues with the layout display. Generally these can still be corrected without the need for a full re-test.
The user documentation (local info, timetable notes, etc) should all be checked to ensure that it provides the information a user will need, and that the documents are well formatted and free of errors.
If not previously carried out, perform a spell check on the documents - see below.

Appendix 1: Providing information for the simulation user

Information to help the user of the simulation is provided as follows:-

Local Information

The information contained in the Local Info file which is applicable generally whenever the simulation is used. For examples, please run existing PC-Rail simulations and click on the Window/Local Information menu option. The information provided will vary according to the nature of each simulation, but it is normal to include at least the following:

Introduction to the simulation location, with a broad description of signalling and operating arrangements, and optionally some history.
Details of any bidirectional working, permissive working, electrification, etc.
Defined stopping places for non-passenger trains
Platform capacities (also siding capacities where this is useful)
Train reporting numbers applicable to the area
Useful operating notes
Design compromises
Acknowledgements

This information may be contained in a plain text file, rhlocal.txt included in the simulation's simdata folder. However, to allow improved formatting, it can (optionally) be created as an RTF (Rich Text Format) file named rhlocal.rtf. If included, this file will be displayed when the user opens the Local Info window. It can be edited within the Builder software or you can edit it using your preferred word processing software.

You can edit the Local Info file by clicking on the (Edit Data) Other button in the Editor.

List of Routes

The details which the user sees when he clicks on Window/Routes is generated from the data in the route.dbf data file. The "Note" column is taken directly from the rnote field of route.dbf. Due to the limited width of this column, a standard set of abbreviations is used, as follows:

[A] = A-button provided
[1], [2], [3] = Preference order of alternative routes ( followed by the "required" point settings)
{} = Leading shunt signals which are preset for the route
[R] = Main route approach released from Red (similarly for other values of route.control which have been used)

The Editor software includes a facility to automatically generate some of these values for the rnote field, and the data can also be edited directly.

The abbreviations which are used need to be explained in the footnotes for the Available Routes screen. The text for these footnotes are contained in the file rtenotes.txt.

You can edit the rtenotes.txt file by clicking on the (Edit Data) Other button in the Data Editor.

Timetable Notes

This is text which supplements the Local Info and is applicable to one specific timetable (initially the "Standard Timetable").

* See: Creating Timetables.pdf

You can edit the Timetable Notes by clicking on the Properties button in the Timetable Editor. When the simulation is run, the timetable notes will be displayed as plain text.

Timetable Notes - RTF option - New

An additional option is available to provide the timetable notes as a rich-text format (RTF) file. The rtf file must be placed in the simulation folder along with the wtt files (not in the simdata folder). It must be named using the same convention as the other wtt files, e.g. wtt_notes_CJ01.rtf for model CJ, timetable 01.

In the Builder version of the software this RTF file can be included and then edited using the RTF Notes link in the Editor's Properties window. It will then be included (in accordance with the previous paragraph) when you update the simdata for the simulation and you choose to update the timetable files.

An RTF notes file can also be created for any extra timetables produced using the editor and will be included when you use Export.

Provision of an RTF file is optional, NOT required.

Formatting and spell-checking

All documents should of course be well formatted, and spell checked. Open the documents concerned in any good text editor or word processing software and run the spell check to identify possible errors. If necessary you can copy and paste the text you want to check into a blank document.

A spell check can be carried out on the individual train notes in the timetable as follows:

In the timetable editor, click on "Print" and select "Save to text file 2"
Click on "Open", and you will see the full list of train numbers and their notes ("words").
Either:
- Open the file wtt_text2.txt in a text editor which has a Spell Check facility (e.g. Word, TextPad)
Or:
- Click on "Copy" and then paste the text into your text editor
Run a Spell check. Many location names will be queried and you will need to use 'Add' or 'Ignore' a lot.
Make a note of the genuine errors and correct these in the editor.

This facility is only available in the Builder version of the software.

Appendix 2: Exchanging Data with Others

Sending simulation data (applies to the Developer of the simulation only)

All the data for your simulation is contained in the simdata zip file (e.g. zipfiles\Wimbledon_simdata.zip). It is this zip file which is exchanged with anyone you wish to share your simulation with.

When you Save your data in the Editor, the data in the zip file is updated. The latest version of the standard timetable will also be included in the zip file

Sending simulation data

Run the PC-Rail Plus Builder program (PCRail_Plus.exe).
Select your simulation on the simulation list
Click on the Simdata button
If you are the developer of the simulation you will be given the option to include an updated version of your timetable data.
A window will then open with your simdata zip file hightlighted.

You can email the zip file direct to selected individuals. If you wish it can also be uploaded to the pcrtest group, placing it in the Simulation testing folder in the Files section of the group. You should also notify group members by posting a message and inform us at PC-Rail so that the List of Current Projects can be updated.

Receiving simulation data

Download the zip file containing the simulation data
If posted to the pcrtest group, this will be found in the Files section of the group.
Make sure you have the latest version of PC-Rail Plus installed
(if not, download it from www.pcrail.co.uk/develop/files.htm - see also the installation instructions there, as well as the date of the latest update)
Run the PC-Rail Plus Builder program (PCRail_Plus.exe).
Click on the Import button.
Select the zip file to import (the one downloaded in [1] above).
Click on the Run button to run the simulation.

If updated versions of the data files are received, simply repeat the above steps.

Appendix 3: using your own image files for signals, etc.

A default set of image files is used for displaying signals and yard entrances. You can if you wish provide your own alternative image files, which should be placed in a subdirectory of your simulation directory, named bitmaps. Your image files must have the same name as the corresponding default files, i.e.:

Node Type	Node Subtype	Normal/ Reverse	Rundirec	Image file name	Notes
S	D	N	1	a_shuntsig.bmp
S	D	N	-1	a_shuntsig_rev.bmp
S	D	R	1	a_shuntsigc.bmp
S	D	R	-1	a_shuntsigc_rev.bmp
S	L	-	1	a_stopbrd.bmp
S	L	-	-1	a_stopbrd_rev.bmp
S	2/3/4	N	1	a_sigpost.bmp	Image is for signal post, with or without subsidiary aspect ("cats's eyes") cleared. The main aspects are generated in a different way.
S	2/3/4	N	-1	a_sigpost_rev.bmp
S	2/3/4	R	1	a_sigpostc.bmp
S	2/3/4	R	-1	a_sigpostc_rev.bmp
Y	-	-	1 *	a_yardleft.bmp	* = entrance direction
Y	-	-	-1 *	a_yardright.bmp	* = entrance direction
Alternatively you can specify a .gif image file, using the same stem name, e.g. a_shuntsig.gif
If you do not specify your own image file, the default file will be used (these have the same file name but without the leading "a_").

Images of your own which are used in the miscobj data file should also be placed in the bitmap subdirectory.

Appendix 4: using special characters in text objects

Open the Text data editing window in the PC-Rail Plus Editor
Add or edit a text record
Make sure you set the value of formatcode to "S".
Click on "Characters" to open the Windows Character Map window.
Cut and paster the required characters into the Text field.
(If further help needed, click on the Help button in the Character Map window).

Direction arrows:

A simplifed method is provided to show left and right arrows in the text data : if the text includes either << or >>, those characters will be displayed instead as arrows.

Appendix 5: including a start position for a timetable

Create the timetable in the Timetable Editor, including timetabling the arrival of the startup trains
Run the simulation and start a new session using the timetable
Save the position when the startup trains are in their required positions
Open the timetable again in the Editor
Open the Properties window
Click on the Start Posn checkbox, and then select the saved position which is to be used for the start position of the timetable.
Close the Properties window, Save the timetable and exit.
Select your simulation in the PC-Rail Plus Builder, click on the Simdata button then select the option to "Include your updated WTT data".

The simulation's simdata zip file will include the folder wtt_init, holding the files for the start position.

Note: If you make changes to the simulation (layout) data, you will need to re-create the start position, repeating the above procedure from step 2 onwards. It is therefore inadvisable to set up a start position before development stage D.

This procedure covers the inclusion of a start position in the standard timetable during the development phase. Users of the simulation can also create timetables with start positions - see the "Start Position" topic in the editor's Help.