Merge branch 'master' into bugfix/Fix-TrainCarOperations-TrainOperationsViewer-overlap

Author: mbm-OR

Source/Documentation/How to Provide Track Profiles for Open Rails Dynamic Track.docm

@@ -64,12 +64,16 @@ Volumetric Flow         m^3/s           air flow    m^3/s
 \                                                   L/min
 \                                                   L/s
 Speed                   m/s             other       m/s         m/s             meter per second
+\                                                   cm/s                        centimeters per second
+\                                                   mm/s                        millimeters per second
 \                                                   km/h
 \                                                   kph         kph             kilometer per hour
-\                                                   kmh         kmh             misspelling accepted by MSTS
-\                                       kmph
-\                       mph             dynamic     mph         mph             miles per hour 
-                                        brake
+\                                                   kmh         kmh,            misspelling accepted by MSTS
+                                                                kmph
+\                       mph             dynamic     mph         mph             miles per hour, 
+                                        brake                                   legacy dynamic brake parameters use mph default
+\                                                   ft/s                        feet per second
+\                                                   in/s                        inches per second
 Frequency               Hz                          Hz                          Hertz
 \                                                   rps                         revolutions per second
 \                                                   rpm

Source/Documentation/Manual/appendices.rst

@@ -138,6 +138,9 @@ A list of the available .eng file CC parameters follows here below.
    "ModeSwitchAllowedWithThrottleNotAtZero", "Switch from manual to auto and vice-versa can occur also when throttle lever is not at 0", "Boolean", "FALSE"
    "DisableManualSwitchToAutoWhenSetSpeedNotAtTop", "Manual Switch to Cruise Control Auto Mode can't occur when speed is not set at maximum value and at the same moment train speed is not 0", "Boolean", "FALSE"
    "UseTrainBrakeAndDynBrake", "CC uses train brake and dyn brake together", "Boolean", "FALSE"
+   "UseDynBrake", "CC uses dyn brake", "Boolean", "TRUE"
+   "TrainBrakeCommandHasPriorityOverCruiseControl", "A manual train braking inhibits Cruise Control to use both dynamic braking and tractive force", "Boolean", "TRUE"
+   "TrainBrakeCommandHasPriorityOverAcceleratingCruiseControl", "A manual train braking inhibits Cruise Control to use tractive force", "Boolean", "TRUE"
    "SpeedDeltaToEnableTrainBrake", "This is the minimum speed delta between actual speed and desired speed for the CC to use also the train brake", "Float(speed)", "5m/s"
    "SpeedDeltaToEnableFullTrainBrake", "This is the minimum speed delta between actual speed and desired speed for the CC to use also the train brake with no reduced intensity", "Float(speed)", "10m/s"
    "TrainBrakeMinPercentValue", "This is the minimum train brake percent used by the CC. 0 means no braking, 100 means full service braking", "Float(percent)", "30"

Source/Documentation/Manual/cruisecontrol.rst

@@ -22,7 +22,7 @@ Rolling Stock
 - 3D cabs add realism.
 - OR graphics renders the results of the rolling stock developers at higher 
   resolution.
-- Rolling stock running on super-elevated track improves gaming experience.
+- Rolling stock running on superelevated track improves gaming experience.
 
 Routes
 ======

Source/Documentation/Manual/developing.rst

@@ -1411,7 +1411,8 @@ Changing the Train Driven by the Player
 General
 -------
 
-This function only works in activity mode, and allows the player to select 
+This function works in activity mode as well as in timetable mode, 
+and allows the player to select 
 another (existing) train from a list and to start driving it.
 
 This function can be called more than once. A new information window has 
@@ -1453,17 +1454,20 @@ completely appeared on the screen - if it is far away from the player train
 this can require several seconds to load the *world* around the train) the 
 switch of control occurs. 
 
-The AI train string now becomes red and is moved to the first position.The 
-train can be driven, or set to autopilot mode. The former player train 
-becomes an AI train.
+The AI train string now becomes red and is moved to the first position.
+In timetable mode the new player train is automatically set to autopilot mode,
+while this does not apply to activity mode. However in both timetable and 
+activity mode the player can switch forth and back to autopilot mode. 
+The former player train becomes an AI train.
 
 Here is the final situation:
 
 .. image:: images/driving-train-list-3.png
     :align: center
     :scale: 80%
 
-If the second left-click was performed with the Shift key down, the former 
+In activity mode only, if the second left-click was performed with the Shift 
+key down, the former 
 player train still becomes an AI train, but it is put in a suspended mode 
 (only if its speed is 0). It won't move until it becomes a player train 
 again. A suspended train is shown in orange color on the Train List window.
@@ -1472,7 +1476,8 @@ The new player train can can be switched to manual mode, can also request to
 pass signals at danger with the ``<Tab>`` command, and can be moved outside 
 of its original path. However before switching control to still another train, 
 the new player train must be returned to the original path or put in suspend 
-mode; or else it will disappear, as occurs for AI trains running outside their 
+mode (last is possible only in activity mode); or else it will disappear, 
+as occurs for AI trains running outside their 
 path.
 
 The sequence may be restarted to switch to a new train or to switch back to 
@@ -1482,15 +1487,9 @@ Train switching also works in activity mode together with multiplayer mode,
 in the sense that the dispatcher player can switch its played train, and 
 the related information is sent to the client players.
 
-The Train List window is also available in 
-:ref:`Timetable mode <start-timetable>`. In this case the 
-names of all trains except the player train are shown in white (they can't 
-be driven), however with a single click on a train in the window the 
-external view cameras become linked to that train, as occurs with the Alt-9 
-command described :ref:`further below <driving-changing-view>`.
 
-Switching to a static train
----------------------------
+Switching to a static train (only activity mode)
+------------------------------------------------
 
 In the Train List window the drivable static consists (that is the ones 
 that have at least an engine provided with a cab) are also listed (in 

Source/Documentation/Manual/driving.rst

@@ -1482,7 +1482,8 @@ containers of same length).
 Multiple passenger viewpoints
 =============================
 
-Additional passenger viewpoints may be added within a carriage that 
+Additional passenger viewpoints may be added within a carriage or 
+locomotive that 
 is provided with passenger viewpoint.
 
 .. index::
@@ -1492,7 +1493,7 @@ is provided with passenger viewpoint.
    single: RotationLimit
    single: StartDirection
 
-Such additional passenger viewpoints are defined within an include file 
+Such additional passenger viewpoints may be defined within an include file 
 with the format shown in 
 following example for the legacy oebarcar.wag (located in the 380 folder) 
 MSTS wagon::
@@ -1519,6 +1520,9 @@ MSTS wagon::
         )
   )
 
+If the passenger viewpoints are defined in the base .wag or .eng file, they 
+must be defined below the Inside () block.
+
 At runtime, when in passenger view, the player may pass from one viewpoint to 
 the other by pressing Shift-5.
 
@@ -1706,7 +1710,7 @@ needed in the .cvf file (same applies also for wipers, doors and so on as seen f
   ORTS_EXTERNALLEFTWINDOWREAR
   ORTS_EXTERNALRIGHTWINDOWREAR
 
-LEFTWINDOW and RIGHTWINDOW are the names of the controls that can be inserted in the 
+ORTS_LEFTWINDOW and ORTS_RIGHTWINDOW are the names of the controls that can be inserted in the 
 .cvf file and in the 3Dcab .s file to command the state change with the mouse.
 
 Here is an example of the animation of the left window in a 2D cab::

Source/Documentation/Manual/features-rollingstock.rst

@@ -858,24 +858,147 @@ Defining Curve Superelevation
 
 .. index::
    single: ORTSTrackSuperElevation
+   single: ORTSSuperElevation
+   single: MaxFreightUnderbalance
+   single: MaxPassengerUnderbalance
+   single: MinimumCant
+   single: MaximumCant
+   single: Precision
+   single: MaxRunOffSlope
+   single: MaxRunOffSpeed
+   single: MinimumSpeed
+   single: MaximumSpeed
+   single: ORTSForceSuperElevation
+   single: TrackGauge
 
 This feature allows curves within the route to be assigned a value for superelevation. It
-is inserted either in the route's root .trk file or in the "Include" .trk file.
+is inserted either in the route's root .trk file or in the "Include" .trk file. Before
+starting, the predominant gauge of track on the route should be given using the legacy
+``TrackGauge`` token. The default units used are meters, though other units are supported
+as in other parts of the program. If ``TrackGauge`` is set to 0 (like most MSTS routes)
+or not present in the .trk file, then the default gauge given in the
+:ref:`Superelevation Options <options-superelevation>` will be used for superelevation calculations.
+
+Defining a superelevation standard in the .trk file will control both the simulated level of
+superelevation on each track section on the entire route and the amount of visual
+superelevation generated by the dynamic track system. However, in some cases it may be desired
+to manually influence the use of visual superelevation due to (un)desired graphical effects.
+The token ``ORTSForceSuperElevation`` can be given a true/false value to force enable/disable
+visual superelevation effects regardless of user settings and other ORTS behaviors. Adding
+this token will have no impact on the physical simulation of superelevation, this only forces
+the graphical elements to be enabled or disabled.
+
+To define a superelevation standard, add an ``ORTSSuperElevation`` block to the route's .trk
+file and add some (or all) of the following parameters inside the ``ORTSSuperElevation`` block:
+
+- ``MaxFreightUnderbalance`` -- The maximum amount (using units of length) of cant deficiency/underbalance
+  that should be allowed for trains travelling at the freight speed limit. Larger allowed underbalance
+  results in less extreme superelevation. (Default 100 mm for metric routes, 2 in for imperial routes.)
+- ``MaxPassengerUnderbalance`` -- The maximum amount (using units of length) of cant deficiency/underbalance
+  that should be allowed for trains travelling at the passenger speed limit. (Default 150 mm / 3 in.)
+  For comfort reasons, the underbalance values should be equal to or less than the
+  ``ORTSUnbalancedSuperElevation`` value used by the rolling stock on the route. If the superelevation
+  required to achieve the max passenger underbalance is different from that required for freight, the
+  curve will use whichever superelevation is larger (the actual amount of underbalance may be lower).
+- ``MinimumCant`` -- If a curve needs superelevation, the amount of superelevation will be no lower than
+  this value (given in units of length). (Default 10 mm / 0.5 in.)
+- ``MaximumCant`` -- Sets the maximum amount of superelevation (units of length) that any curve is allowed
+  to have, regardless of other factors. Usually curves should be designed to avoid reaching this limit, as
+  exceeding the limit could result in excessive curve force or even trains toppling over at low speeds.
+  (Default 180 mm / 6 in.)
+- ``Precision`` -- Determines the accuracy (in length) to which the superelevation is maintained. If
+  the superelevation required by a curve is not a nice number, it will be rounded up to the nearest
+  multiple of ``Precision``. (Default 5 mm / 0.25 in.)
+- ``MaxRunOffSlope`` -- Sets a limit on the amount of change in superelevation per unit length along a curve
+  (quantity is unitless). This allows for smooth transition between flat and superelevated track at low speeds.
+  (Default 0.003.)
+- ``MaxRunOffSpeed`` -- Sets a limit on the amount of change in superelevation per second (units of speed) when
+  travelling at the max speed for the curve. This allows for smooth transition between flat and superelevated
+  track at high speeds. (Default 55 mm/sec / 1.5 in/sec.)
+- ``MinimumSpeed`` -- The minimum speed limit required for superelevation to be added to a curve. Useful for
+  preventing superelevation from being generated in yards. (Default 25 kmh / 15 mph.)
+- ``MaximumSpeed`` -- The maximum speed limit allowed for superelevation to be added to a curve. This
+  is only useful if a route needs multiple sets of superelevation settings. See section below for a
+  description on use of multiple superelevation standards. (Default unlimited.)
+
+Any parameters not specified will use the default values, which are suitable for most medium-speed routes.
+Upon route loading, the given parameters will be used to calculate the appropriate amount of superelevation
+for each curve based on the curve radius and speed limits. An example ``ORTSSuperElevation`` block which
+defines the superelevation standard used by Union Pacific is given below::
+
+    ORTSSuperElevation(
+		MaxFreightUnderbalance ( 1in )
+		MaxPassengerUnderbalance ( 3in )
+		MinimumCant ( 0.25in )
+		MaximumCant ( 5in )
+		Precision ( 0.25in )
+		MaxRunOffSlope ( 0.0019 )
+		MaxRunOffSpeed ( 1.25in/s )
+		MinimumSpeed ( 15mph )
+    )
 
-It should be noted that currently this information only applies to physics calculations 
-for superelevation. The visual movement of the train due to superelevation is set within 
-the option menu.
+Note that it is also possible to create a superelevation standard which entirely disables superelevation
+on the route, should the real railroad not use superelevation. This can be achieved by setting
+``MaximumCant ( 0 )`` and leaving all other values default. Note that this disables both physics and visual
+superelevation::
 
-The values are assigned by inserting the following parameter::
+    ORTSSuperElevation(
+		MaximumCant ( 0 )
+    )
 
-   ORTSTrackSuperElevation ( x y .......... )
+More than one ``ORTSSuperElevation`` block can be added to the .trk file to facilitate routes that require
+different superelevation standards for different track speeds (for example, a route with both standard speed
+160 kmh tracks and dedicated 300 kmh high speed tracks). If a track has a speed limit below ``MinimumSpeed``
+or above ``MaximumSpeed``, the track will skip the superelevation standard defined and check the next standard in
+the .trk file to see if the speed limit is in between the min and max of that standard. Only if the track
+speed is out of bounds for every superelevation standard will no superelevation be applied at all. For
+example, to have 3 different types of superelevation on one route, one from 25-60 kmh, another from 60-160 kmh,
+and a third standard for 160 kph and up, the required Minimum/MaximumSpeed settings would look like this::
+
+    ORTSSuperElevation(
+        ...
+		MinimumSpeed ( 25km/h )
+		MaximumSpeed ( 60km/h )
+    )
+    ORTSSuperElevation(
+        ...
+		MinimumSpeed ( 60km/h )
+		MaximumSpeed ( 160km/h )
+    )
+    ORTSSuperElevation(
+        ...
+		MinimumSpeed ( 160km/h )
+    )
+
+Note that the order of the ``ORTSSuperElevation`` blocks is important; they are read from top down
+so the slowest superelevation standard should be on top of all faster superelevation standards.
+
+Open Rails also supports a simpler way to define superelevation based on curve radius only, resulting
+in the same superelevation regardless of track speed. If a railroad uses this simplified method, they
+would provide a table of track curve radii and the superelevation used at that radius (usually also
+including a maximum speed for the curve). This table can then be provided to OR using the
+``ORTSTrackSuperElevation`` parameter in the .trk file::
+
+    ORTSTrackSuperElevation (
+        x1 y1
+        x2 y2
+        ........
+    )
    
-where x and y are a series of paired parameters specifying the curve radius in metres (x value),
-and the amount of superelevation in metres (y value). The statement will take as many paired 
-values as desired. Each paired set of values must have an x and y value present. If it is desired
-to 'hold' a certain value of SuperElevation for a number of different radii curves, then the same 
+Where x and y are a series of paired parameters specifying the curve radius (default meters)
+(x value), and the amount of superelevation (default meters) (y value). The statement will take
+as many paired values as desired, as long as the radius values are in increasing order.
+Each paired set of values must have an x and y value present. If it is desired
+to 'hold' a certain value of superelevation for a number of different radii curves, then the same 
 y value needs to be used for succeeding values of curve radius. Where the y value changes between 
-curve radii, then Open Rails will extrapolate the y value between the two points. 
+curve radii, then Open Rails will interpolate the y value between the two points.
+
+Superelevation calculated using ``ORTSSuperElevation`` will generally override any values
+entered in ``ORTSTrackSuperElevation`` unless the ``ORTSSuperElevation`` block did not specify
+a value for ``MaxFreightUnderbalance`` or ``MaxPassengerUnderbalance``. If neither is given,
+superelevation will be replaced with the value given by ``ORTSTrackSuperElevation``, but will
+be adjusted to match the given values of minimum and maximum cant, precision, and runoff. This
+way, it is possible to represent a wide variety of superelevation configurations.
 
 
 Overhead (catenary) wire

Source/Documentation/Manual/features-route.rst

@@ -24,6 +24,7 @@ What's been added
 - more accurate wheelslip using Polach adhesion
 - duplex and booster steam engines (e.g. T1 class) 
 - cloud-free skies
+- sounds conditional on season, weather and time of day
 - more air and dynamic brake options for locos
 - mouse control for scripted brake controllers
 
@@ -39,6 +40,7 @@ What's been improved
 - controls for electric locos
 - air brake features for both European and American brake systems 
 - accurate friction simulation for 4 types of brake shoes
+- superelevation system rewritten to be smoother and more configurable
 
 
 Other changes

Source/Documentation/Manual/images/content-form-auto-installed.png

@@ -641,7 +641,7 @@ Calculation of Train Speed Limit
   - local signal speed limit
   - local speedpost speed limit
   - local temporary speedpost speed limit
-  - first parameter ``MaxVelocityA`` in ``.con`` file, if bigger than zero and not 
+  - first parameter of ``MaxVelocity`` line in ``.con`` file, if bigger than zero and not 
     equal 40
   - locomotive speed limit in ``.eng`` file in the other cases. 
 
@@ -651,18 +651,11 @@ Calculation of Train Speed Limit
   - local signal speed limit
   - local speedpost speed limit
   - local temporary speedpost speed limit
-  - first parameter ``MaxVelocityA`` in ``.con`` file, if bigger than zero and not 
-    equal 40
+  - first parameter of ``MaxVelocity`` line in ``.con`` file, if bigger than zero and not 
+    equal 40, multiplied by the Efficiency as explained :ref:``here <operation-performance>``
   - locomotive speed limit in ``.eng`` file in the other cases. 
 
 
-  - route speed limit as defined in the ``.trk`` file
-  - local signal speed limit
-  - local speedpost speed limit
-  - local temporary speedpost speed limit
-  - first parameter ``MaxVelocityA`` in ``.con`` file, if bigger than zero, 
-    multiplied by the Efficiency as explained :ref:``here <operation-performance>``.
-
 Start of Run of AI train in a Section Reserved by Another Train
 ---------------------------------------------------------------