openrails
diff --git a/‎Source/Documentation/How to Provide Track Profiles for Open Rails Dynamic Track.docm‎
-1.24 MB b/‎Source/Documentation/How to Provide Track Profiles for Open Rails Dynamic Track.docm‎
-1.24 MB
diff --git a/‎Source/Documentation/Manual/appendices.rst‎
Lines changed: 4 additions & 8 deletions b/‎Source/Documentation/Manual/appendices.rst‎
Lines changed: 4 additions & 8 deletions
diff --git a/‎Source/Documentation/Manual/cabs.rst‎
Lines changed: 18 additions & 0 deletions b/‎Source/Documentation/Manual/cabs.rst‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎Source/Documentation/Manual/features-rollingstock.rst‎
Lines changed: 90 additions & 2 deletions b/‎Source/Documentation/Manual/features-rollingstock.rst‎
Lines changed: 90 additions & 2 deletions
diff --git a/‎Source/Documentation/Manual/features-route.rst‎
Lines changed: 9 additions & 111 deletions b/‎Source/Documentation/Manual/features-route.rst‎
Lines changed: 9 additions & 111 deletions
diff --git a/‎Source/Documentation/Manual/news.rst‎
Lines changed: 0 additions & 1 deletion b/‎Source/Documentation/Manual/news.rst‎
Lines changed: 0 additions & 1 deletion
@@ -64,16 +64,12 @@ 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                                   legacy dynamic brake parameters use mph default
-\                                                   ft/s                        feet per second
-\                                                   in/s                        inches per second
+\                                                   kmh         kmh             misspelling accepted by MSTS
+\                                       kmph
+\                       mph             dynamic     mph         mph             miles per hour 
+                                        brake
 Frequency               Hz                          Hz                          Hertz
 \                                                   rps                         revolutions per second
 \                                                   rpm
 
@@ -166,6 +166,24 @@ The following controls are available for the cabview:
 - ``ORTS_ELECTRIC_TRAIN_SUPPLY_COMMAND_SWITCH`` can be used to control the electric train supply switch
 - ``ORTS_ELECTRIC_TRAIN_SUPPLY_ON`` can be used to indicate that the electric train supply line is powered on
 
+.. _cabs-voltmeters:
+
+Voltmeters
+----------
+
+.. index::
+   single: LINE_VOLTAGE
+   single: ORTS_PANTOGRAPH_VOLTAGE_AC
+   single: ORTS_PANTOGRAPH_VOLTAGE_DC
+   single: ORTS_BATTERY_VOLTAGE
+
+The following voltmeters are available for the cabview:
+
+- ``LINE_VOLTAGE`` indicates the line voltage
+- ``ORTS_PANTOGRAPH_VOLTAGE_AC`` indicates the line voltage when operating on AC lines
+- ``ORTS_PANTOGRAPH_VOLTAGE_DC`` indicates the line voltage when operating on DC lines
+- ``ORTS_BATTERY_VOLTAGE`` indicates the vehicle's battery voltage
+
 .. _cabs-dieselenginesonoff:
 
 Controls to switch on and off diesel engines
 
@@ -1918,6 +1918,9 @@ Scripts will run if referenced by OR-specific fields in the .eng file.
    single: ORTSEngineBrakeController
    single: ORTSCircuitBreaker
    single: ORTSTractionCutOffRelay
+   single: ORTSPantographSelector
+   single: ORTSVoltageSelector
+   single: ORTSPowerLimitationSelector
    single: ORTSPowerSupply
    single: ORTSTrainControlSystem
 
@@ -1949,6 +1952,15 @@ Scripts will run if referenced by OR-specific fields in the .eng file.
    * - Passenger car power supply
      - ``ORTS.Scripting.Api.PassengerCarPowerSupply``
      - ``Wagon ( ORTSPowerSupply ( "DemoPower.cs" ) )``
+   * - Pantograph selector
+     - ``ORTS.Scripting.Api.PantographSelector``
+     - ``Engine ( ORTSPantographSelector ( Script ( "DemoPantographSelector.cs" ) ) )``
+   * - Voltage selector
+     - ``ORTS.Scripting.Api.VoltageSelector``
+     - ``Engine ( ORTSVoltageSelector ( Script ( "DemoVoltageSelector.cs" ) ) )``
+   * - Power limitation selector
+     - ``ORTS.Scripting.Api.PowerLimitationSelector``
+     - ``Engine ( ORTSPantographSelector ( Script ( "DemoPowerLimitator.cs" ) ) )``
    * - Train Control System
      - ``ORTS.Scripting.Api.TrainControlSystem``
      - ``Engine ( ORTSTrainControlSystem ( "DemoTCS.cs" ) )``
@@ -2131,14 +2143,66 @@ Use the following .eng parameter to load a traction cut-off relay script::
   )
 
 ``ORTSTractionCutOffRelay`` refers to the traction cut-off relay script in the engine's ``Script`` 
-subfolder. For this field, the .cs extension is optional. "Automatic" and "Manual" load the generic OR 
-traction cut-off relay implementation, so do `not` use these names for your own script.
+subfolder. For this field, the .cs extension is optional. Alternatively, there are several
+built-in OR traction cut-off relay implementations:
+
+- "Automatic": no driver intervention required, circuit breaker is closed when conditions are met.
+- "Manual": a traction cut-off switch with open and closed positions.
+- "PushButtons": a traction cut-off relay with dedicated open and close buttons.
+
+Please do `not` use these names for your own script, since the generic implementation will
+be loaded instead.
 
 ``ORTSTractionCutOffRelayClosingDelay`` refers to the delay between the closing command of the traction cut-off relay
 and the effective closing of the relay.
 
+.. _features-scripting-powerselectors
+
+Pantograph, voltage and power limitation selectors
+--------------------------------------------------
+
+Available for electric locomotives only. The scripts control 
+the behavior of the locomotive's 
+:ref:`pantograph selector <physics-pantograph-selector>`, 
+:ref:`voltage selector <physics-voltage-selector>` and 
+:ref:`power limitation selector <physics-power-limitation-selector>` respectively.
+
+.. index::
+   single: ORTSPantographSelector
+   single: ORTSVoltageSelector
+   single: ORTSPowerLimitationSelector
+
+Use the following .eng parameters to load power selector scripts::
+
+  Engine (
+      ORTSPantographSelector ( 
+        Script ( "YourPSScript.cs" )
+        SelectorPositions ( ... )
+      )
+      ORTSVoltageSelector ( 
+        Script ( "YourVSScript.cs" )
+        SelectorPositions ( ... )
+      )
+      ORTSPowerLimitationSelector ( 
+        Script ( "YourPLSScript.cs" )
+        SelectorPositions ( ... )
+      )
+  )
+
+``Script`` refers to the circuit breaker script in the engine's ``Script`` 
+subfolder. For this field, the .cs extension is optional. Alternatively, there are several
+built-in OR selector implementations which can be used if custom features such as interlocking
+with other devices are not required:
+
+- "Default": a selector with sequential positions.
+- "Circular": same as above, but the first position follows again after the last one.
+
+Please do `not` use these names for your own script, since the generic implementation will
+be loaded instead.
+
 .. _features-scripting-powersupply:
 
+
 Diesel and electric power supply
 --------------------------------
 
@@ -2158,6 +2222,7 @@ Use the following .eng parameter to load a power supply script::
 
   Engine (
       ORTSPowerSupply ( "YourEPS.cs" )
+      ORTSPowerSupplyParameters ( "YourEPS.ini" )
       ORTSPowerOnDelay ( 5s )
       ORTSAuxPowerOnDelay ( 10s )
   )
@@ -2166,6 +2231,12 @@ Use the following .eng parameter to load a power supply script::
 subfolder. For this field, the .cs extension is optional. "Default" will load the generic OR power supply 
 implementation, so do `not` use this name for your own script.
 
+``ORTSPowerSupplyParameters``, an optional field, refers to an .ini file, 
+also in the ``Script`` subfolder, whose parameters will be made available to the 
+power supply script through the ``GetBoolParameter()``, ``GetIntParameter()``, 
+``GetFloatParameter()``, and ``GetStringParameter()`` methods. This .ini file provides for easy customization of 
+the behavior of the power supply script by end users.
+
 ``ORTSPowerOnDelay`` refers to the delay between the closing of the circuit breaker or the traction cut-off relay
 and the availability of the power for traction.
 
@@ -2547,6 +2618,23 @@ which may be used this way within the script:
 
 so that, instead of ORTS_TCSnn the related mnemonic string is displayed.
 
+Generic cabview controls are also available for the Power Supply subsystem. They are named ORTS_POWER_SUPPLY1, ORTS_POWER_SUPPLY2
+and so on in the cabview file. Their usage is the same as for the TCS controls.
+
+Events related to power supply controls are made available to power supply scripts via ``TCSEvent.GenericTCSButtonPressed``, 
+``TCSEvent.GenericTCSButtonReleased``, ``TCSEvent.GenericTCSSwitchOff`` and ``TCSEvent.GenericTCSSwitchOn`` events, 
+received asynchronously by script through the method:
+
+.. code-block:: csharp
+
+    public override void HandleEvent(PowerSupplyEvent evt, string message)
+
+As for the TCS buttons, message is a string representing the control number with zero-base indexing
+(e.g. "5" corresponds to ORTS_POWER_SUPPLY6).
+
+SetCabDisplayControl and SetCustomizedCabviewControlName methods, which work in the same
+way as their TCS counterparts, are accessible from all power supply scripts.
+
 Helper classes
 --------------
 3 helper classes are available in the ``Orts.Scripting.Api`` namespace:
 
@@ -858,126 +858,24 @@ 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
 
 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.
 
-The superelevation standard defined here will control the simulated level of superelevation on
-each track section on the entire route and, if enabled in the options, the amount of visual
-superelevation generated by the dynamic track system.
-
-To define a superelevation standard, add a ``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.
 
-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 )
-    )
+The values are assigned by inserting the following parameter::
 
-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
-        ........
-    )
+   ORTSTrackSuperElevation ( x y .......... )
    
-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
+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 
 y value needs to be used for succeeding values of curve radius. Where the y value changes between 
-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.
+curve radii, then Open Rails will extrapolate the y value between the two points. 
 
 
 Overhead (catenary) wire
 
@@ -39,7 +39,6 @@ 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