Merge branch 'master' into external-controllers

Author: cesarBLG

Source/ContentChecker/ContentChecker.csproj

@@ -14,7 +14,7 @@
   </PropertyGroup>
   <ItemGroup>
     <Reference Include="MonoGame.Framework">
-      <HintPath>$(SolutionDir)\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
+      <HintPath>..\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
     </Reference>
   </ItemGroup>
   <ItemGroup>

Source/Contrib/ActivityEditor/ActivityEditor/ActivityEditor.csproj

@@ -17,7 +17,7 @@
   </PropertyGroup>
   <ItemGroup>
     <Reference Include="MonoGame.Framework">
-      <HintPath>$(SolutionDir)\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
+      <HintPath>..\..\..\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
     </Reference>
   </ItemGroup>
   <ItemGroup>

Source/Contrib/ActivityEditor/LibAE/LibAE.csproj

@@ -14,7 +14,7 @@
   </PropertyGroup>
   <ItemGroup>
     <Reference Include="MonoGame.Framework">
-      <HintPath>$(SolutionDir)\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
+      <HintPath>..\..\..\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
     </Reference>
   </ItemGroup>
   <ItemGroup>

Source/Contrib/DataCollector/DataCollector.csproj

@@ -15,7 +15,7 @@
   </PropertyGroup>
   <ItemGroup>
     <Reference Include="MonoGame.Framework">
-      <HintPath>$(SolutionDir)\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
+      <HintPath>..\..\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
     </Reference>
   </ItemGroup>
   <ItemGroup>

Source/Contrib/TrackViewer/TrackViewer.csproj

@@ -26,7 +26,7 @@
       <HintPath>..\..\3rdPartyLibs\GNU.Gettext.dll</HintPath>
     </Reference>
     <Reference Include="MonoGame.Framework">
-      <HintPath>$(SolutionDir)\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
+      <HintPath>..\..\3rdPartyLibs\MonoGame\MonoGame.Framework.dll</HintPath>
     </Reference>
   </ItemGroup>
   <ItemGroup>

Source/Documentation/Manual/cabs.rst

@@ -79,14 +79,24 @@ The following controls are available for the cabview:
 - ``ORTS_BATTERY_SWITCH_COMMAND_BUTTON_CLOSE`` and ``ORTS_BATTERY_SWITCH_COMMAND_BUTTON_OPEN`` can be used if the switch is controlled with two pushbuttons (one to close the switch and the other to open it)
 - ``ORTS_BATTERY_SWITCH_ON`` can be used to control a light on the cab showing the state of the battery switch
 
-Other controls can be hidden if the low voltage power supply is not available using the following parameter::
+Other controls can be disabled if the low voltage power supply is not available using the following parameter::
 
       TwoState (
-         Type ( ORTS_CIRCUIT_BREAKER_CLOSED TWO_STATE)
+         Type ( ORTS_CIRCUIT_BREAKER_CLOSED TWO_STATE )
          ...
          DisabledIfLowVoltagePowerSupplyOff ( 1 )
       )
 
+By default, the cabview control will be completely hidden. You can also set a specific value for the control when it is disabled::
+
+      TwoState (
+         Type ( SPEEDOMETER DIAL )
+         ...
+         DisabledIfLowVoltagePowerSupplyOff ( 1 )
+         HideIfDisabled ( 0 )
+         ValueIfDisabled ( 0 )
+      )
+
 .. _cabs-master-key:
 
 Master key
@@ -105,12 +115,22 @@ The following controls are available for the cabview:
 - ``ORTS_CURRENT_CAB_IN_USE`` can be used to indicate that the current cab is active
 - ``ORTS_OTHER_CAB_IN_USE`` can be used to indicate that another cab of the train is active
 
-Other controls can be hidden if the cab power supply is not available using the following parameter::
+Other controls can be disabled if the cab power supply is not available using the following parameter::
+
+      TwoState (
+         Type ( ORTS_CIRCUIT_BREAKER_CLOSED TWO_STATE )
+         ...
+         DisabledIfCabPowerSupplyOff ( 1 )
+      )
+
+By default, the cabview control will be completely hidden. You can also set a specific value for the control when it is disabled::
 
       TwoState (
-         Type ( ORTS_CIRCUIT_BREAKER_CLOSED TWO_STATE)
+         Type ( SPEEDOMETER DIAL )
          ...
          DisabledIfCabPowerSupplyOff ( 1 )
+         HideIfDisabled ( 0 )
+         ValueIfDisabled ( 0 )
       )
 
 .. _cabs-service-retention:

Source/Documentation/Manual/features-rollingstock.rst

@@ -599,6 +599,8 @@ Here below a sample of a ``.load-or`` file::
 	  	"Shape" : "COMMON_Container_3d\\Cont_40ftHC\\container-40ftHC_Triton.s",
 	  	"ContainerType" : "C40ftHC",
 	  	"IntrinsicShapeOffset": [0,1.175,0],
+   		"EmptyMassKG": 2100.,
+		  "MaxMassWhenLoadedKG": 28000.,
 	  }
   }
 
@@ -621,20 +623,30 @@ Here below a sample of a ``.load-or`` file::
   container with respect to the container shape file coordinates. Unfortunately often such 
   offset is not [0,0,0], which would be advisable for newly produced containers. A simple way to 
   state such offset is to use the ``Show Bounding Info`` of ``Shape Viewer``.
+- "EmptyMassKG" is an optional parameter that defines the tare (weight when empty) of the 
+  container. If the parameter is not present, OR uses a default parameter, specific for that 
+  ContainerType.
+- "MaxMassWhenLoadedKG" is an optional parameter that defines the sum of the tare plus the maximum 
+  allowed payload. As above, if the parameter is not present, OR uses a default parameter, specific for that 
+  ContainerType.
+
 
 Pre-setting a .wag file to accommodate containers
 -------------------------------------------------
 
 As a minimum following block must be present in the .wag file for a double stacker::
 
   ORTSFreightAnims (
+		WagonEmptyWeight ( 12.575t )
 		LoadingAreaLength ( 12.20 )
 		AboveLoadingAreaLength ( 12.20 )
 		DoubleStacker ()
 		Offset( 0 0.34 0 )
 		IntakePoint ( 0 6.0 Container)
 		)
 
+- WagonEmptyWeight is the weight of the wagon, when it has neither containers nor other 
+  weighing freight animations on board
 - LoadingAreaLength is the length in meters of the loading area available for containers
 - AboveLoadingAreaLength is the length in meters of the above loading area available 
   for containers (parameter not needed if not double stacker)
@@ -694,9 +706,9 @@ shown here::
 
   		Wagon (
 			  WagonData ( DTTX_620040_A ATW.DTTX_620040 )
-			  LoadData ( 20cmacgm common.containerdata CenterFront)
-			  LoadData ( 20hamburgsud common.containerdata CenterRear)
-			  LoadData ( 40msc common.containerdata Above)			
+			  LoadData ( 20cmacgm common.containerdata CenterFront Empty)
+			  LoadData ( 20hamburgsud common.containerdata CenterRear Loaded)
+			  LoadData ( 40msc common.containerdata Above Random)			
 			  UiD ( 11 )
 		)
 
@@ -707,7 +719,17 @@ present. The meaning of the parameters is as follows:
 - The first parameter is the name of the ``.load-or`` file 
 - The second parameter is the path (having ``Trainset`` as base path) where the ``.load-or``
   file resides 
-- The third parameter indicates where the container is allocated on the wagon.
+- The third parameter indicates where the container is allocated on the wagon
+- The fourth parameter, which is optional, defines the load state of the related container, 
+  which is used to derive the weight of the container. If ``Empty`` is present, the weight 
+  of the empty container is used as actual weight; if ``Loaded`` is present, the maximum 
+  weight (tare + payload) of the container is used; if ``Random`` is present, the weight 
+  is computed as follows: a random number between 0 and 100 is generated. If the number is 
+  below 31, the container is considered empty; else the number is used as percentage of the 
+  maximum weight of the container (tare + payload). The weight of the containers are added to 
+  the empty weight of the wagon, to compute the total weight of the wagon. If the parameter 
+  is not present, the ``Random`` value is assumed.
+
 
 The entry for the container allocated ``Above`` must be the last one.
 
@@ -733,18 +755,19 @@ A minimum ``FreightAnimations`` entry in a ``.wag`` file to have the same pre-lo
 set as in the previous paragraph is as follows::
 
     ORTSFreightAnims (
-	  	LoadingAreaLength ( 14.6 )
-	  	AboveLoadingAreaLength ( 16.15 )
+		  WagonEmptyWeight ( 12.575t )
+		  LoadingAreaLength ( 14.6 )
+		  AboveLoadingAreaLength ( 16.15 )
 		  DoubleStacker ()
 		  Offset( 0 0.34 0 )
 		  IntakePoint ( 0 6.0 Container)
-		  LoadData ( 20cmacgm common.containerdata CenterFront)
-		  LoadData ( 20hamburgsud common.containerdata CenterRear)
-		  LoadData ( 40msc common.containerdata Above)
+		  LoadData ( 20cmacgm common.containerdata CenterFront Empty)
+		  LoadData ( 20hamburgsud common.containerdata CenterRear Loaded)
+		  LoadData ( 40msc common.containerdata Above Random)
 		)
 
 As can be seen, the syntax of the ``LoadData`` entries is the same as in the case of 
-the ``.con``  file.
+the ``.con``  file. Also here the fourth parameter is optional.
 
 Obviously, using ``.wag`` files for this type of info, a different ``.wag`` file must 
 be created for every desired pre-loaded set of containers.
@@ -1048,9 +1071,9 @@ The ``.load-stations-loads-or`` file is a Json file. An example is shown here be
 		{
 			"LoadStationID" : { "wfile" : "w-005354+014849.w", "UiD" :  21, },
 			"LoadData" : [
-				{ "File" : "40HCcai", "Folder" : "common.containerdata", "StackLocation" : 0, },
-				{ "File" : "40HCcai", "Folder" : "common.containerdata", "StackLocation" : 0, },
-				{ "File" : "20cmacgm", "Folder" : "common.containerdata", "StackLocation" : 2, },
+				{ "File" : "40HCcai", "Folder" : "common.containerdata", "StackLocation" : 0, "LoadState" : "Empty"},
+				{ "File" : "40HCcai", "Folder" : "common.containerdata", "StackLocation" : 0, "LoadState" : "Loaded"},
+				{ "File" : "20cmacgm", "Folder" : "common.containerdata", "StackLocation" : 2, "LoadState" : "Random"},
 				{ "File" : "20kline", "Folder" : "common.containerdata", "StackLocation" : 2, },
 				{ "File" : "45HCtriton", "Folder" : "common.containerdata", "StackLocation" : 5, },
 				{ "File" : "45HCtriton", "Folder" : "common.containerdata", "StackLocation" : 5, },
@@ -1081,6 +1104,8 @@ The file can define the population at startup of many container stations.
   index refers to a child stack location.
 - If more than a container is defined for a stack location, they are stacked one above the 
   other.
+- The ``LoadState`` parameter is optional, and has the same meaning and values as the 
+  parameter of the same name which can be present in .con or .wag files.
 
 The container station population file must be written taking into account the constraints 
 of the stack locations (container length must be smaller than stack location lenght, 
@@ -1192,6 +1217,22 @@ shape movement, however for greater accuracy the modeler can add specific values
 ``ORTSLengthAirHose``. In addition the length values suggested in the Derailment Coefficient should 
 also be added.
 
+Passenger doors
+===============
+
+.. index:: ORTSDoors
+
+Passenger doors are opened and closed (by default) using the ``<Q>`` and ``<Shift+Q>`` keys.
+It is possible to add opening and closing delays, which can be useful to delay the indication of
+"Doors closed" until all doors are fully closed.
+The delays can be added inserting the following block in the wagon section of any
+ENG or WAG file::
+
+  ORTSDoors (
+    ClosingDelay ( 5s )
+    OpeningDelay ( 1s )
+  )
+
 
 C# engine scripting
 ===================

Source/Documentation/Manual/physics.rst

@@ -339,6 +339,17 @@ The ``ORTSSlipControlSystem ( Full )``  parameter can be inserted
 into the engine section of the .eng file to indicate the presence of
 such system.
 
+Steam locomotives will have varying magnitude of rotational forces depending upon the separation 
+between the cylinder crank angles.
+
+The crank angles for example of a 2 cylinder locomotive has a 90 deg separation whereas a 3 cylinder locomotive 
+has a 120 deg variation. OR will default to a "common" value for the number of cylinders defined, but the user 
+can override this with "ORTSWheelCrankAngleDifference ( A B C D )", where A, B, C and D are the separations for 
+up to a 4 cylinder locomotive. For example, a 4 cylinder locomotive can have a separation of 90 deg for each 
+cylinder or sometimes it has two of the cranks separated by 45 deg instead. These values can either be in 
+Rad (default) or Deg. The separations should be described around the full 360 deg of rotation, so for example, 
+a 3 cylinder locomotive would be - ORTSWheelCrankAngleDifference ( 0deg, 120deg, 240deg ).
+
 
 Engine -- Classes of Motive Power
 =================================
@@ -2022,13 +2033,22 @@ of a relevant wagon (including diesel, steam or electric locomotives.
 
 OR supports the following special visual effects in a steam locomotive:
 
-- Steam cylinders (named ``CylindersFX`` and ``Cylinders2FX``) -- two effects
-  are provided which will represent the steam exhausted when the steam
-  cylinder cocks are opened.  Two effects are provided to represent the steam
-  exhausted at the front and rear of each piston stroke. These effects will
-  appear whenever the cylinder cocks are opened, and there is sufficient
-  steam pressure at the cylinder to cause the steam to exhaust, typically the
-  regulator is open (> 0%).
+- Steam cylinder cocks (named ``Cylinders11FX``, ``Cylinders12FX``, ``Cylinders21FX``, 
+  ``Cylinders22FX``, ``Cylinders31FX``, ``Cylinders32FX``, ``Cylinders41FX``, 
+  ``Cylinders42FX``) -- these effects are provided which will represent the steam 
+  exhausted when the steam cylinder cocks are opened.  The effects are provided to 
+  represent the steam exhausted at the front and rear of each piston stroke. The 
+  numbers in the value names represent firstly the cylinder and the second the 
+  cylinder position, ie "11" = cylinder 1, front stroke, "12" = cylinder 1, backward 
+  stroke. These effects will appear whenever the cylinder cocks are opened, and 
+  there is sufficient steam pressure at the cylinder to cause the steam to exhaust, 
+  typically when the regulator is open (> 0%). Note: ``CylindersFX`` and ``Cylinders2FX`` 
+  should now be considered legacy parameters and ideally should not be  used.
+- Cylinder Exhaust (named ``CylinderSteamExhaust1FX``, ``CylinderSteamExhaust2FX``, 
+  ``CylinderSteamExhaust3FX``, ``CylinderSteamExhaust4FX``) -- these effects represent 
+  the steam exhausted from the cylinders at the end of each stroke. Typically this 
+  steam is feed back through a blast pipe up the smoke stack to improve draught in the 
+  firebox and bolier. The above parameters represent up to 4 individual steam cylinders.
 - Stack (named ``StackFX``) -- represents the smoke stack emissions. This
   effect will appear all the time in different forms depending upon the firing
   and steaming conditions of the locomotive.
@@ -2085,7 +2105,7 @@ Similarly if any of the co-ordinates are zero, then the effect will not be displ
 Each effect is defined by inserting a code block into the ENG/WAG file similar to
 the one shown below::
 
-    CylindersFX (
+    Cylinders11FX (
         -1.0485 1.0 2.8
         -1  0  0
         0.1
@@ -2698,7 +2718,9 @@ Typically this happens with lightly loaded vehicles at lower speeds, and hence t
 
 When a vehicle experiences wheel skid, an indication is provided in the FORCES INFORMATION HUD. To correct the problem the brakes must be released, and then applied slowly to ensure that the wheels are not *locked* up. Wheel skid will only occur if ADVANCED adhesion is selected in the options menu.
 
-(Ref to *Wheel Skidding due to Excessive Brake Force* for additional information)
+On some steam locomotives brakes are not applied to all the wheels, possibly only the drive wheels have braking, and the other wheels do not. The following parameter can be set to reflect this for the calculation of skidding.
+
+``ORTSLocomotiveDriveWheelOnlyBraking ( x )`` - where x = 1 if brakes are only fitted to the drive wheels, set to 0 or leave blank if all wheels are braked.
 
 Using the F5 HUD Expanded Braking Information
 ---------------------------------------------