Coals to Newcastle

INC Files.. For Beginners

Aim - to users with an understanding of how to use INC files in the configuration of stock for Open Rails. Based upon information by Sanjay Das.

If you wish to provide any feedback on this page, please use the contact page. It would be great to have some feedback as this helps to ensure the accuracy of the information and models.

Index

Introduction to Open Rails Include Files

Advantages of using Include Files

Challenges with using Include Files

The Include Statement

INC File Content Principles

File Naming Principles

Multiple Call INC Files for Rolling Stock

Single Call INC Files.

Example Aplications.

Introduction to Open Rails Include Files

Include (INC) files in Open Rails are files whose content is copied into a configuration file using an "Include" statement.

Open Rails uses configuration files with user-configurable parameters that define the appearance and behavior of rolling stock (.eng and .wag files), routes (.trk), environment (.env), sound management (.sms) and other objects used in the simulator.

INC files are used to eliminate duplicate code, which may use up many megabytes of disk space in no time at all. For instance rolling stock WAG and ENG configuration files often have groups of parameters with the same values across multiple files. The Include statement makes it possible to maintain these common parameters in a single INC file that can be changed once, and used by multiple configuration files. This method uses an Include statement that looks like this: Include (filepath/filename).

There are a couple of different ways to use the Include statement and these are as follows:

Multiple INC File Calls - in this method the original configuration file (WAG, ENG, etc) is modified to allow the use of multiple Include statements to call various sub-configuration files for different components.

Single INC File Call - in this method the original configuration file is not altered, but instead a single INC file is used to over write or replace various parameters from the original file. This method can also be used when running both the ORTS and MSTS simulators on the same route and rolling stock folders, as it preserves the original file for use by MSTS. This is described below in section "Single Call INC Files.".

top

Advantages of using Include Files

Easier and faster maintenance of parameters and roll-out of common changes. Updating one INC file saves a lot of time compared to updating each individual configuration file.
Lower the risk of making mistakes. Duplication of code across multiple files increases the risk of unintended differences. Using INC files ensures that parameter definitions are the same across all configuration files.
Concentrating common parameters in INC files saves some disk space.

top

Challenges with using Include Files

There are few restrictions on how to organize the content of INC files and where the files are stored on a user's harddrive. This can make maintaining and debugging configuration files a daunting task. Imagine having to dig through multiple configuration and INC files to find the specific parameter you are looking for.

To overcome above mentioned challenges with INC files, and to make it easier to share INC files with other developers and users, a set of principles are proposed on this webpage, that will ensure a consistent structure and format across developers of INC files. These principles are supported by examples of using and organizing INC files.

Given the many years of history that OR has, content developers have used a number of different approaches to structure INC files. The following suggested principles are provided on the basis of trying to bring some order to the file structure and layout of users OR environment. Some existing stock distributions may require editing to fit within the suggested principles. These changes will be at the discretion of the content developer.

top

The Include Statement

The syntax of the Include statement is:

Include (filepath/filename)

The Open Rails simulator reads the parameter declarations in configuration files from top to bottom. The common parameters defined in an INC file will be inserted into for instance WAG or ENG files at the location of the Include statement. The example below shows how the simulator reads the configuration parameter file with an Include statement.

If the same parameter is declared multiple times in an WAG or ENG file, only the last one will be used by ORTS. This also applies to parameters that are defined in INC files. Thus a parameter defined in an INC file will be replaced by defining that same parameter after the Include statement, and vice versa, a parameter that is defined before the Include statement will be replaced when the INC file re-defines that same parameter.

The filepath in the Include statement can be specified by either providing the full path name to the INC file (absolute file path), or a file path relative to the folder that contains the WAG or ENG file that is calling the INC file.

Examples of relative file paths:

the INC file is located within the same subfolder as the WAG or ENG: Include ( "filename.inc" )
INC file is located in a subfolder of the folder that contains the WAG or ENG files: Include ( "/filepath/filename.inc" )
the INC file and the WAG or ENG file are in different subfolders of, for instance the Trainset folder: Include ( "../subfoldername/filename.inc" )

The double dot ".." steps back (or up) one folder level relative to the folder with the WAG or ENG file.

top

INC File Content Principles

INC files should only be used where duplication of multiple parameters will be eliminated, for example where all the cars in a train use the same brake system, then the brake system can be defined as an INC file. Like the WAG or ENG files that are discussed on the File Format and Layout page, INC files should be formatted consistently for ease of readability and finding relevant parameters.
The first line of the INC file MUST be left blank!
Do NOT` include the SIMISA@@@@@@@@@@JINX0D0t______ header that appears at the top of every WAG or ENG file.
It is recommended to insert a comment at the top of the INC file with the correct Include statement to that particular file. The statement can then simply be copied and pasted into the appropriate WAG or ENG file. Comment ( Include ( filepath/filename ) )
To avoid issues with the rolling stock simulation, please double check that all relevant data has been added to the INC file and the WAG or ENG files.
Make sure that all file contents and comments are clearly written to ensure readability for yourself and others.
Try and keep the number of folder levels down to as few as possible, aim for no more then 2 levels, if possible. This will make it easier for users to check and read files.

top

File Naming Principles

INC files should have a naming convention that includes, as a minimum, a reference to the equipment type, for example, TripleValve, etc, equipment model, for example, AB and the region or standards that the equipment is used in, for example, us, aar, en, uic, etc. This will make it easier for various content developers to find and identify reusable equipment components that they can use in their stock.

Although INC files can be given any name, it is recommended to use ".inc" as file extension to make them easy to recognize and distinguish them from other files.

top

Multiple Call INC Files

This paragraph provides guidelines for organizing INC files in a folder structure. Typically this method can be used to configure rolling stock.

For the purpose of organizing INC files used in WAG and ENG, two main groups of identical parameters can be distinguished:

Universal (or Global) INC files, contain standardized parameters for equipment used by all locos and rolling stock, for example common braking equipment, couplers, etc.
Class-specific INC files, which contain data that is common to a specific class of equipment. Some examples might include a class of identical locomotives or wagons with different road numbers, or load configurations.

The INC files that contain Global or Class parameters should be stored in their own folders, to make finding them easier. The following examples of organizing Global and Class specific INC files is just one way of organizing them. Depending on your locomotive and rolling stock fleet, there may be additional INC files and folders that you will want to create for other standardized parameters, whether they're universal or class-specific.

Universal (or Global) INC files should be stored under the main Trainset folder, in a folder similar to Common.Sound and Common.Cab alias folders. In the example below, the folders are named according to the common parameter class (brakes, couplers, etc.):

Since most ORTS users likes to run different types of equipment from different regions of the world, these folders can be further subdivided into individual subfolders for each continent/country/region

Class-specific INC files should be stored directly under the main Rolling_Stock_Class folder, in a folder with an appropriate name.

When multiple locomotives within the same class - e. g.: several 4-6-2 type steam locomotives with different road numbers or other details - are stored in one class-specific subfolder within the Trainset folder, than the INC files are stored in an additional Include subfolder, such as:

../TRAINS/TRAINSET/Indian_Valley_4-6-2/Include/

If a class or rolling stock shares a folder with several other classes, then each class gets their own Include subfolder:

../TRAINS/TRAINSET/Indian_Valley_Steam/Include_4-6-2/
../TRAINS/TRAINSET/Indian_Valley_Steam/Include_2-8-0/

An Include subfolder and INC file is not needed for "discrete" locomotives or cars that only need a single WAG or ENG file with configuration parameters.

See the Example Applications for examples of this type of application.

top

Single Call INC Files.

This method allows the user to keep the original configuration file unchanged and add additional information by adding an Include statement. As one type of example, users who still use MSTS beside ORTS, there is a way to reuse the MSTS files in ORTS, and run both ORTS and MSTS interchangeably on the same route and rolling stock folder structure. There may also be other valid reasons to add certain parameters across several routes with a series of INC file without changing the original route or stock files.

To implement INC files using this method, all INC files must be stored in a subfolder called OpenRails, located within the same folder where the file that needs the parameters added to it is located.

Within the OpenRails folder create an INC file with the same name as the file that you wish to add the parameters to. The include statement will look something like this:

Include ( ../au_great_zig_zag.trk )
Remember that the first line in this file must be blank.

When migrating large numbers of files, such as rolling stock from MSTS to ORTS it can be useful not having to adjust each filename reference in each WAG and ENG file that are often copies from each other. Instead of writing out the full filename ORTS lets you use the phrase SameName which it replaces with the filename of the file that contains the Include statement.

Example of using the SameName Include statement in file ~CTN-PT5-Tender-FC.wag:

Include ( ../[[SameName]] )

is equivalent to writing the full filename:
Include ( ../[[~CTN-PT5-Tender-FC.wag]] )

See Open Rails manual "OR-Specific Include Files for Modifying MSTS File Parameters" for further details.

See the Example Applications for examples of this type of application.

top

Example Aplications.

The following scenario examples have been modelled based upon stock used in the Zig Zag route Zig Zag railway route. (Note: The stock in the route is not currently set up with INC files.)

Multiple Call - Universal INC files


Typical Universal INC files would be for common components used by the majority of the rolling stock.

For example in the ZZ route we have common components such as brake triple valves, drivers brake valves, 
brake cylinders, reservoirs, compressors, etc.

To implement this we would establish a folder structure to accomodate the various components. 

In the case of the ZZ it would look like the following:

 

Then we would create a WAG file that would look like the following to call these common components:

Comment ( ******************************* Brakes *******************************
          Included in this section - Type, Force, Reservoir, Applicatiion, Release. etc
          *********************************************************************** )
	 
          BrakeEquipmentType( "Triple_valve, Auxilary_reservoir, Handbrake" )
          BrakeSystemType                            ( "Air_single_pipe" )
          
          Include ( "../Common_Inc_Brake/Triple_Valves/au_triplevalve_quickaction_goods.inc" )
          Include( "../Common_Inc_Brake/Brake_Cylinders/au_brake_cylinder_6_comb.inc" )

          Comment ( ===Brake Pipe Properties=== )
          BrakePipeVolume ( 0.15ft^3 ) Comment ( CTN calculator * 0.64 for 1 inch pipes )

          Comment ( ===Foundation Brake Gear, Brake Shoe and Force Properties=== )
          ORTSMaxBrakeShoeForce                              	( 31360.0lbf ) 
          Comment (Assume empty weight of 14.0t-uk)	 
          MaxHandbrakeForce                          	( 31360.0lbf )	 
          ORTSNumberCarBrakeShoes ( 4 ) Comment ( *** Assumes One Shoe Per Wheel *** )
          ORTSBrakeShoeType ( "Cast_Iron_P6" ) 
 

Note the combination of Include ( ) statements for the common components, and the other parameters which are specific to the 
particular car that we are modelling.

Multiple Call - Class specific INC files


Typical Class specific INC files would be to eliminate significant 
"duplication", when for example, a class of locomotives is configured with a model for each engine number. 

For example in the ZZ route we have two locomotives from the P Class, ie P464 and P708.

To implement this we would establish a folder structure to accomodate the various "duplicate" components. 

In the case of the ZZ it would look like the following:

 

Then we would create a ENG file that would call these "duplicate" components using commands like the following:

Comment ( ***************************** Cylinders *****************************
          Included in this section - Number, Stroke, Diameter, steam usage, etc          
         *********************************************************************** )

            Include( "/Include/P-Class/Cylinders.inc" )


Comment ( ************************** Engine Controls **************************
        Included in this section - Controllers for Regulator, Reverser, Brakes, etc
        *********************************************************************** )

            EngineControllers (
                Include( "/Include/P-Class/CabControls.inc" )
                Include( "../Common_Inc_Brake/Loco/A6ET/au_Brake_Control_West_4.inc" )
                )

Note, in this instance, also the call to a Universal common component in the Engine Controls section.

Universal INC files


Typical single use call INC files can be used to add parameters to route type files or stock type files.

For example in the ZZ route we have added a number of new components to the route (INC) definition file.

To implement this we would establish a folder structure to accomodate the various components. 

In the case of the ZZ it would look like the following:

 

Then in the OpenRails folder we would create a TRK file that would 
insert the following parameters into the route TRK:

      include ( ../au_great_zig_zag.trk )

        ORTSSingleTunnelArea  ( "26.84*(m^2)" )
        ORTSSingleTunnelPerimeter ( 20.724m )
        ORTSDoubleTunnelArea ( "49.536*(m^2)" )
        ORTSDoubleTunnelPerimeter ( 28.497m ) 

        ORTSUserPreferenceForestClearDistance ( 6 )

      Comment ( Add Superelevation values - 1921 NSWGR Plate Laying Guide )	
        ORTSTrackSuperElevation ( 0.0 0.000  160.0 0.0635  270.0 0.0635  280.0 0.0762 390.0 0.0762  400.0 0.1016 590.0 0.1016  
        600.0 0.0889  790.0 0.0889 800.0  0.0635 990.0 0.0635 1000.0 0.0508  1190.0 0.0508 1200.0 0.0381 1590.0  0.0381 1600.0 0.0254 
        3190.0 0.0254 3200.0 0.0127   10000.0 0.0127 )
        
      Comment ( Adds sounds for turntables )	
        ORTSDefaultTurntableSMS ( turntable.sms )

      Comment ( Adds sounds to tracks, such as curve squeal )
        ORTSSwitchSMSNumber ( 18 )
        ORTSCurveSMSNumber ( 10 )
        ORTSCurveSwitchSMSNumber ( 12 )

top

Coals to Newcastle

An Open Rails Train Simulator Route

INC Files.. For Beginners

Index

Introduction to Open Rails Include Files

Advantages of using Include Files

Challenges with using Include Files

The Include Statement

INC File Content Principles

File Naming Principles

Multiple Call INC Files

Single Call INC Files.

Example Aplications.