Automatic merge of T1.6-139-g6b62c2a7d and 12 pull requests

- Pull request #1082 at 8538170: Allow variable water level in glass gauge
- Pull request #1156 at f46d5f2: Fix incorrectly disabled options in train operations window
- Pull request #1091 at 492795a: Automatic speed control
- Pull request #1122 at 73c47b4: Wagon Size and Centering Controls
- Pull request #1124 at e241a0d: Built-in PBL2 brake controller
- Pull request #1128 at d116396: Particle Emitter Overhaul
- Pull request #1157 at 39cd994: Dynamic brake authorization by TCS
- Pull request #1159 at 48c9a63: Skip OR warnings about TSRE-specific token Ruler
- Pull request #1163 at 2f9e292: Fix: Crash when using Camera 8 and F9.
- Pull request #1164 at 1ad9889: Fix: F9 crashes with a front coupled single steam locomotive by Csantucci.
- Pull request #1166 at 51e7f7a: Simplify loading of internal and game textures
- Pull request #1167 at 2c028a4: Fix: RunActivity slow to terminate because of long sleep in Host Process

Author: openrails-bot

Source/Documentation/Manual/features-rollingstock.rst

@@ -505,6 +505,37 @@ types at each end. Only the highest detail LOD of the main shape and freight ani
 used, the .sd file is not checked. If the process fails, a warning will be written to the
 log and the automatic calculation will be skipped.
 
+Advanced articulation control
+-----------------------------
+
+A wide variety of modern rolling stock uses articulation, in which multiple rail vehicles
+share a single "Jacobs Bogie". Open Rails offers partial support for such passenger and
+freight units by allowing one wagon to include a bogie in its 3D model while the next
+wagon removes the bogie from its 3D model. Ideally, OR will then add an invisible bogie
+to the end of the wagon without the bogie to emulate "sharing" the bogie with the previous
+wagon.
+
+However, this automatic system is limited. OR will check for wheels in the wagon's 3D
+model and will assume the wagon is articulated at one end if there are no wheels towards
+that end of the 3D model. This approach will only be used on 3D models with 3, 2, or 0 axles
+(the 1-axle case is excluded for compatibility reasons) and won't be used on locomotives.
+In some cases, this approach will result in false negative or false positive detection
+of articulation. Should the automatic articulation method not produce the expected track
+following behavior, it is now possible to manually define whether a wagon or engine
+should use the articulation behavior.
+
+.. index::
+   single: ORTSFrontArticulation
+   single: ORTSRearArticulation
+
+To forcibly enable the articulation behavior at the front of the rail vehicle, use
+``ORTSFrontArticulation ( 1 )`` and at the rear use ``ORTSRearArticulation ( 1 )``.
+Conversely, use ``ORTSFrontArticulation ( 0 )`` or ``ORTSRearArticulation ( 0 )`` to
+force disable articulation behavior. Articulation should generally be enabled on the
+'floating' end(s) of a vehicle, where a bogie or wheels are not present in the 3D
+model, and disabled on the end(s) that have wheels. Entering a value of -1 provides
+the default (automatic) behavior.
+
 Freight animations and pickups
 ==============================
 

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

@@ -1427,6 +1427,8 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     if (ShapeBoundingLimits.Maxes.Z < ShapeBoundingLimits.Mins.Z)
                         (ShapeBoundingLimits.Maxes.Z, ShapeBoundingLimits.Mins.Z) = (ShapeBoundingLimits.Mins.Z, ShapeBoundingLimits.Maxes.Z);
                     break;
+                case "wagon(ortsfrontarticulation": FrontArticulation = stf.ReadIntBlock(null); break;
+                case "wagon(ortsreararticulation": RearArticulation = stf.ReadIntBlock(null); break;
                 case "wagon(ortslengthbogiecentre": CarBogieCentreLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
                 case "wagon(ortslengthcarbody": CarBodyLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
                 case "wagon(ortslengthairhose": CarAirHoseLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
@@ -1454,13 +1456,13 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                         InitialCentreOfGravityM.Y = stf.ReadFloat(STFReader.UNITS.Distance, 0);
                         InitialCentreOfGravityM.Z = stf.ReadFloat(STFReader.UNITS.Distance, 0);
 
-                    if (Math.Abs(InitialCentreOfGravityM.Z) > 2)
-                    {
-                        STFException.TraceWarning(stf, string.Format("CentreOfGravity Z set to zero because value {0} outside range -2 to +2", InitialCentreOfGravityM.Z));
-                        InitialCentreOfGravityM.Z = 0;
-                    }
+                        if (Math.Abs(InitialCentreOfGravityM.Z) > 2)
+                        {
+                            STFException.TraceWarning(stf, string.Format("CentreOfGravity Z set to zero because value {0} outside range -2 to +2", InitialCentreOfGravityM.Z));
+                            InitialCentreOfGravityM.Z = 0;
+                        }
 
-                    stf.SkipRestOfBlock();
+                        stf.SkipRestOfBlock();
                     }
                     else // User has entered a single value, only set the Y component to this value, leave other components unchanged
                     {

Source/Orts.Simulation/Simulation/RollingStocks/TrainCar.cs

@@ -189,6 +189,8 @@ public static Interpolator SteamHeatBoilerFuelUsageGalukpH()
         public (Vector3 Mins, Vector3 Maxes) ShapeBoundingLimits;
         public bool AutoSize = false;       // Are the dimensions of this wagon to be calculated automatically from the shape file?
         public Vector3 AutoSizeOffsetM;
+        public int FrontArticulation = -1;  // -1: Determine front articulation automatically, 0: Force no front articulation, 1: Force front articulation
+        public int RearArticulation = -1;   // -1: Determine rear articulation automatically, 0: Force no rear articulation, 1: Force rear articulation
         public float MassKG = 10000;        // Mass in KG at runtime; coincides with InitialMassKG if there is no load and no ORTS freight anim
         public float InitialMassKG = 10000;
         public bool IsDriveable;
@@ -2927,34 +2929,36 @@ public void SetUpWheels()
             // Decided to control what is sent to SetUpWheelsArticulation()by using
             // WheelAxlesLoaded as a flag.  This way, wagons that have to be processed are included
             // and the rest left out.
-            bool articulatedFront = !WheelAxles.Any(a => a.OffsetM.Z < 0);
-            bool articulatedRear = !WheelAxles.Any(a => a.OffsetM.Z > 0);
-            var carIndex = Train.Cars.IndexOf(this);
-            //Certain locomotives are testing as articulated wagons for some reason.
-            if (WagonType != WagonTypes.Engine)
-                if (WheelAxles.Count != 1 && (articulatedFront || articulatedRear))
-                {
-                    WheelAxlesLoaded = true;
-                    SetUpWheelsArticulation(carIndex);
-                }
+
+            // Force articulation if stock is configured as such
+            // Otherwise, use default behavior which gives articulation if there are no axles forward/reareward on the model,
+            // disables articulation on engines, and only allows articulation with 3 or fewer axles, but not 1 axle
+            bool articulatedFront = (FrontArticulation == 1 ||
+                (FrontArticulation == -1 && !WheelAxles.Any(a => a.OffsetM.Z < 0) && WagonType != WagonTypes.Engine && WheelAxles.Count != 1 && WheelAxles.Count <= 3));
+            bool articulatedRear = (RearArticulation == 1 ||
+                (RearArticulation == -1 && !WheelAxles.Any(a => a.OffsetM.Z > 0) && WagonType != WagonTypes.Engine && WheelAxles.Count != 1 && WheelAxles.Count <= 3));
+
+            if (articulatedFront || articulatedRear)
+            {
+                WheelAxlesLoaded = true;
+                SetUpWheelsArticulation(articulatedFront, articulatedRear);
+            }
         } // end SetUpWheels()
 
-        protected void SetUpWheelsArticulation(int carIndex)
+        protected void SetUpWheelsArticulation(bool front, bool rear)
         {
             // If there are no forward wheels, this car is articulated (joined
             // to the car in front) at the front. Likewise for the rear.
-            bool articulatedFront = !WheelAxles.Any(a => a.OffsetM.Z < 0);
-            bool articulatedRear = !WheelAxles.Any(a => a.OffsetM.Z > 0);
             // Original process originally used caused too many issues.
             // The original process did include the below process of just using WheelAxles.Add
             //  if the initial test did not work.  Since the below process is working without issues the
             //  original process was stripped down to what is below
-            if (articulatedFront || articulatedRear)
+            if (front || rear)
             {
-                if (articulatedFront && WheelAxles.Count <= 3)
+                if (front)
                     WheelAxles.Add(new WheelAxle(new Vector3(0.0f, BogiePivotHeightM, -CarLengthM / 2.0f), 0, 0) { Part = Parts[0] });
 
-                if (articulatedRear && WheelAxles.Count <= 3)
+                if (rear)
                     WheelAxles.Add(new WheelAxle(new Vector3(0.0f, BogiePivotHeightM, CarLengthM / 2.0f), 0, 0) { Part = Parts[0] });
 
                 WheelAxles.Sort(WheelAxles[0]);