PC-Rail Simulations - Development Guide

Updated 14/04/22

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)

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:

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:

Checking the simulation (Stage 1d)

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)

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 needs to be extensively tested. Feedback is needed by the Developer to make any further changes required.

Final Testing (Stage 6)

Although all signficant issues should have been resolved by now, full re-testing is required to identify any outstanding issues prior to release. Also it is not too late to make suggestions for cosmetic improvements to the layout display, etc.

 


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. This information is contained in the simple text file, rhlocal.txt. 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:

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

To allow improved formatting, the Local Info file can be created as an RTF (Rich Text Format) file. It will be named rhlocal.rtf and included in the simulation's simdata folder. This will be used instead of the normal rhlocal.txt file 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.

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:

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: http://www.pcrailservices.co.uk/create.htm

You can edit the Timetable Notes by clicking on the Properties button in the Timetable Editor.


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

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

  1. 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.
  2. 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)
  3. Run the PC-Rail Plus  program (PCRail_Plus.exe).
  4. Click on the Import button.
  5. Select the zip file to import (the one downloaded in [1] above).
  6. 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

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

  


Appendix 5: including a start position for a timetable

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