Automatic merge of T1.5.1-1885-g12b1a74d5 and 7 pull requests

- Pull request #570 at 362e4e7: glTF 2.0 support with PBR lighting
- Pull request #1085 at 37e2817: updates key commands for Train Operations window and also Daylight Offset
- Pull request #1086 at e10390b: Add Settings Exporter tool (copy settings to INI, etc)
- Pull request #1094 at e6e95f1: Blended Braking Compatibility and Effectiveness Improvements
- Pull request #1082 at 5845a1a: Allow variable water level in glass gauge
- Pull request #1081 at 689494b: Brake cuts power unification
- Pull request #1091 at b0c622b: Automatic speed control

Author: openrails-bot

Source/Documentation/Manual/physics.rst

@@ -3343,6 +3343,8 @@ the following parameters will adjust the behaviour of air brakes:
 .. index::
    single: DynamicBrakeHasAutoBailOff
    single: ORTSDynamicBrakesHasPartialBailOff
+   single: ORTSDynamicBlendingRetainedPressure
+   single: ORTSDynamicBlendingMinimumSpeed
    single: ORTSTrainDynamicBlendingTable
    single: ORTSDynamicBrakeReplacementWithEngineBrake 
    single: ORTSDynamicBrakeReplacementWithEngineBrakeAtSpeed
@@ -3353,6 +3355,13 @@ the following parameters will adjust the behaviour of air brakes:
   air brakes are released while dynamic brakes satisfy the train brake demand.
   If dynamic braking is not sufficient, air brakes will be partially applied
   so the combination air+dynamic provides the required brake demand.
+- ``Engine(ORTSDynamicBlendingRetainedPressure`` -- Sets the brake cylinder
+  pressure which, when used in combination with ORTSDynamicBrakesHasPartialBailOff,
+  will remain applied regardless of the blended dynamic brake force. This
+  pressure is also the minimum pressure at which the blended braking system will activate.
+- ``Engine(ORTSDynamicBlendingMinimumSpeed`` -- Below the specified speed
+  (default units mph, default value 5 mph / 8 kph), local dynamic brake blending
+  will be disabled, allowing locomotive brakes to hold the train while stopped.
 
 Sometimes the train brake controller is capable to apply the dynamic
 brakes for the whole consist, usually as a first step before air brakes

Source/Orts.Simulation/Simulation/RollingStocks/MSTSLocomotive.cs

@@ -419,6 +419,8 @@ public float OdometerM
         public double? DynamicBrakeCommandStartTime;
         protected bool DynamicBrakeBlendingOverride; // true when DB lever >0% should always override the blending. When false, the bigger command is applied.
         protected bool DynamicBrakeBlendingForceMatch = true; // if true, dynamic brake blending tries to achieve the same braking force as the airbrake would have.
+        public float DynamicBrakeBlendingRetainedPressurePSI { get; private set; } = -1.0f; // the amount of pressure that will always be retained in the brake cylinders during blended braking
+        public float DynamicBrakeBlendingMinSpeedMpS { get; private set; } = 2.25f; // below this speed, blended braking is disabled
         protected bool DynamicBrakeControllerSetupLock; // if true if dynamic brake lever will lock until dynamic brake is available
 
         public float DynamicBrakeBlendingPercent { get; protected set; } = -1;
@@ -1098,6 +1100,7 @@ public override void Parse(string lowercasetoken, STFReader stf)
                 case "engine(ortsdynamicbrakeshaspartialbailoff": DynamicBrakePartialBailOff = stf.ReadBoolBlock(false); break;
                 case "engine(ortsdynamicbrakereplacementwithenginebrake": DynamicBrakeEngineBrakeReplacement = stf.ReadBoolBlock(false); break;
                 case "engine(ortsdynamicbrakereplacementwithenginebrakeatspeed": DynamicBrakeEngineBrakeReplacementSpeed = stf.ReadFloatBlock(STFReader.UNITS.SpeedDefaultMPH, null); break;
+                case "engine(ortsdynamicblendingminimumspeed": DynamicBrakeBlendingMinSpeedMpS = stf.ReadFloatBlock(STFReader.UNITS.SpeedDefaultMPH, null); break;
                 case "engine(dynamicbrakesdelaytimebeforeengaging": DynamicBrakeDelayS = stf.ReadFloatBlock(STFReader.UNITS.Time, null); break;
                 case "engine(dynamicbrakesresistorcurrentlimit": DynamicBrakeMaxCurrentA = stf.ReadFloatBlock(STFReader.UNITS.Current, null); break;
                 case "engine(numwheels": MSTSLocoNumDrvWheels = stf.ReadFloatBlock(STFReader.UNITS.None, 4.0f); if (MSTSLocoNumDrvWheels < 1) STFException.TraceWarning(stf, "Engine:NumWheels is less than 1, parts of the simulation may not function correctly"); break;
@@ -1178,6 +1181,7 @@ public override void Parse(string lowercasetoken, STFReader stf)
                     break;
                 case "engine(ortsdynamicblendingoverride": DynamicBrakeBlendingOverride = stf.ReadBoolBlock(false); break;
                 case "engine(ortsdynamicblendingforcematch": DynamicBrakeBlendingForceMatch = stf.ReadBoolBlock(false); break;
+                case "engine(ortsdynamicblendingretainedpressure": DynamicBrakeBlendingRetainedPressurePSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, null); break;
                 case "engine(vacuumbrakeshasvacuumpump": VacuumPumpFitted = stf.ReadBoolBlock(false); break;
                 case "engine(enginecontrollers(ortssteamheat": SteamHeatController.Parse(stf); break;
                 case "engine(name": stf.MustMatch("("); LocomotiveName = stf.ReadString(); break;
@@ -1264,6 +1268,7 @@ public override void Copy(MSTSWagon copy)
             DynamicBrakePartialBailOff = locoCopy.DynamicBrakePartialBailOff;
             DynamicBrakeEngineBrakeReplacement = locoCopy.DynamicBrakeEngineBrakeReplacement;
             DynamicBrakeEngineBrakeReplacementSpeed = locoCopy.DynamicBrakeEngineBrakeReplacementSpeed;
+            DynamicBrakeBlendingMinSpeedMpS = locoCopy.DynamicBrakeBlendingMinSpeedMpS;
             DynamicBrakeMaxCurrentA = locoCopy.DynamicBrakeMaxCurrentA;
             DynamicBrakeSpeed1MpS = locoCopy.DynamicBrakeSpeed1MpS;
             DynamicBrakeSpeed2MpS = locoCopy.DynamicBrakeSpeed2MpS;
@@ -1335,6 +1340,7 @@ public override void Copy(MSTSWagon copy)
             DynamicBrakeCommandStartTime = locoCopy.DynamicBrakeCommandStartTime;
             DynamicBrakeBlendingOverride = locoCopy.DynamicBrakeBlendingOverride;
             DynamicBrakeBlendingForceMatch = locoCopy.DynamicBrakeBlendingForceMatch;
+            DynamicBrakeBlendingRetainedPressurePSI = locoCopy.DynamicBrakeBlendingRetainedPressurePSI;
             DynamicBrakeControllerSetupLock = locoCopy.DynamicBrakeControllerSetupLock;
 
             MainPressureUnit = locoCopy.MainPressureUnit;
@@ -2015,6 +2021,15 @@ protected void CorrectBrakingParams()
                 (MaxDynamicBrakeForceN / MaxContinuousForceN < 0.3f && MaxDynamicBrakeForceN == 20000))
                     MaxDynamicBrakeForceN = Math.Min (MaxContinuousForceN * 0.5f, 150000); // 20000 is suggested as standard value in the MSTS documentation, but in general it is a too low value
             }
+
+            // Define blending retained pressure if it was left undefined
+            if (DynamicBrakeBlendingRetainedPressurePSI < 0)
+            {
+                if (BrakeSystem is AirSinglePipe airSystem)
+                    DynamicBrakeBlendingRetainedPressurePSI = 2.0f * airSystem.BrakeCylinderSpringPressurePSI;
+                else
+                    DynamicBrakeBlendingRetainedPressurePSI = 0.0f;
+            }
         }
 
         /// <summary>
@@ -2023,24 +2038,43 @@ protected void CorrectBrakingParams()
         public void DynamicBrakeBlending(float elapsedClockSeconds)
         {
             // Local blending
-            if (Math.Abs(SpeedMpS) > DynamicBrakeSpeed1MpS && airPipeSystem != null && airPipeSystem.AutoCylPressurePSI > 0.1f
+            if (airPipeSystem == null)
+            {
+                DynamicBrakeBlendingPercent = -1;
+                return;
+            }
+            float autoDemandedPressurePSI = airPipeSystem.AutoCylPressurePSI * airPipeSystem.RelayValveRatio;
+
+            if (Math.Abs(SpeedMpS) > DynamicBrakeBlendingMinSpeedMpS && autoDemandedPressurePSI > DynamicBrakeBlendingRetainedPressurePSI
                 && ThrottlePercent == 0 && !(DynamicBrakeController != null && DynamicBrakeBlendingOverride && DynamicBrakeController.SavedValue > 0))
             {
-                float maxCylPressurePSI = airPipeSystem.GetMaxCylPressurePSI();
-                float target = airPipeSystem.AutoCylPressurePSI * airPipeSystem.RelayValveRatio / maxCylPressurePSI;
+                float target = (autoDemandedPressurePSI - DynamicBrakeBlendingRetainedPressurePSI) /
+                    (airPipeSystem.ReferencePressurePSI - DynamicBrakeBlendingRetainedPressurePSI);
 
                 if (DynamicBrakeBlendingForceMatch)
                 {
+                    if (DynamicBrake)
+                    {
                     float diff = target * FrictionBrakeBlendingMaxForceN - DynamicBrakeForceN;
-                    float threshold = 100;
-                    if (diff > threshold && DynamicBrakePercent < 100)
-                        DynamicBrakeBlendingPercent = Math.Min(DynamicBrakePercent + 100 * elapsedClockSeconds, 100);
-                    else if (diff < -threshold && DynamicBrakePercent > 1)
-                        DynamicBrakeBlendingPercent = Math.Max(DynamicBrakePercent - 100 * elapsedClockSeconds, 1);
+                        float normDiff = diff / MaxDynamicBrakeForceN;
+
+                        if (Math.Abs(diff) > 100.0f)
+                        {
+                            // Limit rate of change to reduce overshoots
+                            if (diff > 0 && DynamicBrakeForceRampUpNpS > 0)
+                                normDiff = Math.Min(normDiff, DynamicBrakeForceRampUpNpS / MaxDynamicBrakeForceN);
+                            if (diff < 0 && DynamicBrakeForceRampDownNpS > 0)
+                                normDiff = Math.Max(normDiff, -DynamicBrakeForceRampDownNpS / MaxDynamicBrakeForceN);
+
+                            DynamicBrakeBlendingPercent = MathHelper.Clamp(DynamicBrakePercent + 100.0f * normDiff * elapsedClockSeconds, 1f, 100f);
+                        }
+                    }
+                    else // Don't increase dynamic brake setting until set-up has completed
+                        DynamicBrakeBlendingPercent = 1.0f;
                 }
                 else
                 {
-                    DynamicBrakeBlendingPercent = target * 100;
+                    DynamicBrakeBlendingPercent = MathHelper.Clamp(target * 100, 1f, 100f);
                 }
             }
             else

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/AirSinglePipe.cs

@@ -81,7 +81,7 @@ public enum BrakeValveType
         protected float ControlResPressurePSI = 64;
         protected float FullServPressurePSI = 50;
         protected float MaxCylPressurePSI;
-        protected float ReferencePressurePSI;
+        public float ReferencePressurePSI { get; protected set; }
         protected float MaxTripleValveCylPressurePSI;
         protected float AuxResVolumeM3;
         protected float AuxCylVolumeRatio;
@@ -143,7 +143,7 @@ public enum BrakeValveType
         protected float AcceleratedApplicationLimitPSIpS = 5.0f;
         protected float InitialApplicationThresholdPSI;
         protected float TripleValveSensitivityPSI;
-        protected float BrakeCylinderSpringPressurePSI;
+        public float BrakeCylinderSpringPressurePSI { get; protected set; }
         protected float ServiceMaxCylPressurePSI;
         protected float ServiceApplicationRatePSIpS;
         protected float TwoStageLowPressurePSI;
@@ -1733,25 +1733,21 @@ public override void Update(float elapsedClockSeconds)
                             if (loco.Train.DetermineDPLeadLocomotive(loco) is MSTSLocomotive lead && (lead.BailOff || (lead.EngineBrakeController != null && lead.EngineBrakeController.TrainBrakeControllerState == ControllerState.BailOff)))
                             {
                                 if (BrakeValve == BrakeValveType.Distributor)
-                                {
                                     ControlResPressurePSI = 0;
 
-                                    if (loco.AttachedTender?.BrakeSystem is AirSinglePipe tenderBrakes)
-                                        tenderBrakes.ControlResPressurePSI = 0;
-                                }
-                                else
+                                float dp = Math.Max(MaxReleaseRatePSIpS, loco.EngineBrakeReleaseRatePSIpS) * elapsedClockSeconds;
+                                AutoCylPressurePSI -= dp;
+                                if (AutoCylPressurePSI < 0)
+                                    AutoCylPressurePSI = 0;
+
+                                if (loco.AttachedTender?.BrakeSystem is AirSinglePipe tenderBrakes)
                                 {
-                                    float dp = Math.Max(MaxReleaseRatePSIpS, loco.EngineBrakeReleaseRatePSIpS) * elapsedClockSeconds;
-                                    AutoCylPressurePSI -= dp;
-                                    if (AutoCylPressurePSI < 0)
-                                        AutoCylPressurePSI = 0;
+                                    if (tenderBrakes.BrakeValve == BrakeValveType.Distributor)
+                                        tenderBrakes.ControlResPressurePSI = 0;
 
-                                    if (loco.AttachedTender?.BrakeSystem is AirSinglePipe tenderBrakes)
-                                    {
-                                        tenderBrakes.AutoCylPressurePSI -= dp;
-                                        if (tenderBrakes.AutoCylPressurePSI < 0)
-                                            tenderBrakes.AutoCylPressurePSI = 0;
-                                    }
+                                    tenderBrakes.AutoCylPressurePSI -= dp;
+                                    if (tenderBrakes.AutoCylPressurePSI < 0)
+                                        tenderBrakes.AutoCylPressurePSI = 0;
                                 }
                             }
                         }
@@ -1762,19 +1758,23 @@ public override void Update(float elapsedClockSeconds)
                         {
                             if (loco.DynamicBrakePartialBailOff)
                             {
-                                var requiredBrakeForceN = MathHelper.Max((AutoCylPressurePSI * RelayValveRatio - BrakeCylinderSpringPressurePSI)
-                                    / (ReferencePressurePSI - BrakeCylinderSpringPressurePSI), 0) * Car.FrictionBrakeBlendingMaxForceN;
-                                var localBrakeForceN = loco.DynamicBrakeForceN + MathHelper.Max((CylPressurePSI - BrakeCylinderSpringPressurePSI)
-                                    / (ReferencePressurePSI - BrakeCylinderSpringPressurePSI), 0) * Car.FrictionBrakeBlendingMaxForceN;
+                                var requiredBrakeForceN = (AutoCylPressurePSI * RelayValveRatio - loco.DynamicBrakeBlendingRetainedPressurePSI)
+                                    / (ReferencePressurePSI - loco.DynamicBrakeBlendingRetainedPressurePSI) * Car.FrictionBrakeBlendingMaxForceN;
+                                var localBrakeForceN = loco.DynamicBrakeForceN + (CylPressurePSI - loco.DynamicBrakeBlendingRetainedPressurePSI)
+                                    / (ReferencePressurePSI - loco.DynamicBrakeBlendingRetainedPressurePSI) * Car.FrictionBrakeBlendingMaxForceN;
                                 if (localBrakeForceN > requiredBrakeForceN - 0.15f * Car.FrictionBrakeBlendingMaxForceN)
                                 {
-                                    demandedPressurePSI = Math.Min(Math.Max((requiredBrakeForceN - loco.DynamicBrakeForceN) / Car.FrictionBrakeBlendingMaxForceN * ReferencePressurePSI
-                                        + BrakeCylinderSpringPressurePSI, 0), MaxCylPressurePSI);
+                                    demandedPressurePSI = MathHelper.Clamp((requiredBrakeForceN - loco.DynamicBrakeForceN) / Car.FrictionBrakeBlendingMaxForceN *
+                                        (ReferencePressurePSI - loco.DynamicBrakeBlendingRetainedPressurePSI) + loco.DynamicBrakeBlendingRetainedPressurePSI,
+                                        loco.DynamicBrakeBlendingRetainedPressurePSI, MaxCylPressurePSI);
                                     if (demandedPressurePSI > CylPressurePSI && demandedPressurePSI < CylPressurePSI + 4) // Allow some margin for unnecessary air brake application
                                     {
                                         demandedPressurePSI = CylPressurePSI;
                                     }
                                     demandedPressurePSI /= RelayValveRatio;
+
+                                    if (demandedPressurePSI > AutoCylPressurePSI)
+                                        demandedPressurePSI = AutoCylPressurePSI;
                                 }
                             }
                             else if (loco.DynamicBrakeAutoBailOff)
@@ -1938,7 +1938,7 @@ public override void Update(float elapsedClockSeconds)
                 }
 
             }
-
+                       
             if (Car is MSTSLocomotive) UpdateTractionCutoff();
 
             // Record HUD display values for brake cylinders depending upon whether they are wagons or locomotives/tenders (which are subject to their own engine brakes)