Merge branch 'master' into creation_automation

Author: SteelFill

Source/Documentation/Manual/driving.rst

@@ -202,7 +202,8 @@ F1 Information Monitor
 ----------------------
 
 The F1 key displays the following set of panels in a tabbed format, 
-selected by clicking with the mouse on the desired heading:
+selected by clicking with the mouse on the desired heading or
+using ``<Shift+F1>`` to step through the tabs:
 
 ``Key Commands``: displays the actions of the keyboard keys
 
@@ -231,6 +232,11 @@ completed, the string ``Done`` appears in the last column:
 
 ``Procedures``: basic instructions for driving trains in Open Rails.
 
+``Train Info``: information about the player train.
+
+.. image:: images/driving-traininfo.png
+  :align: center
+  :scale: 80%
 
 F3 
 ----------------
@@ -464,6 +470,77 @@ specified by the player:
 
 .. image:: images/driving-train-names-multiplayer.png
 
+Alt-F7 Train Forces
+-------------------
+
+Pressing ``<Alt+F7>`` opens the Train Forces window.
+It shows the forces along the player's train in bar-graph form.
+The window is sized to fit the train (graph), with a minimum size for short trains,
+and a maximum size for very long trains.
+Scrolling may be required to see the end of the train, or the end of the text line.
+
+.. image:: images/driving-trainforces.png
+  :align: center
+  :scale: 80%
+
+The train is shown as a white line; locomotives are shown in blue.
+The front of the train is to the left.
+
+``Coupler Force``
+'''''''''''''''''
+
+Shows the length-wise pull or push force at each coupling, as a colored bar graph.
+Up (positive) is pull, down (negative) is push.
+The scale is determined by the weakest coupler in the train.
+The steps are non-linear, to provide more sensitivity near the breaking point.
+
+Note: Because the graph is scaled by the weakest car,
+a red bar may not mean that the coupler will break.
+When the car has a higher coupler strength, it can tolerate higher forces than the weakest car.
+
+``Derail Force``
+''''''''''''''''
+
+Shows the sideway push or pull at the wheels as a colored bar graph.
+Up (positive) is pull to the inside (stringline), down (negative) is push to the outside (jackknife).
+The scale is determined by the car with the lowest axle-load (lowest vertical force).
+The steps are non-linear, to provide more sensitivity near the derailing point.
+But this is less effective for lateral forces, as the force is proportional to the curve radius,
+which changes in discrete steps (MSTS legacy).
+
+Note: Because the graph is scaled by the most susceptible car,
+a red bar may not mean that the car will derail.
+When the car has a higher vertical force, it can tolerate higher lateral forces than the most susceptible car.
+
+
+``Brake Force``
+'''''''''''''''
+
+Shows the braking force of each car as a bar graph.
+The scale is determined by the car with the smallest brake force (generally lowest weight).
+The steps are non-linear, to provide more sensitivity near the small brake applications.
+As the weight (and thus brake force varies greatly between cars (and especially engines),
+the graph can be quite jagged, even though all brake cylinders have the same pressure.
+Locomotives will show a full bar long before the brakes are fully applied.
+
+Dynamic braking is shown in blue (unless there also is a greater force from the air-brakes).
+
+``Text Line``
+'''''''''''''
+
+The text line at the bottom shows the following information.
+
+- Max Coupler: The current maximum coupler force within the train,
+  and the car (count from front, including locomotives) where the maximum force is.
+- Max Derail: The current maximum derail force within the train,
+  and the car (count from front, including locomotives) where the maximum force is.
+- Low Coupler: The lowest coupler strength within the train.
+- Low Derail: The lowest derail force within the train.
+  This is an estimate, based on the vertical force.
+  Dynamic factors also affect the force needed to derail.
+
+It may be necessary to scroll to see the rightmost parts of the line.
+
 F8 Switch Monitor
 -----------------
 

Source/Documentation/Manual/images/driving-trainforces.png

@@ -614,7 +614,7 @@ AE in the .srv file as "Efficiency".
 
 If the AI train makes station stops, its maxspeed depends from the "Performance" 
 parameter for every route section, as can be seen and defined in the AI train 
-timetable (that is maxspeed is the product of the first MAxVelocity parameter by 
+timetable (that is maxspeed is the product of the first MaxVelocity parameter by 
 the "Performance" parameter divided by 100).
 
 Such performance parameter list is written (divided by 100) by the AE in 
@@ -632,6 +632,8 @@ This corresponds to MSTS behaviour.
 Moreover the Efficiency parameter is used also to compute acceleration and 
 braking curves.
 
+.. _operation-speed:
+
 Calculation of Train Speed Limit
 --------------------------------
 

Source/Documentation/Manual/images/driving-traininfo.png

@@ -450,6 +450,7 @@ locomotive (regardless of transmission type) are as follows:
    single: MaxPower
    single: MaxForce
    single: MaxContinuousForce
+   single: ORTSTractiveForceIsPowerLimited
 
 ``ORTSDieselEngineMaxPower`` ==> sets the maximum power output at the 
 shaft of the diesel engine (or prime mover).
@@ -463,6 +464,9 @@ wheels when starting.
 continuously supply to the wheels without exceeding the design specifications. 
 Typically this is linked to a particular speed (see next parameter).
 
+``ORTSTractiveForceIsPowerLimited`` ==> determines if tractive force curves
+shall be limited to the available output power from the diesel engine.
+
 .. index::
    single: ORTSSpeedOfMaxContinuousForce
    single: MaxVelocity
@@ -1166,6 +1170,67 @@ with the ``ORTSTractionMotorType ( AC ) `` parameter, to be inserted in the Engi
 section of the ENG file. The use of this motor will have an impact on wheel slip,
 because the wheel speed never exceeds the frequency of the rotating magnetic field.
 
+Traction force retardation
+''''''''''''''''''''''''''
+
+.. index::
+    single: ORTSTractiveForceRampUpRate
+    single: ORTSTractiveForceRampDownRate
+    single: ORTSTractiveForceRampDownToZeroRate
+    single: ORTSTractivePowerRampUpRate
+    single: ORTSTractivePowerRampDownRate
+    single: ORTSTractivePowerRampDownToZeroRate
+    single: ORTSDynamicBrakeForceRampUpRate
+    single: ORTSDynamicBrakeForceRampDownRate
+    single: ORTSDynamicBrakeForceRampDownToZeroRate
+    single: ORTSDynamicBrakePowerRampUpRate
+    single: ORTSDynamicBrakePowerRampDownRate
+    single: ORTSDynamicBrakePowerRampDownToZeroRate
+    single: ORTSDelayTimeBeforeUpdating
+
+When the driver sets full throttle, the control electronics may not apply the full
+tractive force instantly, but it will instead linearly apply force until reaching
+the target demand. This can be tuned both for traction and dynamic braking by inserting
+``ORTSTractiveForceRampUpRate``, ``ORTSTractiveForceRampDownRate``,
+``ORTSTractiveForceRampDownToZeroRate``, ``ORTSDynamicBrakeForceRampUpRate``,
+``ORTSDynamicBrakeForceRampDownRate`` and ``ORTSDynamicBrakeForceRampDownToZeroRate``
+in the .eng file. The value of each parameter determines the force increase/decrease
+rate. To include ramp up/down times also for power, use the equivalent
+``ORTSTractivePowerRampUpRate``, ``ORTSTractivePowerRampDownRate``,
+``ORTSTractivePowerRampDownToZeroRate``, ``ORTSDynamicBrakePowerRampUpRate``,
+``ORTSDynamicBrakePowerRampDownRate`` and ``ORTSDynamicBrakePowerRampDownToZeroRate``
+parameters.
+
+Example::
+
+  Engine (
+    ORTSTractiveForceRampUpRate ( 50kN/s )
+    ORTSTractiveForceRampDownRate ( 50kN/s )
+    ORTSTractiveForceRampDownToZeroRate ( 100kN/s )
+    ORTSDynamicBrakePowerRampUpRate ( 1000kW/s )
+    ORTSDynamicBrakeForceRampDownRate ( 50kN/s )
+  )
+
+Another possibility to avoid sudden variations in tractive force while the driver
+is moving the throttle, is to only update the throttle/brake demand when the lever
+has not been moved for a defined amount of time. This can be implemented using the
+``ORTSDelayTimeBeforeUpdating``, which has to be inserted for the desired
+controller in the ``EngineControllers`` block.
+
+Example::
+
+  Engine (
+    EngineControllers (
+      Throttle ( 0 1 0.1 0
+        NumNotches ( 0 )
+        ORTSDelayTimeBeforeUpdating ( 0.5s )
+      )
+      Brake_Dynamic ( 0 1 0.1 0
+        NumNotches ( 0 )
+        ORTSDelayTimeBeforeUpdating ( 1s )
+      )
+    )
+  )
 
 Steam Locomotives
 -----------------