[Genma Saotome]

For better and worse, KUJU defined all of the folder names we use in MSTS. With the development of the Include file concept (as applied to .engs and .wags) I concluded that something very much like KUJU's \common.cab directory tree was needed for .inc files. Using the examples of how payware vendors made use of folders in \trains I saw that sometimes they used \common.cab, sometimes they used a folder specific to their own product folder, and sometimes they used something "in between" -- a vendor named folder named for the unskined mesh (e.g., 3DTrains_FPack).

This post describes the issues and proposed folders. Post #2 is a procedure to follow when assigning files to a location. Posts #3-6 are examples

IMO KUJU's solution for cab files is a good template for locating Include files. After much experimentation I'm proposing am solution that addresses these needs:

• A folder for widely used .inc files, much like what is in \common.cab.
  
• Recognition that many end-users have routes and equipment from many countries and therefore it might be useful to group certain files for each country.
  
• Acceptance that many payware vendors sell the same mesh skinned for many railroads and when distributed there is a unique folder for each railroad.
  
• Addressing the easiest to solve problem of minimal commonality, where everything belongs in one folder.

Proposal:
Within the \trains directory,

• Add \common.fleet
  
• Add \common.model

Within both of those directories, add folders (one for your own country and others only as needed) for country codes. Examples:
\AUS Australia
\AUT Austria
\BRA Brazil
\CAN Canada
\CHE Switzerland
\CHN China
\CZE Czechia
\DEU Germany
\FRA France
\GBR United Kingdom
\HRV Croatia
\HUN Hungary
\IND India
\ITA Italy
\JPN Japan
\NLD Netherlands
\POL Poland
\RUS Russian Federation
\SVK Slovakia
\SVN Slovenia
\SWE Sweden
\UKR Ukraine
\USA United States of America
\ZAF South Africa

For myself, this means I will have (at least) this:

• \common.fleet\USA
  
• \common.model\USA

Because there are many instances of multiple people creating models for the same locomotive or car there are cases where the parametric values will differ from one person's model to another -- different sizes, different location of lights, etc. To protect end users from inadvertently over-writing existing .inc files from person A when installing a similar model from person B I decided it was probably best to add a directory layer in the \common.model tree that is based on the model and maker names (e.g., \F7 by 3dtrains).

An example:

\common.model\USA\F7 by 3dtrains

Last, the .inc file itself should be named for what the parameters contained therein describe (e.g., \Std_Steam_Locomotive_Bar_&_Coupler.inc ).

Examples:

• \common.fleet\USA\Std_Steam_Locomotive_Bar_&_Coupler.inc
  \common.model\USA\F7 by 3dtrains\F7A_Engine_Specs.inc

======================

Possible issues

Is there a need to add an additional folder layer for \freight, \passenger, and \locomotive? I'm inclined to say no, but am open to being persuaded otherwise.

Is there a problem in the directory trees WRT files being used by multiple countries? I don't know. The US and Canada had a lot in common.

[Genma Saotome]

Include_File_Procedure_Location_Readme.txt
2017/11/20

This document is the procedure I use to move parameters from .wag files
into .inc files as well as the standard to decide where those .inc files should
reside.

All .inc files are stored in one of three locations:
(1) The same folder as the .wag or .eng file that uses it.
(2 ) A folder based on the unskined model that will be used by several .eng or
.wag files.
(3 ) A folder based on the equipment that is used by a large percentage of .wags
or engs.

Case (1) When you are sure the .inc will only be used by the .wag or .eng files
found in a single folder, put the .inc in that folder.

Case (2) When it is obvious the .eng or .wag files that will use an .inc are found
in many folders (e.g., the same model skinned for different railroads, each of
which have their own folder) go into a subdirectory of the \common.model
folder.

Within \common.fleet there will always be many subdirectories of \"country
code" where "country code" is a 3 character abbreviation or each country
name (.e.g., \USA, \GBR, \CAN, \AUS, etc.). The codes are from (ISO
3166-1 alpha-3*)

Within \common.model add a sub directory whose name is based on what the
model is and who created it (e.g.,\USRA_DS_Boxcar_Tim_Muir_Model).
The purpose of this long name is ensure that .inc files for similar models
from other people obtained at some later date will not accidentilly over-write
the .inc files created earlier for this model.

Last, the name of the actual .inc file should be based on what the parameters
in the .inc are used for (e.g., XM_USRA_DS_MTY_Weight.inc ).

Case (3) When an .inc file will be used by a very larger percentage of .eng or
.wag files they will be placed in a sub directory of the \common.fleet folder.

Within \common.fleet there will always be many subdirectories of \"country
code" where "country code" is a 3 character abbreviation or each country
name (.e.g., \USA, \GBR, \CAN, \AUS, etc.). The codes are from (ISO
3166-1 alpha-3)

Last, the name of the actual .inc file should be based on what the parameters
in the .inc are used for (e.g., Single_Pipe_AB_Brakes ).

Examples:
\common.fleet\USA\Std_Type_H_Coupler_Generic_Draft_Gear.inc
\common.model\USA\USRA_DS_Boxcar_Tim_Muir_Model\XM_USRA_DS_MTY_Weight.inc
\ATSF_Passenger_Set_3DTrains\ATSF_Super_Chief_Diner_Mesh_Dimensions.inc

[Genma Saotome]

Examples of \common.fleet\USA .inc files"

• \Early_Diesel_Era_Generic_AWS_Monitor.inc
  
• \Early_Diesel_Era_Generic_Emergency_Stop_Monitor.inc
  
• \Generic_Locomotive_Monitors.inc
  
• \Single_Pipe_AB_Brakes.inc
  
• \Single_Pipe_KC_Brakes.inc
  
• \Std_Early_Road_Diesel_Independant_AB_Brake.inc
  
• \Std_Late_Steam_Era_Diesel_Locomotive_Bar_&_Bar.inc
  
• \Std_Late_Steam_Era_Diesel_Locomotive_Bar_&_Coupler.inc
  
• \Std_Late_Steam_Era_Diesel_Locomotive_Coupler.inc
  
• \Std_Late_Steam_Era_Diesel_Switcher_Coupler.inc
  
• \Std_Single_Pipe_AB_1_B_Brakes.inc
  
• \Std_Steam_Locomotive_Bar_&_Coupler.inc
  
• \Std_Tender_Couplers_Generic.inc
  
• \Std_Tightlock_Coupler_Generic_Draft_Gear.inc
  
• \Std_Tightlock_Passenger_Couplers_Generic_Draft_Gear.inc
  
• \Std_Type_Coupler_Generic_Draft_Gear.inc
  
• \Std_Type_D_Coupler_Generic_Draft_Gear.inc
  
• \Std_Type_E_Coupler_Generic_Draft_Gear.inc
  
• \Std_Type_H_Coupler_Generic_Draft_Gear.inc
  
• \Westinghouse_24RL_Brakestand.inc
  
• \Westinghouse_24RL_Brakestand_W_Dynamics.inc

[Genma Saotome]

Examples of folder names within common.fleet:

• \ALCO_S1_Stds_Percy_&_Norton_Model
  
• \ALCO_S2_Stds_Percy_&_Norton_Model
  
• \F3_Stds_3dtrains_V3
  
• \F7_Stds_3dtrains_V3
  
• \FM_H10-44_Stds_Percy_&_Norton_Model
  
• \FM_H12-44_Stds_Percy_&_Norton_Model
  
• \FM_H14-44_Stds_Percy_&_Norton_Model
  
• \FT_Stds_3dtrains_V1
  
• \FUnit_Stds_3DTrains_v3
  
• \GP9_SLI_Payware
  
• \MILW_Heavy_Electrics_Tim_Muir
  
• \PS-1_Model_By_Larry_Goss
  
• \SD9_BLW_Payware
  
• \USRA_DS_Boxcar_Tim_Muir_Model
  
• \USRA_SS_Boxcar_Tim_Muir_Model
  
• \X29_&_ARA_Boxcar_By_Tim_Muir

[Genma Saotome]

Examples of .inc file names located in the \common.model\USA directory tree:

• \FM_H10-44_Air_Compressor.inc
  
• \FM_H10-44_Couplers.inc
  
• \FM_H10-44_Engine_Specs.inc
  
• \FM_H10-44_Lights.inc
  
• \FM_H10-44_Locomotive_Brake.inc
  
• \FM_H10-44_Locomotive_Control.inc
  
• \FM_H10-44_Mesh_Defined.inc
  
• \FM_H10-44_Monitors.inc
  
• \FM_H10-44_Std_Lights.inc
  
• \FM_H10-44_Text.inc
  
• \FM_H10-44_Weight.inc
  
• \FM_H10-44_Westinghouse_XYZ_Brakestand.inc

[Genma Saotome]

An example of a typical .eng after revision to use .inc files:

SIMISA@@@@@@@@@@JINX0D0t______

Wagon ( SP_H-12-44_1568  
	Type ( Engine )

	comment ( SP 3rd Order Fairbanks-Morse H-12-44 #1568 in 1956 Tiger Stripe paint with working gyralights )

	WagonShape ( SP_H-12-44_1568.s )
	FreightAnim ( SP_H-12-44_1568_FA.s 1 1 1 )

	Include ( "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Mesh_Defined.inc" ) 
	Include ( "..\\Common.Fleet\\US\\Std_Late_Steam_Era_Diesel_Switcher_Coupler.inc" ) 
	Include ( "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Weight.inc" )
	Include ( "..\\Common.Fleet\\US\\Std_Early_Road_Diesel_Independant_AB_Brake.inc" )
	Include ( "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Std_Lights.inc" ) 

	Sound ( Tmeng_2.sms )
)

Engine ( SP_H-12-44_1568

	Effects (
		DieselSpecialEffects
		(
			Exhaust1
			(
				-0.3 4.64 2.78
				0 1 0
				.1
			)
			Exhaust2
			(
				0.3 4.64 2.78
				0 1 0
				.1
			)
		)
	)

	Wagon ( SP_H-12-44_1568 )
	Type ( Diesel )
	Include ( "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Engine_Specs.inc" )
	Include (  "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Air_Compressor.inc" )
	Include (  "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Westinghouse_XYZ_Brakestand.inc " )

	CabView ( FMH12_2.cvf )
	Headout ( 1.6 3.4 -5.8 )

	DieselSmokeEffectInitialMagnitude( 1 )
	DieselSmokeEffectMaxMagnitude( 2 )
	DieselSmokeEffectInitialSmokeRate( 1 )
	DieselSmokeEffectMaxSmokeRate( 4 )

	Include (  "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Monitors.inc" )
	Include (  "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Locomotive_Controllers.inc" )

	comment( fuel_level )
	EngineVariables ( 750 )
	Sound ( TMcab_1.sms )
	Name ( "SP H-12-44 1568 Tiger Stripe, 1952 < Active < 19nn" )

	Include ( "..\\Common.Model\\US\\FM_H12-44_Stds_Percy_&_Norton_Model\\FM_H12-44_Std_Text.inc")
)

Exhaust and smoke effects are retained in the .eng file to allow for locomotive by locomotive customization. Almost everything else has been moved to an .inc file because the parameter names and values are identical for all .wags of that model.

[eric from trainsim]

I like the concept, but is going by individual country really needed??

I'd think an Alco RSD3 would have the same performance criteria regardless if it was in Canada, Mexico, United States, or England, no?

The only difference might be units of measure for speed/fuel/weights.

Electric engines sold and used across Europe are also going to be mostly the same physics aside perhaps from voltage.

[Genma Saotome]

Eric, you may be right about all of that but I suspect the further back you go in time the less commonality would be found. I'd really like to hear what the European members think as I suspect they are the ones most likely to have rolling stock from multiple countries.

At any rate I did mention your point as a potential issue and I'm quite open to being shown country codes are not needed. OTOH if they are a sensible feaeture then perhaps adding something like \Global or \FRA&DEU (as needed) would serve.

[longiron]

I believe "include" file standards are a good thing - but I'm very fuzzy on what's available for include and what's not. Perhaps some baseline is needed for those who aren't deep into this area yet.

Thanks

[Genma Saotome]

longiron, on 20 November 2017 - 03:34 PM, said:

I believe "include" file standards are a good thing - but I'm very fuzzy on what's available for include and what's not. Perhaps some baseline is needed for those who aren't deep into this area yet.

Thanks

AFAIK only Gerry (RHSteele) and I are trying to make the .inc file work. Starting from scratch it has been very much a trial and error process. If you want a better understanding of things go back up and review the examples I posted for \common.fleet\USA and ask yourself two questions:

• Are these file likely to be used in lots and lots of .wags and .engs?
  
• When there are several files for a certain kind of equipment do the names convey what is common and what might be unique to each?

You might not recognize what each one is/does but IMO what's in that list could be the go-to list of .inc files to go into .wags and .engs of most US rolling stock between 1915 and 1960.


A second area to study are the names of the actual .inc files I posted in my last example. I think all but two of the file names are self evident. The oddballs are ...mesh_defined.inc and the westinghouse_xyz_brakestand.inc. I need to rename the last one and change "xyz" to "generic". As for mesh_defined, that holds the dimensional parameters that describe the model. Here's a typical example of what's in one of the mesh_defined.inc files:

Comment ( ATSF_Super_Chief_Regal_Series_Mesh_Dimensions.inc )


	Type ( Carriage )
	Size ( 3m 6m 25.6912m )
	WheelRadius ( 28in/2 )
	InertiaTensor ( Box (3m 6m 25.6912m) )
	DerailRailHeight ( 4cm )
	NumWheels (8 )

	ORTSTrackGauge ( 4ft 8.5in )
	ORTSRigidWheelBase ( 5ft 6in )
	ORTSBearingType ( Roller )
	ORTSUnbalancedSuperelevation ( 6in )

What is there reflects what the modeler created in the mesh -- the kind of model and descriptive data about it. If there was an Inside() statement I'd put it here as well. I chose not to include Lights() because there are some Lights() specifications that vary from one .eng to another for the same locomotive -- rear end helper for instance. Do Lights() get their own .inc files. The exception to "as defined by the mesh" is ORTSUnbalancedSuperelevation(). I put that here becuase it came with the other three ORTS parameters. Arguably it could be moved to the .inc files that address weight as that's where I've put CenterofGravity().

I'll add that most of the .inc files I have created do not yet have ORTS_whatever parameters. Just something I havn't yet turned to solve. The other thing is these files are not at all compatible w/ MSTS and should not be put in a \trainset folder that is used by MSTS.