Automatic merge of T1.5.1-969-g2319f7f14 and 15 pull requests

- Pull request #799 at dfc715e: Consolidated wind simulation
- Pull request #839 at d00beb9: First phase of https://blueprints.launchpad.net/or/+spec/additional-cruise-control-parameters
- Pull request #876 at f92de76: docs: add source for documents previously on website to source Documentation folder
- Pull request #882 at 48aa537: Blueprint/train car operations UI window
- Pull request #891 at 9a1d6b2: Auto save
- Pull request #892 at 1f5ba4c: Signal Function OPP_SIG_ID_TRAINPATH
- Pull request #896 at 5866028: First implementation of https://blueprints.launchpad.net/or/+spec/specific-sounds-for-ai-trains
- Pull request #900 at c27f32d: DMI updates
- Pull request #903 at c296b32: Downloading route content (Github, zip)
- Pull request #912 at 0cb07c2: New Triple Valve Features Vol. 2
- Pull request #918 at c46eb0d: Manual - News topics updated since 1.5.1
- Pull request #919 at 26cc6a8: Added mouse wheel support for controls which can be moved by pressing t…
- Pull request #922 at abe2e52: Autopilot for timetable mode
- Pull request #923 at 4c27204: Add curve squeal to route
- Pull request #943 at de1bccb: Dynamic Brakes Behavior & Display Improvements

Author: openrails-bot

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

@@ -2108,10 +2108,10 @@ public override void Update(float elapsedClockSeconds)
                     if (DynamicBrakeCommandStartTime + DynamicBrakeDelayS < Simulator.ClockTime)
                     {
                         DynamicBrake = true; // Engage
-                        if (IsLeadLocomotive() && DynamicBrakeController.CurrentValue > 0)
+                        if (IsLeadLocomotive() && DynamicBrakeController?.CurrentValue > 0)
                             Simulator.Confirmer.ConfirmWithPerCent(CabControl.DynamicBrake, DynamicBrakeController.CurrentValue * 100);
                     }
-                    else if (IsLeadLocomotive() && DynamicBrakeController.CurrentValue > 0)
+                    else if (IsLeadLocomotive() && DynamicBrakeController?.CurrentValue > 0)
                         Simulator.Confirmer.Confirm(CabControl.DynamicBrake, CabSetting.On); // Keeping status string on screen so user knows what's happening
                 }
             }
@@ -2396,24 +2396,31 @@ protected virtual void UpdateControllers(float elapsedClockSeconds)
             {
                 LocalDynamicBrakePercent = TrainBrakeController.TrainDynamicBrakeIntervention * 100;
             }
-            if (DynamicBrakeController != null && DynamicBrakeController.CurrentValue > 0)
+            if (DynamicBrakeController != null && (DynamicBrakeController.CurrentValue > 0 || DynamicBrakeController.UpdateValue > 0))
             {
                 float prevValue = DynamicBrakeController.CurrentValue;
+
                 if (DynamicBrake || !DynamicBrakeControllerSetupLock)
                     DynamicBrakeController.Update(elapsedClockSeconds);
-                // Dynamic brake is about to be disabled, pause motion of controller to prevent accidental shut-off
-                if (DynamicBrakeController.CurrentValue <= 0)
+
+                // Dynamic brake is about to be enabled or disabled, pause motion of controller to prevent accidental overshooting
+                if ((DynamicBrakeController.CurrentValue <= 0 && prevValue > 0) || (DynamicBrakeController.CurrentValue > 0 && prevValue <= 0))
                 {
                     if (!DynamicBrakePause)
                     {
                         DynamicBrakePause = true;
-                        StopDynamicBrakeDecrease();
-                        DynamicBrakeController.CurrentValue = prevValue;
+                        if (DynamicBrakeController.UpdateValue < 0)
+                        {
+                            StopDynamicBrakeDecrease();
+                            DynamicBrakeController.CurrentValue = prevValue;
+                        }
+                        else if (DynamicBrakeController.UpdateValue > 0)
+                            StopDynamicBrakeIncrease();
                 }
                 else
                         DynamicBrakePause = false;
                 }
-                else if (DynamicBrakeController.CurrentValue > prevValue)
+                else if (DynamicBrakeController.UpdateValue != 0)
                     DynamicBrakePause = false;
 
                 LocalDynamicBrakePercent = Math.Max(DynamicBrakeController.CurrentValue * 100, LocalDynamicBrakePercent);
@@ -4100,7 +4107,7 @@ public void SetCombinedHandleValue(float value)
                 ThrottleController.IntermediateValue = 0;
             }
             // Return to throttling
-            else if ((DynamicBrakeController.CurrentValue <= 0 && value < CombinedControlSplitPosition) ||
+            else if ((DynamicBrakeController?.CurrentValue ?? 0) <= 0 ||
                     (CruiseControl != null && !CruiseControl.DynamicBrakePriority && CruiseControl.SpeedRegMode == CruiseControl.SpeedRegulatorMode.Auto))
             {
                     SetThrottleValue(1 - MathHelper.Clamp(value, 0, CombinedControlSplitPosition) / CombinedControlSplitPosition);
@@ -4120,9 +4127,9 @@ public void SetCombinedHandleValue(float value)
         /// <returns>Combined position into 0-1 range, where arrangement is [[1--throttle--0]split[0--dynamic|airbrake--1]]</returns>
         public float GetCombinedHandleValue(bool intermediateValue)
         {
-            float throttleValue = intermediateValue ? ThrottleController.IntermediateValue : ThrottleController.CurrentValue;
-            float dynamicsValue = intermediateValue ? DynamicBrakeController.IntermediateValue : DynamicBrakeController.CurrentValue;
-            float brakesValue = intermediateValue ? TrainBrakeController.IntermediateValue : TrainBrakeController.CurrentValue;
+            var throttleValue = intermediateValue ? ThrottleController?.IntermediateValue : ThrottleController?.CurrentValue;
+            var dynamicsValue = intermediateValue ? DynamicBrakeController?.IntermediateValue : DynamicBrakeController?.CurrentValue;
+            var brakesValue = intermediateValue ? TrainBrakeController?.IntermediateValue : TrainBrakeController?.CurrentValue;
 
             if (CruiseControl?.SpeedRegMode == CruiseControl.SpeedRegulatorMode.Auto)
             {
@@ -4144,14 +4151,14 @@ public float GetCombinedHandleValue(bool intermediateValue)
                 if (CruiseControl != null && CruiseControl.SkipThrottleDisplay && !CruiseControl.DynamicBrakeCommandHasPriorityOverCruiseControl)
                         return CombinedControlSplitPosition;
                     else
-                    return CombinedControlSplitPosition + (1 - CombinedControlSplitPosition) * dynamicsValue;
+                    return CombinedControlSplitPosition + (1 - CombinedControlSplitPosition) * (dynamicsValue ?? 0);
                     }
             else if (CombinedControlType == CombinedControl.ThrottleAir && throttleValue <= 0 && brakesValue > 0)
-                return CombinedControlSplitPosition + (1 - CombinedControlSplitPosition) * brakesValue;
+                return CombinedControlSplitPosition + (1 - CombinedControlSplitPosition) * (brakesValue ?? 0);
             else if (CruiseControl == null)
-                return CombinedControlSplitPosition * (1 - throttleValue);
+                return CombinedControlSplitPosition * (1 - (throttleValue ?? 0));
             else if (CruiseControl.SpeedRegMode == CruiseControl.SpeedRegulatorMode.Manual)
-                return CombinedControlSplitPosition * (1 - throttleValue);
+                return CombinedControlSplitPosition * (1 - (throttleValue ?? 0));
             else if (CruiseControl.UseThrottleAsSpeedSelector)
                 return CombinedControlSplitPosition * (1 - (CruiseControl.SelectedSpeedMpS / MaxSpeedMpS));
             else if (CruiseControl.UseThrottleAsForceSelector && CruiseControl.UseThrottleInCombinedControl)
@@ -4729,6 +4736,8 @@ public void StartDynamicBrakeIncrease(float? target)
             // Only allow increasing dynamic brake if dynamic braking is off, there's no setup lock, or dynamic braking is already active
             if (DynamicBrake || !DynamicBrakeControllerSetupLock || DynamicBrakeController.CurrentValue <= 0)
             {
+                float prevValue = DynamicBrakeController.CurrentValue;
+
                 DynamicBrakeController.StartIncrease(target);
 
                 AlerterReset(TCSEvent.DynamicBrakeChanged);
@@ -4738,6 +4747,12 @@ public void StartDynamicBrakeIncrease(float? target)
                     StopDynamicBrakeIncrease();
                     Simulator.Confirmer.ConfirmWithPerCent(CabControl.DynamicBrake, DynamicBrakeController.CurrentValue * 100);
                 }
+                // If this is the first application of dynamics, pause movement to prevent accidental over-application
+                else if (DynamicBrakeController.CurrentValue > 0 && prevValue <= 0)
+                {
+                    DynamicBrakePause = true;
+                    StopDynamicBrakeIncrease();
+                }
             }
         }
 
@@ -4865,7 +4880,8 @@ public void SetDynamicBrakePercentWithSound(float percent)
 
         public bool CheckDisableDynamicBrake()
         {
-            if (DynamicBrakeController.CurrentValue <= 0)
+            // Only disable the dynamic brake if the lever is in the off position and the controller isn't trying to increase
+            if (DynamicBrakeController.CurrentValue <= 0 && DynamicBrakeController.UpdateValue <= 0)
             {
                 StopDynamicBrakeDecrease();
                 Simulator.Confirmer.Confirm(CabControl.DynamicBrake, CabSetting.Off);

Source/RunActivity/Viewer3D/RollingStock/MSTSLocomotiveViewer.cs

@@ -124,7 +124,7 @@ protected virtual void ReverserControlForwards()
         {
             if (Locomotive.Direction != Direction.Forward
             && (Locomotive.ThrottlePercent >= 1
-            || Math.Abs(Locomotive.SpeedMpS) > 1 || Locomotive.DynamicBrakeController.CurrentValue > 0))
+            || Math.Abs(Locomotive.SpeedMpS) > 1 || Locomotive.DynamicBrakeController?.CurrentValue > 0))
             {
                 Viewer.Simulator.Confirmer.Warning(CabControl.Reverser, CabSetting.Warn1);
                 return;
@@ -136,7 +136,7 @@ protected virtual void ReverserControlBackwards()
         {
             if (Locomotive.Direction != Direction.Reverse
             && (Locomotive.ThrottlePercent >= 1
-            || Math.Abs(Locomotive.SpeedMpS) > 1 || Locomotive.DynamicBrakeController.CurrentValue > 0))
+            || Math.Abs(Locomotive.SpeedMpS) > 1 || Locomotive.DynamicBrakeController?.CurrentValue > 0))
             {
                 Viewer.Simulator.Confirmer.Warning(CabControl.Reverser, CabSetting.Warn1);
                 return;
@@ -2220,22 +2220,12 @@ public virtual int GetDrawIndex()
                 case CABViewControlTypes.DYNAMIC_BRAKE_DISPLAY:
                     var dynBrakePercent = (Locomotive.Train.TrainType == Train.TRAINTYPE.AI_PLAYERHOSTING || Locomotive.Train.Autopilot) ?
                         Locomotive.DynamicBrakePercent : Locomotive.LocalDynamicBrakePercent;
-                    if (Locomotive.DynamicBrakeController != null)
-                    {
-                        if (dynBrakePercent <= 0)
-                        {
+                    if (dynBrakePercent <= 0)
                             index = 0;
-                            break;
-                        }
-                        if (!Locomotive.HasSmoothStruc)
-                            index = Locomotive.DynamicBrakeController != null ? Locomotive.DynamicBrakeController.CurrentNotch : 0;
+                    else if (!Locomotive.HasSmoothStruc && Locomotive.DynamicBrakeController != null)
+                        index = Locomotive.DynamicBrakeController.CurrentNotch;
                                 else
                                     index = PercentToIndex(dynBrakePercent);
-                            }
-                            else
-                    {
-                        index = PercentToIndex(dynBrakePercent);
-                    }
                     break;
                 case CABViewControlTypes.CPH_DISPLAY:
                     if (Locomotive.CombinedControlType == MSTSLocomotive.CombinedControl.ThrottleDynamic && Locomotive.DynamicBrakePercent >= 0)