Merge pull request #899 from peternewell/steam-booster#1

Duplex steam engines - Booster Engine addition

Author: peternewell

Source/Documentation/Manual/physics.rst

@@ -237,6 +237,18 @@ advanced adhesion model dynamics. The value considers the inertia of all
 the axles and traction drives. If not set, the value is estimated from the
 locomotive mass and maximal power.
 
+By inserting multiple "Axle" sections in the above configuration, multiple 
+indpependent wheelsets can be defined which will operate independently of 
+each other. The following parameters can be inserted to characterise the 
+performance of the wheelset.
+
+``AnimatedParts`` - animated parts associated with the axles wheelset.
+``Weight`` - weight on the axles in the wheelset.
+``ORTSRadius`` - radius of the wheels in the wheelset.
+``NumberWheelsetAxles`` - number of axles in the wheelset.
+``ORTSFlangeAngle`` - flange angle of the wheels in the wheelset.
+``ORTSInertia`` - inertia of the wheels in the wheelset.
+
 The first model -- simple adhesion model -- is a simple tractive force
 condition-based computation. If the tractive force reaches its actual
 maximum, the wheel slip is indicated in HUD view and the tractive force
@@ -1253,6 +1265,66 @@ cylinder also tended to reach finite limits as well. These factors
 typically combined to place limits on the power of a locomotive depending
 upon the design factors used.
 
+Steam Locomotives with Multiple Engines
+.......................................
+
+Some steam locomotives can have multiple steam engines (ie separate steam 
+cylinders connected to different wheels), such as the 4-4-4-4 locomotive or 
+an articulated Garratt locomotive.
+
+To configure these types of locomotives configurations, multiple steam 
+engines need to be added to the engine section of the ENG file. These should have the 
+following format::
+
+    ORTSSteamEngines ( x
+        Wheelset (
+           
+        )
+    )
+
+where x = number of steam engines fitted to locomotive.
+
+The following parameters can be used to configure the steam engine::
+
+``NumCylinders`` - number of steam cylinders in engine.
+``CylinderStroke`` - stroke of steam cylinder.
+``CylinderDiameter`` - diameter of steam cylinder.
+``MaxIndicatedHorsepower`` - maximum indicated horsepower of steam engine.
+``AttachedAxle`` - the axle wheelset that the steam engine is attached to.
+
+To specify the engine as a Booster engine, the following additional parameters 
+can be used::
+
+``BoosterCutoff`` - the cutoff point for the Booster steam cylinder.
+``BoosterThrottleCutoff`` - the locomotive cutoff point where the Booster unlatches.
+``BoosterGearRatio`` - the gear ratio of the Booster engine.
+``AuxiliarySteamEngineType`` - by inserting "Booster" into this parameter the 
+engine is defined as a Booster engine.
+
+The following steam effects are defined for the 2nd multuple engine:
+
+i) Steam Exhausts - these are the exhausts from the two steam cylinders, and would be 
+located wherever the steam exhausted out of the cylinders, 
+``CylinderSteamExhaust2_1FX``, ``CylinderSteamExhaust2_2FX``, where "x_yFX", 
+x = engine number and y = cylinder number.
+
+ii) Cylinder Cocks Exhaust - the exhaust out of the cylinder drainage cocks, 
+``Cylinders2_11FX``, ``Cylinders2_12FX``, ``Cylinders2_21FX``, ``Cylinders2_22FX``, 
+where "x_yzFX", x = engine number, y = cylinder number and z = cylinder position.
+
+The following steam effects are defined for the Booster Engine:
+
+i) Steam Exhausts - these are the exhausts from the two steam cylinders, and would be 
+located wherever the steam exhausted out of the cylinders, 
+``BoosterCylinderSteamExhaust01FX``, ``BoosterCylinderSteamExhaust02FX``
+
+ii) Cylinder Cocks Exhaust - the exhaust out of the cylinder drainage cocks, 
+``BoosterCylinders11FX``, ``BoosterCylinders12FX``, ``BoosterCylinders21FX``, 
+``BoosterCylinders22FX``, where "xyFX", x = cylinder number, and y = cylinder position.
+
+The following CAB controls have been defined, ``STEAM_BOOSTER_AIR``, ``STEAM_BOOSTER_IDLE``,
+ ``STEAM_BOOSTER_LATCH``, ``STEAM_BOOSTER_PRESSURE``.
+
 Locomotive Types
 ................
 

Source/Documentation/Manual/sound.rst

@@ -417,14 +417,23 @@ Trigger       Function
 261           WindowOpening
 =========     =====================================
 
+The following triggers are related to the steam booster engine:
+
+=========     =====================================
+Trigger       Function
+=========     =====================================
+321           BoosterCylinderCocksOpen
+322           BoosterCylinderCocksClose
+=========     =====================================
+
 Variable Triggers
 -----------------
 
 ORTS
 ^^^^
 
 The sound objects attached to a vehicle (wagon or loco) can respond in volume and frequency to changes in the vehicle's properties.
-There are 7 properties:
+There are a number of triggers as follows:
 
 - distance squared from a sound source (m\ :sup:`2`)
 
@@ -436,9 +445,11 @@ There are 7 properties:
 
 - 3 variables in range 0 - 1:
 
-  - Variable1 reflects the throttle
+  - Variable1 reflects the throttle. For steam locomotives it is possible to have multiple steam engines, thus this variable can be applied
+   to each engine, by using a sound trigger of the form ``Variable1_x_inc_past`` or ``Variable1_x_dec_past``, where x = steam engine number.
 
-  - Variable2 reflects the engine's RPM (diesel) or Tractive Force (electric) or cylinder pressure (steam)
+  - Variable2 reflects the engine's RPM (diesel) or Tractive Force (electric) or cylinder pressure (steam). Where a Booster Engine is fitted, 
+  then ``Variable2BoosterControlled`` can be used to control cylinder pressure for booster engines on steam locomotives.
 
   - Variable3 reflects the dynamic brake (diesel | electric) or fuel rate (steam)
 

Source/ORTS.Common/Input/UserCommand.cs

@@ -195,8 +195,9 @@ public enum UserCommand
         [GetString("Control Blower Decrease")] ControlBlowerDecrease,
         [GetString("Control Steam Heat Increase")] ControlSteamHeatIncrease,
         [GetString("Control Steam Heat Decrease")] ControlSteamHeatDecrease,
-        [GetString("Control Steam Booster Increase")] ControlSteamBoosterIncrease,
-        [GetString("Control Steam Booster Decrease")] ControlSteamBoosterDecrease,
+        [GetString("Control Steam Booster Air Valve")] ControlSteamBoosterAirValve,
+        [GetString("Control Steam Booster Idle Valve")] ControlSteamBoosterIdleValve,
+        [GetString("Control Steam Booster Latch")] ControlSteamBoosterLatch,
         [GetString("Control Damper Increase")] ControlDamperIncrease,
         [GetString("Control Damper Decrease")] ControlDamperDecrease,
         [GetString("Control Firebox Open")] ControlFireboxOpen,

Source/ORTS.Settings/InputSettings.cs

@@ -356,8 +356,9 @@ static void InitializeCommands(UserCommandInput[] Commands)
             Commands[(int)UserCommand.ControlBlowerIncrease] = new UserCommandKeyInput(0x31);
             Commands[(int)UserCommand.ControlSteamHeatDecrease] = new UserCommandKeyInput(0x20, KeyModifiers.Alt);
             Commands[(int)UserCommand.ControlSteamHeatIncrease] = new UserCommandKeyInput(0x16, KeyModifiers.Alt);
-            Commands[(int)UserCommand.ControlSteamBoosterDecrease] = new UserCommandKeyInput(0x11, KeyModifiers.Shift);
-            Commands[(int)UserCommand.ControlSteamBoosterIncrease] = new UserCommandKeyInput(0x11, KeyModifiers.Alt);
+            Commands[(int)UserCommand.ControlSteamBoosterAirValve] = new UserCommandKeyInput(0x20, KeyModifiers.Control);
+            Commands[(int)UserCommand.ControlSteamBoosterIdleValve] = new UserCommandKeyInput(0x30, KeyModifiers.Control);
+            Commands[(int)UserCommand.ControlSteamBoosterLatch] = new UserCommandKeyInput(0x25, KeyModifiers.Control);
             Commands[(int)UserCommand.ControlBrakeHoseConnect] = new UserCommandKeyInput(0x2B);
             Commands[(int)UserCommand.ControlBrakeHoseDisconnect] = new UserCommandKeyInput(0x2B, KeyModifiers.Shift);
             Commands[(int)UserCommand.ControlCabRadio] = new UserCommandKeyInput(0x13, KeyModifiers.Alt);

Source/Orts.Formats.Msts/CabViewFile.cs

@@ -130,7 +130,10 @@ public enum CABViewControlTypes
         DAMPERS_FRONT,
         DAMPERS_BACK,
         STEAM_HEAT,
-        STEAM_BOOSTER,
+        STEAM_BOOSTER_AIR,
+        STEAM_BOOSTER_IDLE,
+        STEAM_BOOSTER_LATCH,
+        STEAM_BOOSTER_PRESSURE,
         WATER_INJECTOR1,
         WATER_INJECTOR2,
         SMALL_EJECTOR,

Source/Orts.Formats.Msts/SoundManagmentFile.cs

@@ -198,7 +198,7 @@ public struct CurvePoint
 
     public class VolumeCurve
     {
-        public enum Controls { None, DistanceControlled, SpeedControlled, Variable1Controlled, Variable2Controlled, Variable3Controlled, BrakeCylControlled, CurveForceControlled };
+        public enum Controls { None, DistanceControlled, SpeedControlled, Variable1Controlled, Variable1_2Controlled, Variable1_3Controlled, Variable1_4Controlled, Variable2Controlled, Variable2BoosterControlled, Variable3Controlled, BrakeCylControlled, CurveForceControlled };
 
         public Controls Control = Controls.None;
         public float Granularity = 1.0f;
@@ -214,7 +214,11 @@ public VolumeCurve(STFReader stf)
                 case "distancecontrolled": Control = Controls.DistanceControlled; break;
                 case "speedcontrolled": Control = Controls.SpeedControlled; break;
                 case "variable1controlled": Control = Controls.Variable1Controlled; break;
+                case "variable1_2controlled": Control = Controls.Variable1_2Controlled; break;
+                case "variable1_3controlled": Control = Controls.Variable1_3Controlled; break;
+                case "variable1_4controlled": Control = Controls.Variable1_4Controlled; break;
                 case "variable2controlled": Control = Controls.Variable2Controlled; break;
+                case "variable2boostercontrolled": Control = Controls.Variable2BoosterControlled; break;
                 case "variable3controlled": Control = Controls.Variable3Controlled; break;
                 case "brakecylcontrolled": Control = Controls.BrakeCylControlled; break;
                 case "curveforcecontrolled": Control = Controls.CurveForceControlled; break;
@@ -339,7 +343,7 @@ public Discrete_Trigger(STFReader f)
     public class Variable_Trigger : Trigger
     {
         public enum Events { Speed_Inc_Past, Speed_Dec_Past, Distance_Inc_Past, Distance_Dec_Past,
-        Variable1_Inc_Past, Variable1_Dec_Past, Variable2_Inc_Past, Variable2_Dec_Past, Variable3_Inc_Past, Variable3_Dec_Past, BrakeCyl_Inc_Past, BrakeCyl_Dec_Past, CurveForce_Inc_Past, CurveForce_Dec_Past
+        Variable1_Inc_Past, Variable1_2_Inc_Past, Variable1_3_Inc_Past, Variable1_4_Inc_Past, Variable1_Dec_Past, Variable1_2_Dec_Past, Variable1_3_Dec_Past, Variable1_4_Dec_Past, Variable2_Inc_Past, Variable2_Dec_Past, Variable3_Inc_Past, Variable3_Dec_Past, BrakeCyl_Inc_Past, BrakeCyl_Dec_Past, CurveForce_Inc_Past, CurveForce_Dec_Past
         };
 
         public Events Event;
@@ -370,7 +374,13 @@ public Variable_Trigger(STFReader f)
                         break;
                     }
                 case "variable1_inc_past": Event = Events.Variable1_Inc_Past; break;
+                case "variable1_2_inc_past": Event = Events.Variable1_2_Inc_Past; break;
+                case "variable1_3_inc_past": Event = Events.Variable1_3_Inc_Past; break;
+                case "variable1_4_inc_past": Event = Events.Variable1_4_Inc_Past; break;
                 case "variable1_dec_past": Event = Events.Variable1_Dec_Past; break;
+                case "variable1_2_dec_past": Event = Events.Variable1_2_Dec_Past; break;
+                case "variable1_3_dec_past": Event = Events.Variable1_3_Dec_Past; break;
+                case "variable1_4_dec_past": Event = Events.Variable1_4_Dec_Past; break;
                 case "variable2_inc_past": Event = Events.Variable2_Inc_Past; break;
                 case "variable2_dec_past": Event = Events.Variable2_Dec_Past; break;
                 case "variable3_inc_past": Event = Events.Variable3_Inc_Past; break;

Source/Orts.Simulation/Common/Commands.cs

@@ -1575,21 +1575,64 @@ public override void Redo()
     // Steam controls
 
     // Steam booster command
+
     [Serializable()]
-    public sealed class ContinuousSteamBoosterCommand : ContinuousCommand
+    public sealed class ToggleSteamBoosterAirCommand : Command
     {
         public static MSTSSteamLocomotive Receiver { get; set; }
 
-        public ContinuousSteamBoosterCommand(CommandLog log, int injector, bool toState, float? target, double startTime)
-            : base(log, toState, target, startTime)
+        public ToggleSteamBoosterAirCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            if (Receiver == null) return;
+            Receiver.ToggleSteamBoosterAir();
+            // Report();
+        }
+    }
+
+    // Steam Booster Idle Valve
+
+    [Serializable()]
+    public sealed class ToggleSteamBoosterIdleCommand : Command
+    {
+        public static MSTSSteamLocomotive Receiver { get; set; }
+
+        public ToggleSteamBoosterIdleCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            if (Receiver == null) return;
+            Receiver.ToggleSteamBoosterIdle();
+            // Report();
+        }
+    }
+
+    // Steam Booster Latch
+
+    [Serializable()]
+    public sealed class ToggleSteamBoosterLatchCommand : Command
+    {
+        public static MSTSSteamLocomotive Receiver { get; set; }
+
+        public ToggleSteamBoosterLatchCommand(CommandLog log)
+            : base(log)
         {
             Redo();
         }
 
         public override void Redo()
         {
             if (Receiver == null) return;
-            Receiver.SteamBoosterChangeTo(ToState, Target);
+            Receiver.ToggleSteamBoosterLatch();
             // Report();
         }
     }

Source/Orts.Simulation/Common/Events.cs

@@ -216,6 +216,8 @@ public enum Event
         BrakePipePressureStoppedChanging,
         CylinderCocksOpen,
         CylinderCocksClose,
+        BoosterCylinderCocksOpen,
+        BoosterCylinderCocksClose,
         SecondEnginePowerOff,
         SecondEnginePowerOn,
 
@@ -272,8 +274,6 @@ public enum Event
 
         MPCChangePosition,
 
-        SteamBoosterChange,
-
     }
 
     public static class Events
@@ -548,7 +548,8 @@ public static Event From(Source source, int eventID)
 
                         case 310: return Event.MPCChangePosition;
 
-                        case 320: return Event.SteamBoosterChange;
+                        case 321: return Event.BoosterCylinderCocksOpen;
+                        case 322: return Event.BoosterCylinderCocksClose;
 
                         default: return 0;
                     }

Source/Orts.Simulation/Simulation/Confirmer.cs

@@ -66,7 +66,9 @@ public enum CabControl {
       , FiringIsManual
       , FireShovelfull
       , CylinderCocks
-      , SteamBooster
+      , SteamBoosterAir
+      , SteamBoosterIdle
+      , SteamBoosterLatch
       , CylinderCompound
       , LargeEjector
       , SmallEjector
@@ -217,7 +219,9 @@ public Confirmer(Simulator simulator, double defaultDurationS)
                 , new string [] { GetString("Manual Firing"), GetString("off"), null, GetString("on") } 
                 , new string [] { GetString("Fire"), null, null, GetString("add shovel-full") }
                 , new string [] { GetString("Cylinder Cocks"), GetString("close"), null, GetString("open") }
-                , new string [] { GetString("SteamBooster"), null, null, null, GetString("decrease"), GetString("increase") }
+                , new string [] { GetString("Steam Booster Air Valve"), GetString("close"), null, GetString("open") }
+                , new string [] { GetString("Steam Booster Idle Valve"), GetString("idle"), null, GetString("run") }
+                , new string [] { GetString("Steam Booster Latch"), GetString("opened"), null, GetString("locked") }
                 , new string [] { GetString("Cylinder Compound"), GetString("close"), null, GetString("open") }
                 , new string [] { GetString("LargeEjector"), null, null, null, GetString("decrease"), GetString("increase") }
                 , new string [] { GetString("SmallEjector"), null, null, null, GetString("decrease"), GetString("increase") }

Source/Orts.Simulation/Simulation/RollingStocks/MSTSDieselLocomotive.cs

@@ -760,7 +760,7 @@ protected override void UpdateTractiveForce(float elapsedClockSeconds, float t,
                 DieselEngines.HandleEvent(PowerSupplyEvent.StopEngine);
             }
 
-            ApplyDirectionToTractiveForce();
+            ApplyDirectionToTractiveForce(ref TractiveForceN, 0);
 
             // Calculate the total tractive force for the locomotive - ie Traction + Dynamic Braking force.
             // Note typically only one of the above will only ever be non-zero at the one time.