Automatic merge of T1.5.1-866-gbae4730e2 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 0d6d045: 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 #908 at ad3362c: feat: supports switching adhesion precisions
- Pull request #911 at 6834af0: docs: Add refactoring as a special type of PR
- Pull request #912 at 659396e: New Triple Valve Features Vol. 2
- Pull request #914 at 9ee1da3: Adjustments to Duplex steam
- Pull request #915 at 6d911d7: Correct calculation error with curve friction
- Pull request #916 at 11ac52c: Distributed Power Air Brake Synchronization

Author: openrails-bot

Source/Orts.Simulation/Simulation/Physics/Train.cs

@@ -513,6 +513,9 @@ public TrainCar LeadLocomotive
                         //if (lead.EngineBrakeController != null)
                         //    lead.EngineBrakeController.UpdateEngineBrakePressure(ref BrakeLine3PressurePSI, 1000);
                     }
+
+                // If lead locomotive changes, distributed power needs to be updated
+                SetDPUnitIDs(true);
             }
         }
 
@@ -1539,27 +1542,43 @@ public void SetDPUnitIDs(bool keepRemoteGroups = false)
         {
             // List to keep track of new 'lead' DP units
             // 'Lead' DP units follow the air brake commands of the master loco, 'trail' DP units do not
-            List<TrainCar> tempDPLead = new List<TrainCar>();
+            List<TrainCar> tempDPLeads = new List<TrainCar>();
+            TrainCar tempDPLead = null;
+            // Value judging how compatible this locomotive is to the lead locomotive for DP purposes
+            float dpRating = 0;
 
             // List of each DP group's locomotives
             List<List<TrainCar>> tempLocoGroups = new List<List<TrainCar>>();
 
             var prevId = -1;
-
             var id = 0;
+
             foreach (var car in Cars)
             {
-                //Console.WriteLine("___{0} {1}", car.CarID, id);
                 if (car is MSTSLocomotive loco)
                 {
+                    float thisDPRating = DetermineDPCompatibility(LeadLocomotive, car);
+
                     loco.DPUnitID = id;
 
-                    if (id != prevId && !tempDPLead.Contains(car)) // If this is a new ID, that means we found a 'lead' unit
+                    if (id != prevId) // New locomotive group
                     {
-                        tempDPLead.Add(car);
+                        // Add the most suitable unit from the previous group as a DP lead unit
+                        if (tempDPLead != null && !tempDPLeads.Contains(tempDPLead))
+                            tempDPLeads.Add(tempDPLead);
+
+                        dpRating = thisDPRating;
+                        tempDPLead = car;
 
                         prevId = id;
                     }
+                    else // Same locomotive group
+                        // Check to see if this locomotive is more compatible than previous ones
+                        if (thisDPRating > dpRating)
+                        {
+                            dpRating = thisDPRating;
+                            tempDPLead = car;
+                        }
 
                     if (car.RemoteControlGroup == 1 && !keepRemoteGroups)
                         car.RemoteControlGroup = 0;
@@ -1568,20 +1587,24 @@ public void SetDPUnitIDs(bool keepRemoteGroups = false)
                     id++;
             }
 
-            foreach (TrainCar locoCar in tempDPLead)
+            // Add final DP lead unit
+            if (tempDPLead != null && !tempDPLeads.Contains(tempDPLead))
+                tempDPLeads.Add(tempDPLead);
+
+            foreach (TrainCar locoCar in tempDPLeads)
             {
                 // The train's lead unit should always be a DP lead unit, even if not at the front
                 // If a different locomotive in the lead loco's group has been declared DP lead, replace that loco with the lead loco
                 if (LeadLocomotive is MSTSLocomotive lead && locoCar is MSTSLocomotive loco)
                     if (loco.DPUnitID == lead.DPUnitID && locoCar != LeadLocomotive)
                     {
-                        tempDPLead.Insert(tempDPLead.IndexOf(locoCar), LeadLocomotive);
-                        tempDPLead.Remove(locoCar);
+                        tempDPLeads.Insert(tempDPLeads.IndexOf(locoCar), LeadLocomotive);
+                        tempDPLeads.Remove(locoCar);
                         break; // foreach doesn't like it when the collection is modified during the loop, break to mitigate error
                     }
             }
 
-            DPLeadUnits = tempDPLead;
+            DPLeadUnits = tempDPLeads;
 
             foreach (TrainCar loco in DPLeadUnits)
             {
@@ -4352,6 +4375,58 @@ public TrainCar DetermineDPLeadLocomotive(TrainCar locoCar)
             return null;
         }
 
+        //================================================================================================//
+        /// <summary>
+        /// Find compatibility of DP connection between two locomotives
+        /// <\summary>
+
+        // Returns a score judging the compatibility of a lead locomotive (first input as a TrainCar)
+        // and remote locomotive (second input as a TrainCar). The more capabilities the two locomotives
+        // share, the higher the number returned. There is an additional slight bias for remote
+        // locomotives having higher capabilities than the lead locomotive.
+        // Returns -1 if one of the input TrainCars isn't a locomotive
+
+        public float DetermineDPCompatibility(TrainCar leadCar, TrainCar remoteCar)
+        {
+            float score = 0;
+
+            if (leadCar is MSTSLocomotive lead && remoteCar is MSTSLocomotive remote)
+            {
+                if (remote.DPSyncTrainApplication)
+                {
+                    if (lead.DPSyncTrainApplication)
+                        score++;
+                    else
+                        score += 0.1f;
+                }
+                if (remote.DPSyncTrainRelease)
+                {
+                    if (lead.DPSyncTrainRelease)
+                        score++;
+                    else
+                        score += 0.1f;
+                }
+                if (remote.DPSyncEmergency)
+                {
+                    if (lead.DPSyncEmergency)
+                        score++;
+                    else
+                        score += 0.1f;
+                }
+                if (remote.DPSyncIndependent)
+                {
+                    if (lead.DPSyncIndependent)
+                        score++;
+                    else
+                        score += 0.1f;
+                }
+
+                return score;
+            }
+            else
+                return -1;
+        }
+
         //================================================================================================//
         /// <summary>
         /// Propagate brake pressure