Refactoring and comments

Author: cesarBLG

Source/Orts.Simulation/Simulation/RollingStocks/MSTSDieselLocomotive.cs

@@ -639,7 +639,9 @@ public override float GetAvailableTractionForceN(float t)
             if (t <= 0) return 0;
             if (DieselEngines.HasGearBox && (TractiveForceCurves == null || DieselTransmissionType == MSTSDieselLocomotive.DieselTransmissionTypes.Mechanic))
             {
-                return base.GetAvailableTractionForceN(t); // TODO: provide more accurate values
+                // TODO: provide more accurate values
+                // Note: if this clause is fulfilled, this method is not used to calculate TractiveForceN, it just provides information for other subsystems about theoretical tractive force
+                return base.GetAvailableTractionForceN(t);
             }
             float forceN = 0;
             float powerW = float.MaxValue;
@@ -658,6 +660,9 @@ public override float GetAvailableTractionForceN(float t)
             {
                 powerW = DieselPowerSupply.MaximumPowerW * t;
             }
+            // This section calculates the traction force of the locomotive as follows:
+            // Basic configuration (no TF table) - uses P = F /speed  relationship - requires power and force parameters to be set in the ENG file. 
+            // Advanced configuration (TF table) - use a user defined tractive force table
             if (TractiveForceCurves == null)
             {
                 // This sets the maximum force of the locomotive, it will be adjusted down if it exceeds the max power of the locomotive.
@@ -692,32 +697,7 @@ protected override void UpdateTractionForce(float elapsedClockSeconds)
                 TractiveForceN = TractionForceN = DieselEngines.TractiveForceN;
                 return;
             }
-            float t = ThrottlePercent / 100;
-
-            float maxthrottle = MaxThrottlePercent / 100;
-            if (IsPlayerTrain) maxthrottle = Math.Min(maxthrottle, DieselEngines.ApparentThrottleSetting / 100.0f);
-            if (t > maxthrottle) t = maxthrottle;
-            t = MathHelper.Clamp(t, 0, 1);
-
-            // This section calculates the traction force of the locomotive as follows:
-            // Basic configuration (no TF table) - uses P = F /speed  relationship - requires power and force parameters to be set in the ENG file. 
-            // Advanced configuration (TF table) - use a user defined tractive force table
-            if (maxthrottle > 0 && Direction != Direction.N && LocomotivePowerSupply.MainPowerSupplyOn)
-            {
-                float targetForceN = GetAvailableTractionForceN(t);
-                float limitForceN = GetAvailableTractionForceN(maxthrottle);
-                float maxForceN = float.MaxValue;
-                if (limitForceN >= targetForceN)
-                    maxForceN = limitForceN;
-                float maxPowerW = DieselPowerSupply.AvailableTractionPowerW;
-                if (targetForceN * AbsTractionSpeedMpS > maxPowerW) maxForceN = maxPowerW / AbsTractionSpeedMpS;
-                UpdateForceWithRamp(ref TractionForceN, elapsedClockSeconds, targetForceN, maxForceN, TractionForceRampUpNpS, TractionForceRampDownNpS, TractionForceRampDownToZeroNpS, TractionPowerRampUpWpS, TractionPowerRampDownWpS, TractionPowerRampDownToZeroWpS);
-            }
-            else
-            {
-                TractionForceN = 0f;
-            }
-            TractiveForceN = TractionForceN;
+            base.UpdateTractionForce(elapsedClockSeconds);
         }
 
         protected override void UpdateAxleDriveForce()

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

@@ -2558,13 +2558,25 @@ public void UpdateForceWithRamp(ref float forceN, float elapsedClockSeconds, flo
                 forceN = Math.Max(targetForceN, forceN - (targetForceN == 0 ? rampZeroNpS : rampDownNpS) * elapsedClockSeconds);
             }
         }
+        /// <summary>
+        /// Provides the theoretical tractive force that can be achieved at current speed
+        /// Takes into account number of available engines and power limitation effects from the power supply.
+        /// This method does not take into account transient effects that temporary limit tractive force
+        /// (e.g. diesel engine still revving up)
+        /// </summary>
+        /// <param name="t">Throttle position (0-1)</param>
+        /// <returns></returns>
         public virtual float GetAvailableTractionForceN(float t)
         {
             if (t <= 0) return 0;
             float powerW = float.MaxValue;
             float forceN;
-            if (this is MSTSElectricLocomotive electric && electric.ElectricPowerSupply.MaximumPowerW > 0)
-                powerW = electric.ElectricPowerSupply.MaximumPowerW * t * (1-PowerReduction);
+            // Take into account power limitation
+            if (LocomotivePowerSupply is ScriptedLocomotivePowerSupply supply && supply.MaximumPowerW > 0)
+                powerW = supply.MaximumPowerW * t * (1-PowerReduction);
+            // This section calculates the traction force of the locomotive as follows:
+            // Basic configuration (no TF table) - uses P = F /speed  relationship - requires power and force parameters to be set in the ENG file. 
+            // Advanced configuration (TF table) - use a user defined tractive force table
             if (TractiveForceCurves == null)
             {
                 powerW = Math.Min(powerW, MaxPowerW * t * t * (1 - PowerReduction));
@@ -2596,20 +2608,28 @@ protected virtual void UpdateTractionForce(float elapsedClockSeconds)
         {
             float t = ThrottlePercent / 100;
 
+            // Ensure that throttle never exceeds the limits imposed by other subsystems
             float maxthrottle = MaxThrottlePercent / 100;
+            // For diesel locomotives, also take into account the throttle setting associated to the current engine RPM
+            if (IsPlayerTrain && this is MSTSDieselLocomotive diesel) maxthrottle = Math.Min(maxthrottle, diesel.DieselEngines.ApparentThrottleSetting / 100.0f);
             if (t > maxthrottle) t = maxthrottle;
             t = MathHelper.Clamp(t, 0, 1);
 
             if (maxthrottle > 0 && Direction != Direction.N && LocomotivePowerSupply.MainPowerSupplyOn)
             {
+                // Set the target force to the theoretically available tractive force for current throttle setting
+                // If there is a limit on the amount of throttle, ensure that tractive force never exceeds the limit
+                // imposed by that throttle setting
                 float targetForceN = GetAvailableTractionForceN(t);
                 float limitForceN = GetAvailableTractionForceN(maxthrottle);
                 float maxForceN = float.MaxValue;
+                // Ignore force limit for exotic curves where higher throttle settings provide less tractive force
                 if (limitForceN >= targetForceN)
                     maxForceN = limitForceN;
-                if (this is MSTSElectricLocomotive electric)
+                // Ensure that power consumption never exceeds the power that is available for traction at the moment
+                if (LocomotivePowerSupply is ScriptedLocomotivePowerSupply supply)
                 {
-                    float maxPowerW = electric.ElectricPowerSupply.AvailableTractionPowerW;
+                    float maxPowerW = supply.AvailableTractionPowerW;
                     if (targetForceN * AbsTractionSpeedMpS > maxPowerW) maxForceN = maxPowerW / AbsTractionSpeedMpS;
                 }
                 UpdateForceWithRamp(ref TractionForceN, elapsedClockSeconds, targetForceN, maxForceN, TractionForceRampUpNpS, TractionForceRampDownNpS, TractionForceRampDownToZeroNpS, TractionPowerRampUpWpS, TractionPowerRampDownWpS, TractionPowerRampDownToZeroWpS);