Automatic merge of T1.5.1-870-ge0bf062eb and 17 pull requests

- Pull request #570 at 3539862: Experimental glTF 2.0 support with PBR lighting
- 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 9c456aa: Blueprint/train car operations UI window
- Pull request #885 at 8f94333: feat: Add notifications to Menu
- Pull request #886 at 6c0785b: Scene viewer extension to TrackViewer
- 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 #897 at 42f1dd9: feat: Improved system information collection
- Pull request #903 at 9bead33: Downloading route content (Github, zip)
- Pull request #907 at 9b0b04f: Bug fix for https://bugs.launchpad.net/or/+bug/2047300 Dynamic tracks disappear after long tunnel
- Pull request #911 at 6834af0: docs: Add refactoring as a special type of PR
- Pull request #912 at d595703: New Triple Valve Features Vol. 2
- Pull request #914 at 476d67b: Adjustments to Duplex steam
- Pull request #915 at 6d911d7: Correct calculation error with curve friction
- Pull request #917 at fde18cf: Lighting Configuration Enhancements
- Pull request #918 at f7ba507: Manual - News topics updated since 1.5.1

Author: openrails-bot

Source/Orts.Simulation/Simulation/RollingStocks/MSTSSteamLocomotive.cs

@@ -656,8 +656,6 @@ public float TenderCoalMassKG              // Decreased by firing and increased
 
         float ReciprocatingWeightLb = 580.0f;  // Weight of reciprocating parts of the rod driving gears
         float ConnectingRodWeightLb = 600.0f;  // Weignt of connecting rod
-        float ConnectingRodBalanceWeightLb = 300.0f; // Balance weight for connecting rods
-        float ExcessBalanceFactor = 400.0f;  // Factor to be included in excess balance formula
         float CrankRadiusFt = 1.08f;        // Assume crank and rod lengths to give a 1:10 ratio - a reasonable av for steam locomotives?
         float ConnectRodLengthFt = 10.8f;
         float RodCoGFt = 4.32f;  // 0.4 from crank end of rod
@@ -1229,25 +1227,6 @@ public override void Initialize()
             if (ZeroError(BoilerVolumeFT3, "BoilerVolume"))
                 BoilerVolumeFT3 = 1;
 
-            // For light locomotives reduce the weight of the various connecting rods, as the default values are for larger locomotives. This will reduce slip on small locomotives
-            // It is not believed that the weight reduction on the connecting rods is linear with the weight of the locmotive. However this requires futher research, and this section is a 
-            // work around until any further research is undertaken
-            // "The following code provides a simple 2-step adjustment, as not enough information is currently available for a more flexible one."
-            if (MassKG < Kg.FromTUS(10))
-            {
-                const float reductionfactor = 0.2f;
-                ReciprocatingWeightLb = 580.0f * reductionfactor;  // Weight of reciprocating parts of the rod driving gears
-                ConnectingRodWeightLb = 600.0f * reductionfactor;  // Weignt of connecting rod
-                ConnectingRodBalanceWeightLb = 300.0f * reductionfactor; // Balance weight for connecting rods
-            }
-            else if (MassKG < Kg.FromTUS(20))
-            {
-                const float reductionfactor = 0.3f;
-                ReciprocatingWeightLb = 580.0f * reductionfactor;  // Weight of reciprocating parts of the rod driving gears
-                ConnectingRodWeightLb = 600.0f * reductionfactor;  // Weignt of connecting rod
-                ConnectingRodBalanceWeightLb = 300.0f * reductionfactor; // Balance weight for connecting rods
-            }
-
             #region Initialise additional steam properties
 
             WaterDensityPSItoLBpFT3 = SteamTable.WaterDensityInterpolatorPSItoLBpFT3();
@@ -2020,6 +1999,26 @@ public override void Initialize()
                     SteamEngines[i].MaxIndicatedHorsePowerHP = MaxSpeedFactor * (SteamEngines[i].MaxTractiveEffortLbf * MaxLocoSpeedMpH) / 375.0f;  // To be checked what MaxTractive Effort is for the purposes of this formula.
                     MaxIndicatedHorsePowerHP += SteamEngines[i].MaxIndicatedHorsePowerHP;
                 }
+
+                if (SteamEngines[i].ExcessWheelBalanceLbs == 0)
+                {
+                    SteamEngines[i].ExcessWheelBalanceLbs = 440f; // set to a default value.
+                }
+
+                // For light locomotives reduce the weight of the various connecting rods, as the default values are for larger locomotives. This will reduce slip on small locomotives
+                // It is not believed that the weight reduction on the connecting rods is linear with the weight of the locmotive. However this requires futher research, and this section is a 
+                // work around until any further research is undertaken
+                // "The following code provides a simple 2-step adjustment, as not enough information is currently available for a more flexible one."
+                if (MassKG < Kg.FromTUS(10))
+                {
+                    const float reductionfactor = 0.2f;
+                    SteamEngines[i].ExcessWheelBalanceLbs *= reductionfactor;
+                }
+                else if (MassKG < Kg.FromTUS(20))
+                {
+                    const float reductionfactor = 0.3f;
+                    SteamEngines[i].ExcessWheelBalanceLbs *= reductionfactor;
+                }
             }
 
             // Check to see if MaxIHP is in fact limited by the boiler
@@ -5981,8 +5980,39 @@ private void UpdateSteamTractiveForce(float elapsedClockSeconds, float locomotiv
                         float verticalThrustForcelbf = effectiveRotationalForcelbf * verticalThrustFactor;
 
                         // Calculate Excess Balance
-                        float excessBalanceWeightLb = (ConnectingRodWeightLb + ReciprocatingWeightLb) - ConnectingRodBalanceWeightLb - (Kg.ToLb(MassKG) / ExcessBalanceFactor);
-                        float excessBalanceForcelbf = inertiaSpeedCorrectionFactor * excessBalanceWeightLb * sin;
+                        float excessBalanceForcelbf = inertiaSpeedCorrectionFactor * SteamEngines[numberofengine].ExcessWheelBalanceLbs * sin;
+
+                        // Hammer (dynamic) force due to the rotation of the wheels is calculated  
+                        // From The Steam Locomotive by Ralph Johnson (pg 276 ) - 
+                        // Hammer force = 1.6047 x stroke (ins) x excessbalancemass (lbf)  x speed^2 (mph) / ( Dia of drive wheel^2 (ins))  - This is per wheel
+                        // The excess balance weight is on one side of the locomotive, is spread evenly over the number of wheels (this is not always the
+                        // case for prototypical locomotives)
+
+                        if (SteamEngines[numberofengine].AuxiliarySteamEngineType != SteamEngine.AuxiliarySteamEngineTypes.Booster)
+                        {
+                            SteamEngines[numberofengine].HammerForceLbs = (1.6047f * Me.ToIn(SteamEngines[numberofengine].CylindersStrokeM) * SteamEngines[numberofengine].ExcessWheelBalanceLbs * (float)Math.Pow(MpS.ToMpH(absSpeedMpS), 2)) / ((float)Math.Pow(Me.ToIn(2.0f * SteamEngines[numberofengine].AttachedAxle.WheelRadiusM), 2) * SteamEngines[numberofengine].AttachedAxle.NumWheelsetAxles);
+
+                            // weight on each individual wheel, rather then each axle
+                            var wheelWeight = SteamEngines[numberofengine].AttachedAxle.WheelWeightKg / (SteamEngines[numberofengine].AttachedAxle.NumWheelsetAxles * 2f);
+
+                            if (SteamEngines[numberofengine].HammerForceLbs > wheelWeight)
+                            {
+                                SteamEngines[numberofengine].IsWheelHammerForce = true;
+                            }
+                            else
+                            {
+                                SteamEngines[numberofengine].IsWheelHammerForce = false;
+                            }
+
+                            if (SteamEngines[numberofengine].HammerForceLbs > 0.9 * wheelWeight)
+                            {
+                                SteamEngines[numberofengine].IsWheelHammerForceWarning = true;
+                            }
+                            else
+                            {
+                                SteamEngines[numberofengine].IsWheelHammerForceWarning = false;
+                            }
+                        }
 
                         // Account for the position of the crosshead position. In other words it depends upon whether the ExcessBalance is above or below the axle.
                         // The crosshead will be -ve for normalised angles between 0 - 180, and +ve for normalised angles between 180 - 360
@@ -7935,7 +7965,7 @@ public override string GetDebugStatus()
                 {
                     for (int i = 0; i < SteamEngines.Count; i++)
                     {
-                        status.AppendFormat("{0}\t{1}\t{2}\t{3}\t{4}\t{5}\t{6}\t{7} \t{8:N0} {9}\n",
+                        status.AppendFormat("{0}\t{1}\t{2}\t{3}\t{4}\t{5}\t{6}\t{7} \t{8:N0} {9}\t{10} \t{11:N0}{12}\n",
                          Simulator.Catalog.GetString("Force:"),
                          Simulator.Catalog.GetString("Eng#"),
                         i + 1,
@@ -7945,7 +7975,10 @@ public override string GetDebugStatus()
                          FormatStrings.FormatForce(SteamEngines[i].DisplayTractiveForceN, IsMetric),
                          Simulator.Catalog.GetString("DrvWhl"),
                          pS.TopM(SteamEngines[i].DriveWheelRevRpS),
-                         FormatStrings.rpm
+                         FormatStrings.rpm,
+                         Simulator.Catalog.GetString("Hammer"),
+                         FormatStrings.FormatForce(N.FromLbf(SteamEngines[i].HammerForceLbs), IsMetric),
+                         SteamEngines[i].IsWheelHammerForce ? "!!!" : SteamEngines[i].IsWheelHammerForceWarning ? "???" : ""
                          );
 
                     }

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/PowerSupplies/SteamEngine.cs

@@ -366,6 +366,26 @@ public enum AuxiliarySteamEngineTypes
         /// </summary>
         public float MaxIndicatedHorsePowerHP;
 
+        /// <summary>
+        /// Steam Engine unbalanced mass on wheels - per side. 
+        /// </summary>
+        public float ExcessWheelBalanceLbs;
+
+        /// <summary>
+        /// Steam Engine unbalanced wheel warning. 
+        /// </summary>
+        public bool IsWheelHammerForceWarning;
+
+        /// <summary>
+        /// Steam Engine unbalanced large overload. 
+        /// </summary>
+        public bool IsWheelHammerForce;
+
+        /// <summary>
+        /// Steam Engine hammer force per wheel - excessive values of this could cause track deformities. 
+        /// </summary>
+        public float HammerForceLbs;
+
         /// <summary>
         /// Steam Engine drive wheel rev per second
         /// </summary>
@@ -699,6 +719,10 @@ public virtual void Parse(STFReader stf)
                         MaxIndicatedHorsePowerHP = stf.ReadFloatBlock(STFReader.UNITS.Power, null);
                         MaxIndicatedHorsePowerHP = W.ToHp(MaxIndicatedHorsePowerHP);  // Convert input to HP for use internally in this module
                         break;
+                    case "excesswheelbalance":
+                        var excess = stf.ReadFloatBlock(STFReader.UNITS.Mass, null);
+                        ExcessWheelBalanceLbs = Kg.ToLb(excess);  // Convert input to lbs for use internally in this module
+                        break;
 
                     case "auxiliarysteamenginetype":
                         stf.MustMatch("(");
@@ -731,6 +755,7 @@ public void Copy(SteamEngine other)
             LPCylindersDiameterM = other.LPCylindersDiameterM;
             BoosterCutoff = other.BoosterCutoff;
             MaxIndicatedHorsePowerHP = other.MaxIndicatedHorsePowerHP;
+            ExcessWheelBalanceLbs = other.ExcessWheelBalanceLbs;
             BoosterThrottleCutoff = other.BoosterThrottleCutoff;
             BoosterGearRatio = other.BoosterGearRatio;
             AttachedAxleId = other.AttachedAxleId;