Allow manually defining articulation

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -488,6 +488,35 @@ types at each end. Only the highest detail LOD of the main shape is used to auto
 rolling stock, other LODs and freight animations are ignored. 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. Entering a value of -1 provides the default
+automatic behavior.
+
 Freight animations and pickups
 ==============================
 

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

@@ -1428,6 +1428,8 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     AutoLengthOffsetM = stf.ReadFloat(STFReader.UNITS.Distance, null);
                     stf.SkipRestOfBlock();
                     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;

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

@@ -1,4 +1,4 @@
-// COPYRIGHT 2009 - 2022 by the Open Rails project.
+// COPYRIGHT 2009 - 2022 by the Open Rails project.
 // 
 // This file is part of Open Rails.
 // 
@@ -191,6 +191,8 @@ public static Interpolator SteamHeatBoilerFuelUsageGalukpH()
         public float AutoWidthOffsetM;
         public float AutoLengthOffsetM;
         public float AutoHeightOffsetM;
+        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;
@@ -2715,34 +2717,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 mode,
+            // 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]);