Add load/empty tokens for relay valve and inshot

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -663,6 +663,8 @@ and the state of these parameters when the wagon or locomotive is full.
    single: EmptyORTSWagonFrontalArea
    single: EmptyORTSDavisDragConstant
    single: EmptyCentreOfGravity_Y
+   single: EmptyBrakeRelayValveRatio
+   single: EmptyBrakeRelayValveInshot
    single: IsGondola
    single: UnloadingStartDelay
    single: FreightAnimContinuous
@@ -680,11 +682,13 @@ and the state of these parameters when the wagon or locomotive is full.
    single: FullORTSWagonFrontalArea
    single: FullORTSDavisDragConstant
    single: FullCentreOfGravity_Y
+   single: FullBrakeRelayValveRatio
+   single: FullBrakeRelayValveInshot
 
 To configure the stock correctly the following empty and full parameters need to be 
 included in the ORTSFreightAnims file. Empty values are included in the first block, 
 and full values are included in the second code block. A sample code block is shown 
-below.::
+below::
 
     ORTSFreightAnims
     (
@@ -720,6 +724,58 @@ below.::
      )
   )
 
+For some rolling stock, it may be more realistic to handle variations in load/empty
+brake force by changing the brake cylinder pressure developed, rather than changing
+the brake force directly. In such cases, the empty/load relay valve parameters work
+best. Unlike other freight physics parameters, the relay valve ratio will not change
+continuously as freight is loaded. Instead, when the freight load is above 25% capacity,
+the loaded relay valve ratio is used, otherwise the empty ratio (or the ratio defined
+in the main .wag file) is used. The level of brake cylinder in-shot can also be changed
+depending on the load level as is often the case on load proportioning equipment. The
+standard behavior of these parameters is defined in more detail in the 
+:ref:`air brakes physics <physics-braking-parameters>` section.
+
+Here is an example of a gondola with a 50% load/empty valve::
+
+    ORTSMaxBrakeShoeForce ( 31300lb )
+    MaxHandbrakeForce ( 32000lb )
+
+    ORTSFreightAnims (
+        MSTSFreightAnimEnabled ( 0 )
+        WagonEmptyWeight( 28.9t-us )
+
+        EmptyBrakeRelayValveRatio ( 0.5 )
+        EmptyBrakeRelayValveInshot ( -15psi )
+
+        ORTSDavis_A ( 87.35lbf )
+        ORTSDavis_B ( 0.289lbf/mph )
+        ORTSDavis_C ( 0.144lbf/mph^2 )
+        ORTSWagonFrontalArea ( 120ft^2 )
+        ORTSDavisDragConstant ( 0.0012 )
+        EmptyCentreOfGravity_Y ( 1.377 )
+        IsGondola( 1 )
+        UnloadingStartDelay ( 5 )
+
+        FreightAnimContinuous (
+            IntakePoint ( 0.0 6.0 FreightCoal )
+            Shape ( COAL_LOAD.s )
+            MaxHeight ( 0.0 )
+            MinHeight ( -2.2 )
+            FreightWeightWhenFull ( 114.1t-us )
+            FullAtStart ( 0 )
+
+            FullBrakeRelayValveRatio ( 1.0 )
+            FullBrakeRelayValveInshot ( 0psi )
+
+            FullORTSDavis_A ( 258.5lbf )
+            FullORTSDavis_B ( 1.43lbf/mph )
+            FullORTSDavis_C ( 0.0504lbf/mph^2 )
+            ORTSWagonFrontalArea ( 120ft^2 )
+            ORTSDavisDragConstant ( 0.00042 )
+            FullCentreOfGravity_Y ( 2.251 ) 
+        )
+    ) 
+
 .. index::
    single: Shape
    single: MaxHeight

Source/Orts.Simulation/Simulation/RollingStocks/MSTSWagon.cs

@@ -411,6 +411,8 @@ public void Load()
         float LoadEmptyMaxBrakeForceN;
         float LoadEmptyMaxHandbrakeForceN;
         float LoadEmptyCentreOfGravityM_Y;
+        float LoadEmptyRelayValveRatio;
+        float LoadEmptyInshotPSI;
 
         float LoadFullMassKg;
         float LoadFullORTSDavis_A;
@@ -421,6 +423,8 @@ public void Load()
         float LoadFullMaxBrakeForceN;
         float LoadFullMaxHandbrakeForceN;
         float LoadFullCentreOfGravityM_Y;
+        float LoadFullRelayValveRatio;
+        float LoadFullInshotPSI;
 
 
         /// <summary>
@@ -787,6 +791,24 @@ public virtual void LoadFromWagFile(string wagFilePath)
                     LoadEmptyCentreOfGravityM_Y = CentreOfGravityM.Y;
                 }
 
+                if (FreightAnimations.EmptyRelayValveRatio > 0)
+                {
+                    LoadEmptyRelayValveRatio = FreightAnimations.EmptyRelayValveRatio;
+                }
+                else if (BrakeSystem is AirSinglePipe brakes)
+                {
+                    LoadEmptyRelayValveRatio = brakes.RelayValveRatio;
+                }
+
+                if (FreightAnimations.EmptyInshotPSI != 0)
+                {
+                    LoadEmptyInshotPSI = FreightAnimations.EmptyInshotPSI;
+                }
+                else if (BrakeSystem is AirSinglePipe brakes)
+                {
+                    LoadEmptyInshotPSI = brakes.RelayValveInshotPSI;
+                }
+
                 // Read (initialise) Static load ones if a static load
                 // Test each value to make sure that it has been defined in the WAG file, if not default to Root WAG file value
                 if (FreightAnimations.FullPhysicsStaticOne != null)
@@ -866,6 +888,24 @@ public virtual void LoadFromWagFile(string wagFilePath)
                     {
                         LoadFullCentreOfGravityM_Y = CentreOfGravityM.Y;
                     }
+
+                    if (FreightAnimations.FullPhysicsStaticOne.FullStaticRelayValveRatio > 0)
+                    {
+                        LoadFullRelayValveRatio = FreightAnimations.FullPhysicsStaticOne.FullStaticRelayValveRatio;
+                    }
+                    else if (BrakeSystem is AirSinglePipe brakes)
+                    {
+                        LoadFullRelayValveRatio = brakes.RelayValveRatio;
+                    }
+
+                    if (FreightAnimations.FullPhysicsStaticOne.FullStaticInshotPSI > 0)
+                    {
+                        LoadFullInshotPSI = FreightAnimations.FullPhysicsStaticOne.FullStaticInshotPSI;
+                    }
+                    else if (BrakeSystem is AirSinglePipe brakes)
+                    {
+                        LoadFullInshotPSI = brakes.RelayValveInshotPSI;
+                    }
                 }
 
                 // Read (initialise) Continuous load ones if a continuous load
@@ -956,6 +996,24 @@ public virtual void LoadFromWagFile(string wagFilePath)
                     {
                         LoadFullCentreOfGravityM_Y = CentreOfGravityM.Y;
                     }
+
+                    if (FreightAnimations.FullPhysicsContinuousOne.FullRelayValveRatio > 0)
+                    {
+                        LoadFullRelayValveRatio = FreightAnimations.FullPhysicsContinuousOne.FullRelayValveRatio;
+                    }
+                    else if (BrakeSystem is AirSinglePipe brakes)
+                    {
+                        LoadFullRelayValveRatio = brakes.RelayValveRatio;
+                    }
+
+                    if (FreightAnimations.FullPhysicsContinuousOne.FullInshotPSI != 0)
+                    {
+                        LoadFullInshotPSI = FreightAnimations.FullPhysicsContinuousOne.FullInshotPSI;
+                    }
+                    else if (BrakeSystem is AirSinglePipe brakes)
+                    {
+                        LoadFullInshotPSI = brakes.RelayValveInshotPSI;
+                    }
                 }
 
                 if (!FreightAnimations.MSTSFreightAnimEnabled) FreightShapeFileName = null;
@@ -978,6 +1036,11 @@ public virtual void LoadFromWagFile(string wagFilePath)
                         // Update brake parameters   
                         MaxBrakeForceN = LoadFullMaxBrakeForceN;
                         MaxHandbrakeForceN = LoadFullMaxHandbrakeForceN;
+                        if (BrakeSystem is AirSinglePipe brakes)
+                        {
+                            brakes.RelayValveRatio = LoadFullRelayValveRatio;
+                            brakes.RelayValveInshotPSI = LoadFullInshotPSI;
+                        }
 
                         // Update friction related parameters
                         DavisAN = LoadFullORTSDavis_A;
@@ -1002,6 +1065,12 @@ public virtual void LoadFromWagFile(string wagFilePath)
                     // Update brake parameters
                     MaxBrakeForceN = ((LoadFullMaxBrakeForceN - LoadEmptyMaxBrakeForceN) * TempMassDiffRatio) + LoadEmptyMaxBrakeForceN;
                     MaxHandbrakeForceN = ((LoadFullMaxHandbrakeForceN - LoadEmptyMaxHandbrakeForceN) * TempMassDiffRatio) + LoadEmptyMaxHandbrakeForceN;
+                    // Not sensible to vary the relay valve ratio continouously; instead, it changes to loaded if more than 25% cargo is present
+                    if (BrakeSystem is AirSinglePipe brakes)
+                    {
+                        brakes.RelayValveRatio = TempMassDiffRatio > 0.25f ? LoadFullRelayValveRatio : LoadEmptyRelayValveRatio;
+                        brakes.RelayValveInshotPSI = TempMassDiffRatio > 0.25f ? LoadFullInshotPSI : LoadEmptyInshotPSI;
+                    }
 
                     // Update friction related parameters
                     DavisAN = ((LoadFullORTSDavis_A - LoadEmptyORTSDavis_A) * TempMassDiffRatio) + LoadEmptyORTSDavis_A;
@@ -1030,6 +1099,11 @@ public virtual void LoadFromWagFile(string wagFilePath)
                         // Update brake physics
                         MaxBrakeForceN = LoadEmptyMaxBrakeForceN;
                         MaxHandbrakeForceN = LoadEmptyMaxHandbrakeForceN;
+                        if (BrakeSystem is AirSinglePipe brakes)
+                        {
+                            brakes.RelayValveRatio = LoadEmptyRelayValveRatio;
+                            brakes.RelayValveInshotPSI = LoadEmptyInshotPSI;
+                        }
 
                         // Update friction related parameters
                         DavisAN = LoadEmptyORTSDavis_A;
@@ -1713,6 +1787,8 @@ public virtual void Copy(MSTSWagon copy)
             LoadEmptyORTSDavis_C = copy.LoadEmptyORTSDavis_C;
             LoadEmptyDavisDragConstant = copy.LoadEmptyDavisDragConstant;
             LoadEmptyWagonFrontalAreaM2 = copy.LoadEmptyWagonFrontalAreaM2;
+            LoadEmptyRelayValveRatio = copy.LoadEmptyRelayValveRatio;
+            LoadEmptyInshotPSI = copy.LoadEmptyInshotPSI;
             LoadFullMassKg = copy.LoadFullMassKg;
             LoadFullCentreOfGravityM_Y = copy.LoadFullCentreOfGravityM_Y;
             LoadFullMaxBrakeForceN = copy.LoadFullMaxBrakeForceN;
@@ -1722,6 +1798,8 @@ public virtual void Copy(MSTSWagon copy)
             LoadFullORTSDavis_C = copy.LoadFullORTSDavis_C;
             LoadFullDavisDragConstant = copy.LoadFullDavisDragConstant;
             LoadFullWagonFrontalAreaM2 = copy.LoadFullWagonFrontalAreaM2;
+            LoadFullRelayValveRatio = copy.LoadFullRelayValveRatio;
+            LoadFullInshotPSI = copy.LoadFullInshotPSI;
 
             if (copy.IntakePointList != null)
             {
@@ -2125,6 +2203,12 @@ public override void Update(float elapsedClockSeconds)
                         // Update brake parameters
                         MaxBrakeForceN = ((LoadFullMaxBrakeForceN - LoadEmptyMaxBrakeForceN) * TempMassDiffRatio) + LoadEmptyMaxBrakeForceN;
                         MaxHandbrakeForceN = ((LoadFullMaxHandbrakeForceN - LoadEmptyMaxHandbrakeForceN) * TempMassDiffRatio) + LoadEmptyMaxHandbrakeForceN;
+                        // Not sensible to vary the relay valve ratio continouously; instead, it changes to loaded if more than 25% cargo is present
+                        if (BrakeSystem is AirSinglePipe brakes)
+                        {
+                            brakes.RelayValveRatio = TempMassDiffRatio > 0.25f ? LoadFullRelayValveRatio : LoadEmptyRelayValveRatio;
+                            brakes.RelayValveInshotPSI = TempMassDiffRatio > 0.25f ? LoadFullInshotPSI : LoadEmptyInshotPSI;
+                        }
                         // Update friction related parameters
                         DavisAN = ((LoadFullORTSDavis_A - LoadEmptyORTSDavis_A) * TempMassDiffRatio) + LoadEmptyORTSDavis_A;
                         DavisBNSpM = ((LoadFullORTSDavis_B - LoadEmptyORTSDavis_B) * TempMassDiffRatio) + LoadEmptyORTSDavis_B;
@@ -2232,6 +2316,12 @@ private void UpdateLocomotiveLoadPhysics()
                         // Update brake parameters
                         MaxBrakeForceN = ((LoadFullMaxBrakeForceN - LoadEmptyMaxBrakeForceN) * TempMassDiffRatio) + LoadEmptyMaxBrakeForceN;
                         MaxHandbrakeForceN = ((LoadFullMaxHandbrakeForceN - LoadEmptyMaxHandbrakeForceN) * TempMassDiffRatio) + LoadEmptyMaxHandbrakeForceN;
+                        // Not sensible to vary the relay valve ratio continouously; instead, it changes to loaded if more than 25% cargo is present
+                        if (BrakeSystem is AirSinglePipe brakes)
+                        {
+                            brakes.RelayValveRatio = TempMassDiffRatio > 0.25f ? LoadFullRelayValveRatio : LoadEmptyRelayValveRatio;
+                            brakes.RelayValveInshotPSI = TempMassDiffRatio > 0.25f ? LoadFullInshotPSI : LoadEmptyInshotPSI;
+                        }
                         // Update friction related parameters
                         DavisAN = ((LoadFullORTSDavis_A - LoadEmptyORTSDavis_A) * TempMassDiffRatio) + LoadEmptyORTSDavis_A;
                         DavisBNSpM = ((LoadFullORTSDavis_B - LoadEmptyORTSDavis_B) * TempMassDiffRatio) + LoadEmptyORTSDavis_B;
@@ -2278,6 +2368,12 @@ private void UpdateLocomotiveLoadPhysics()
                         // Update brake parameters
                         MaxBrakeForceN = ((LoadFullMaxBrakeForceN - LoadEmptyMaxBrakeForceN) * TempMassDiffRatio) + LoadEmptyMaxBrakeForceN;
                         MaxHandbrakeForceN = ((LoadFullMaxHandbrakeForceN - LoadEmptyMaxHandbrakeForceN) * TempMassDiffRatio) + LoadEmptyMaxHandbrakeForceN;
+                        // Not sensible to vary the relay valve ratio continouously; instead, it changes to loaded if more than 25% cargo is present
+                        if (BrakeSystem is AirSinglePipe brakes)
+                        {
+                            brakes.RelayValveRatio = TempMassDiffRatio > 0.25f ? LoadFullRelayValveRatio : LoadEmptyRelayValveRatio;
+                            brakes.RelayValveInshotPSI = TempMassDiffRatio > 0.25f ? LoadFullInshotPSI : LoadEmptyInshotPSI;
+                        }
                         // Update friction related parameters
                         DavisAN = ((LoadFullORTSDavis_A - LoadEmptyORTSDavis_A) * TempMassDiffRatio) + LoadEmptyORTSDavis_A;
                         DavisBNSpM = ((LoadFullORTSDavis_B - LoadEmptyORTSDavis_B) * TempMassDiffRatio) + LoadEmptyORTSDavis_B;
@@ -3220,6 +3316,12 @@ private void UpdateTenderLoad()
                     // Update brake parameters
                     MaxBrakeForceN = ((LoadFullMaxBrakeForceN - LoadEmptyMaxBrakeForceN) * TempTenderMassDiffRatio) + LoadEmptyMaxBrakeForceN;
                     MaxHandbrakeForceN = ((LoadFullMaxHandbrakeForceN - LoadEmptyMaxHandbrakeForceN) * TempTenderMassDiffRatio) + LoadEmptyMaxHandbrakeForceN;
+                    // Not sensible to vary the relay valve ratio continouously; instead, it changes to loaded if more than 25% cargo is present
+                    if (BrakeSystem is AirSinglePipe brakes)
+                    {
+                        brakes.RelayValveRatio = TempTenderMassDiffRatio > 0.25f ? LoadFullRelayValveRatio : LoadEmptyRelayValveRatio;
+                        brakes.RelayValveInshotPSI = TempTenderMassDiffRatio > 0.25f ? LoadFullInshotPSI : LoadEmptyInshotPSI;
+                    }
                     // Update friction related parameters
                     DavisAN = ((LoadFullORTSDavis_A - LoadEmptyORTSDavis_A) * TempTenderMassDiffRatio) + LoadEmptyORTSDavis_A;
                     DavisBNSpM = ((LoadFullORTSDavis_B - LoadEmptyORTSDavis_B) * TempTenderMassDiffRatio) + LoadEmptyORTSDavis_B;
@@ -3253,6 +3355,12 @@ private void UpdateTenderLoad()
                     // Update brake parameters
                     MaxBrakeForceN = ((LoadFullMaxBrakeForceN - LoadEmptyMaxBrakeForceN) * TempTenderMassDiffRatio) + LoadEmptyMaxBrakeForceN;
                     MaxHandbrakeForceN = ((LoadFullMaxHandbrakeForceN - LoadEmptyMaxHandbrakeForceN) * TempTenderMassDiffRatio) + LoadEmptyMaxHandbrakeForceN;
+                    // Not sensible to vary the relay valve ratio continouously; instead, it changes to loaded if more than 25% cargo is present
+                    if (BrakeSystem is AirSinglePipe brakes)
+                    {
+                        brakes.RelayValveRatio = TempTenderMassDiffRatio > 0.25f ? LoadFullRelayValveRatio : LoadEmptyRelayValveRatio;
+                        brakes.RelayValveInshotPSI = TempTenderMassDiffRatio > 0.25f ? LoadFullInshotPSI : LoadEmptyInshotPSI;
+                    }
                     // Update friction related parameters
                     DavisAN = ((LoadFullORTSDavis_A - LoadEmptyORTSDavis_A) * TempTenderMassDiffRatio) + LoadEmptyORTSDavis_A;
                     DavisBNSpM = ((LoadFullORTSDavis_B - LoadEmptyORTSDavis_B) * TempTenderMassDiffRatio) + LoadEmptyORTSDavis_B;