Fix the brake equipment type, added some documentation.

Author: pzgulyas

Source/Documentation/Manual/physics.rst

@@ -2678,6 +2678,46 @@ For EP brakes, two variants are available:
   actuating the cylinders. This system is sometimes called "UIC EP brake". It is typically the system
   used in high speed trains.
 
+Defining Multiple Brake Systems
+-------------------------------
+
+It is possible to define multiple systems within ``OrtsBrakeMode`` sections::
+
+    ORTSBrakeMode (
+        ORTSBrakeModeName ( AG )
+        BrakeSystemType( Air_single_pipe )
+        Comment ( All brake parameters are available in such a section )
+    )
+    ORTSBrakeMode (
+        ORTSBrakeModeName ( VB )
+        BrakeSystemType( Vacuum_single_pipe )
+        Comment ( All brake parameters are available in such a section )
+    )
+
+These sections can be used to either define dual vacuum/air rolling stock, or 
+can be used to define the brake modes of the UIC stock in the following form::
+
+    BrakeSystemType( Air_twin_pipe )
+    ORTSBrakeMode (
+        ORTSBrakeModeName ( G )
+        ORTSBrakeMass ( 67t )
+        Comment ( All brake parameters are available in such a section )
+    )
+    ORTSBrakeMode (
+        ORTSBrakeModeName ( P )
+        ORTSBrakeMass ( 83t )
+        BrakeSystemType( Vacuum_single_pipe )
+        Comment ( All brake parameters are available in such a section )
+    )
+
+Available brake mode names to be used are: GG, G, PP, P, RR, R, R_MG, AG, AP, AU, VB, VP, VU. 
+With the ``ORTSBrakeModeNames`` keyword the used brake modes can be filtered, 
+for being able to define them in an include file, and using only the needed 
+ones. It can be used e.g. in the following form::
+
+    ORTSBrakeModeNames ( "P, R" )
+
+
 .. _physics-brake-controller:
 
 Train Brake Controller Positions
@@ -3087,6 +3127,13 @@ using the ORTSBrakeShoeFriction parameter, 1D (ie, speed only, see above section
 
 ``ORTSNumberCarBrakeShoes`` - to facilitate the operation of the default 2D curves above it is necessary to configure the number of brake shoes for each car.
 
+``ORTSBrakeMass`` - Railways part of the UIC organisation instead of NBR 
+provide brake masses, measured in tonnes, which is a virtual value to define 
+the brake efficiency. Openrails uses this value as an alternative to setting 
+the max brake shoe force directly, and recalculates this to that force using 
+approximating formulas to the published UIC brake curves. This parameter is 
+ignored if the ``ORTSMaxBrakeShoeForce`` also set.
+
 Whilst OR will attempt to set some defaults if parameters are left out, the most realistic operation will be achieved by using all the relevant parameters.
 
 The following two legacy arrangements can be used as an alternative to the above method,
@@ -3095,6 +3142,26 @@ The following two legacy arrangements can be used as an alternative to the above
 
 - Legacy #2 - where MaxBrakeForce and ORTSBrakeShoeFriction have been set, legacy operation will remain unchanged.
 
+Load Compensation
+-----------------
+
+Load compensation stages can be defined in the following way::
+
+    OrtsLoadStage (
+        OrtsBrakeMass ( 28t )
+        Comment ( All brake parameters are available in such a section )
+    )
+    OrtsLoadStage (
+        OrtsBrakeMass ( 37t )
+        OrtsLoadStageMinMass ( 34t )
+        Comment ( All brake parameters are available in such a section )
+    )
+
+The ``OrtsLoadStageMinMass`` parameter defines the minimum car mass (together 
+with the load) where the stage can be activated without risking the brake lock. 
+For the lowest stage this keyword should be omitted. In OpenRails the switching 
+between stages is automatic.
+
 
 Train Brake Pipe Losses
 -----------------------
@@ -3597,10 +3664,11 @@ The retainers of a car will only be available if either the General Option
 :ref:`Retainer valve on all cars <options-retainers>` is checked, or the car's
 .wag file contains a retainer valve declaration. To declare a retainer the line
 ``BrakeEquipmentType (  )`` in the .wag file must include either the item
-``Retainer_4_Position`` or  the item ``Retainer_3_Position``. A 4 position
+``Retainer_4_Position``, ``Retainer_3_Position`` or ``UIC_mountain``. A 4 position
 retainer includes four states: exhaust, low pressure (10 psi), high pressure
 (20 psi), and slow direct (gradual drop to zero). A 3 position retainer does
-not include the low pressure position. The use and display of the retainers is
+not include the low pressure position. The UIC plain-mountain switch has only 
+2 positions. The use and display of the retainers is 
 described in :ref:`Extended HUD for Brake Information <physics-hud-brake>`.
 
 The setting of the retained pressure and the number of retainers is

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

@@ -1383,6 +1383,7 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                 case "wagon(ortsbrakemode":
                     var newSystem = BrakeSystem.CreateNewLike(BrakeSystem, this)?.InitializeDefault(); // Start with the same BrakeSystemType() as the base
                     BrakeModes? brakeModeName = null;
+                    List<string> brakeEquipment = null;
 
                     stf.VerifyStartOfBlock();
                     while (!stf.EndOfBlock())
@@ -1419,6 +1420,12 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                                     else
                                         BrakeSystems.Add(key, newSystem);
                                 }
+                                if (brakeEquipment != null)
+                                    (newSystem as MSTSBrakeSystem)?.SetBrakeEquipment(brakeEquipment);
+                                break;
+                            case "wagon(ortsbrakemode(brakeequipmenttype":
+                                brakeEquipment = stf.ReadStringBlock("").ToLower().Replace(" ", "").Split(',').ToList();
+                                (newSystem as MSTSBrakeSystem)?.SetBrakeEquipment(brakeEquipment);
                                 break;
                             case "wagon(ortsbrakemode(ortsloadstage":
                                 var stage = BrakeSystem.CreateNewLike(newSystem, this).InitializeDefault();

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/AirSinglePipe.cs

@@ -402,7 +402,7 @@ public override string[] GetDebugStatus(Dictionary<BrakeSystemComponent, Pressur
                 TwoPipes ? FormatStrings.FormatPressure(BrakeLine2PressurePSI, PressureUnit.PSI, units[BrakeSystemComponent.MainPipe], true) : string.Empty,
                 BrakeValve == BrakeValveType.Distributor ? FormatStrings.FormatPressure(ControlResPressurePSI, PressureUnit.PSI, units[BrakeSystemComponent.AuxiliaryReservoir], true) : string.Empty,
                 SupplyReservoirPresent ? FormatStrings.FormatPressure(SupplyResPressurePSI, PressureUnit.PSI, units[BrakeSystemComponent.SupplyReservoir], true) : string.Empty,
-                RetainerPositions == 0 ? string.Empty : RetainerDebugState,
+                RetainerPositions <= 0 ? string.Empty : RetainerDebugState,
                 Simulator.Catalog.GetString(GetStringAttribute.GetPrettyName(TripleValveState)),
                 string.Empty, // Spacer because the state above needs 2 columns.
                 HandBrakePresent ? string.Format("{0:F0}%", HandbrakePercent) : string.Empty,
@@ -482,7 +482,7 @@ public override void SetBrakeEquipment(List<string> equipment)
             if (equipment.Contains("retainer_4_position")) RetainerPositions = 4;
             else if (equipment.Contains("retainer_3_position")) RetainerPositions = 3;
             else if (equipment.Contains("uic_mountain")) RetainerPositions = 2;
-            else RetainerPositions = 0;
+            else RetainerPositions = -1;
             SupplyReservoirPresent = equipment.Contains("supply_reservoir");
             EmergencySolenoidValve = equipment.Contains("emergency_solenoid_valve");
         }
@@ -2515,6 +2515,7 @@ public override void SetRetainer(RetainerSetting setting)
         {
             switch (RetainerPositions)
             {
+                case -1:
                 case 0:
                 case 1: setting = RetainerSetting.Exhaust; break;
                 case 2: if (setting == RetainerSetting.LowPressure || setting == RetainerSetting.HighPressure) setting = RetainerSetting.SlowDirect; break;

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/SMEBrakeSystem.cs

@@ -86,7 +86,7 @@ public override string[] GetDebugStatus(Dictionary<BrakeSystemComponent, Pressur
                 EmergencyReservoirPresent ? FormatStrings.FormatPressure(EmergResPressurePSI, PressureUnit.PSI, units[BrakeSystemComponent.EmergencyReservoir], true) : string.Empty,
                 TwoPipes ? FormatStrings.FormatPressure(CylPressurePSI, PressureUnit.PSI, units[BrakeSystemComponent.MainPipe], true) : string.Empty,
                 BrakeValve == BrakeValveType.Distributor ? FormatStrings.FormatPressure(ControlResPressurePSI, PressureUnit.PSI, units[BrakeSystemComponent.AuxiliaryReservoir], true) : string.Empty,
-                RetainerPositions == 0 ? string.Empty : RetainerDebugState,
+                RetainerPositions <= 0 ? string.Empty : RetainerDebugState,
                 Simulator.Catalog.GetString(GetStringAttribute.GetPrettyName(TripleValveState)),
                 string.Empty, // Spacer because the state above needs 2 columns.
                 string.Empty,