Merge branch 'openrails:master' into creation_automation

Author: SteelFill

Build.cmd

@@ -83,8 +83,9 @@ FOR /F "usebackq tokens=1* delims==" %%A IN (`CALL GetVersion.cmd %Mode%`) DO SE
 REM Restore NuGet packages.
 nuget restore Source\ORTS.sln || GOTO :error
 
-REM Recreate Program directory for output.
+REM Recreate Program directory for output and delete previous build files.
 CALL :recreate "Program" || GOTO :error
+CALL :delete "OpenRails-%Mode%*" || GOTO :error
 
 REM Build main program.
 REM Disable warning CS1591 "Missing XML comment for publicly visible type or member".
@@ -126,11 +127,14 @@ IF NOT "%Mode%" == "Unstable" (
 	NET stop ClickToRunSvc
 	NET start ClickToRunSvc
 
-	REM Recreate Documentation folder for output.
-	CALL :recreate "Program\Documentation" || GOTO :error
+	REM Create the documentation folders for output.
+	CALL :create "Program\Documentation" || GOTO :error
+	CALL :create "Program\Documentation\Online" || GOTO :error
+	CALL :create "Program\Documentation\es" || GOTO :error
 
 	REM Compile the documentation.
 	FOR %%E IN (doc docx docm xls xlsx xlsm odt) DO FOR %%F IN ("Source\Documentation\*.%%E") DO ECHO %%~F && OfficeToPDF.exe /bookmarks /print "%%~F" "Program\Documentation\%%~nF.pdf" || GOTO :error
+	FOR %%E IN (doc docx docm xls xlsx xlsm odt) DO FOR %%F IN ("Source\Documentation\Online\*.%%E") DO ECHO %%~F && OfficeToPDF.exe /bookmarks /print "%%~F" "Program\Documentation\Online\%%~nF.pdf" || GOTO :error
 	>"Source\Documentation\Manual\version.py" ECHO version = '%OpenRails_Version%' || GOTO :error
 	>>"Source\Documentation\Manual\version.py" ECHO release = '%OpenRails_Revision%' || GOTO :error
 	PUSHD "Source\Documentation\Manual" && CALL make.bat clean & POPD || GOTO :error
@@ -139,13 +143,13 @@ IF NOT "%Mode%" == "Unstable" (
 	REM Copy the documentation.
 	FOR %%F IN ("Source\Documentation\*.pdf") DO CALL :copy "%%~F" "Program\Documentation\%%~nF.pdf" || GOTO :error
 	CALL :copy "Source\Documentation\Manual\_build\latex\Manual.pdf" "Program\Documentation\Manual.pdf" || GOTO :error
-	CALL :create "Program\Documentation\es"
 	CALL :copy "Source\Documentation\Manual\es\Manual.pdf" "Program\Documentation\es\Manual.pdf" || GOTO :error
 	ROBOCOPY /MIR /NJH /NJS "Source\Documentation\SampleFiles" "Program\Documentation\SampleFiles"
 	IF %ERRORLEVEL% GEQ 8 GOTO :error
 
 	REM Copy the documentation separately.
 	FOR %%F IN ("Program\Documentation\*.pdf") DO CALL :copy "%%~F" "OpenRails-%Mode%-%%~nxF" || GOTO :error
+	FOR %%F IN ("Program\Documentation\Online\*.pdf") DO CALL :copy "%%~F" "OpenRails-%Mode%-%%~nxF" || GOTO :error
 )
 
 IF "%Mode%" == "Stable" (
@@ -161,8 +165,7 @@ IF "%Mode%" == "Stable" (
 )
 
 REM Create binary and source zips.
-CALL :delete "OpenRails-%Mode%*.zip" || GOTO :error
-PUSHD "Program" && 7za.exe a -r -tzip -x^^!*.xml "..\OpenRails-%Mode%.zip" . && POPD || GOTO :error
+PUSHD "Program" && 7za.exe a -r -tzip -x^^!*.xml -x^^!Online "..\OpenRails-%Mode%.zip" . && POPD || GOTO :error
 7za.exe a -r -tzip -x^^!.* -x^^!obj -x^^!lib -x^^!_build -x^^!*.bak "OpenRails-%Mode%-Source.zip" "Source" || GOTO :error
 
 ENDLOCAL

Source/Documentation/Manual/appendices.rst

@@ -678,6 +678,19 @@ The value speed is the required speed value in dimension as set by the relevant
 Inclusion of speed definition is optional and need not be set if only approach control position functions
 are used.
 
+Signal light parameters
+-----------------------
+
+.. index::
+  single: ORTSSignalLightTex
+
+It is possible to have different light textures in the same signal, by inserting
+the following parameter in the signal light definition::
+
+    ORTSSignalLightTex ( "name" )
+
+Where **name** is the name of the texture to be used for the signal light.
+
 Signal aspect parameters
 ------------------------
 The following parameters can be included in signal aspect definitions.

Source/Documentation/Manual/cabs.rst

@@ -61,23 +61,25 @@ The following DMI size variants are available: FullSize (displays the whole DMI)
 The information displayed in the DMI is controlled via the TCS script. For more details,
 see :ref:`C# engine scripting - Train Control System <features-scripting-tcs>`.
 
-.. _cabs-battery-switch:
+.. _cabs-battery:
 
-Battery switch
---------------
+Battery
+-------
 
 .. index::
    single: ORTS_BATTERY_SWITCH_COMMAND_SWITCH
    single: ORTS_BATTERY_SWITCH_COMMAND_BUTTON_CLOSE
    single: ORTS_BATTERY_SWITCH_ON
+   single: ORTS_BATTERY_VOLTAGE
 
-The :ref:`battery switch <physics-battery-switch>` controls the low voltage power supply of the locomotive.
+The :ref:`battery subsystem <physics-battery>` controls the low voltage power supply of the locomotive.
 
 The following controls are available for the cabview:
 
-- ``ORTS_BATTERY_SWITCH_COMMAND_SWITCH`` can be used if the switch is directly controlled from the cab
+- ``ORTS_BATTERY_SWITCH_COMMAND_SWITCH`` can be used if the battery switch is directly controlled from the cab
 - ``ORTS_BATTERY_SWITCH_COMMAND_BUTTON_CLOSE`` and ``ORTS_BATTERY_SWITCH_COMMAND_BUTTON_OPEN`` can be used if the switch is controlled with two pushbuttons (one to close the switch and the other to open it)
 - ``ORTS_BATTERY_SWITCH_ON`` can be used to control a light on the cab showing the state of the battery switch
+- ``ORTS_BATTERY_VOLTAGE`` monitors the battery voltage
 
 Other controls can be disabled if the low voltage power supply is not available using the following parameter::
 
@@ -166,6 +168,44 @@ 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-electricselectors:
+
+.. index::
+   single: ORTS_PANTOGRAPH_SELECTOR
+   single: ORTS_POWER_LIMITATION_SELECTOR
+   single: ORTS_VOLTAGE_SELECTOR
+
+There :ref:`pantograph selector <physics-pantograph-selector>`, 
+:ref:`voltage selector <physics-voltage-selector>` and 
+:ref:`power limitation selector <physics-power-limitation-selector>` can be used
+to switch the traction system for locomotives operating at different voltages.
+
+They can be included in the cabview as follows:
+
+- ``ORTS_PANTOGRAPH_SELECTOR`` allows selecting pre-defined pantograph arrangements
+  (requires a custom script).
+- ``ORTS_VOLTAGE_SELECTOR`` configures the power supply for the voltage of the line
+  (requires a custom script to raise the right pantograph).
+- ``ORTS_POWER_LIMITATION_SELECTOR`` limits the maximum power that the locomotive can draw.
+
 .. _cabs-dieselenginesonoff:
 
 Controls to switch on and off diesel engines

Source/Documentation/Manual/features-rollingstock.rst

@@ -149,11 +149,11 @@ block!
 .. index::
    single: Conditions(ORTSBattery
 
-Battery Switch
-''''''''''''''
+Battery
+'''''''
 
 The light condition ``ORTSBattery`` allows a light to respond to the state of
-the :ref:`battery switch subsystem <physics-battery-switch>`. The valid settings
+the :ref:`battery subsystem <physics-battery>`. The valid settings
 and associated conditions for the light to turn *on* are as follows:
 
 - ``ORTSBattery ( 0 )`` Battery state is ignored (default)
@@ -2012,6 +2012,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
 
@@ -2043,6 +2046,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" ) )``
@@ -2225,14 +2237,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
 --------------------------------
 
@@ -2252,6 +2316,7 @@ Use the following .eng parameter to load a power supply script::
 
   Engine (
       ORTSPowerSupply ( "YourEPS.cs" )
+      ORTSPowerSupplyParameters ( "YourEPS.ini" )
       ORTSPowerOnDelay ( 5s )
       ORTSAuxPowerOnDelay ( 10s )
   )
@@ -2260,6 +2325,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.
 
@@ -2641,6 +2712,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:

Source/Documentation/Manual/images/multiplayerserver.png

@@ -312,6 +312,27 @@ Additional info on using the Public Server
   time frame, it will re-enter the game in the position where he was at the 
   moment of the crash.
 
+.. _standalone-multiplayer-server:
+
+Standalone multiplayer server
+=============================
+
+If preferred, a standalone multiplayer server may be run on a local computer. It must be 
+started before the players enter the game.
+To start it, click on the *Tools* button in the main menu window, and then select 
+*MultiPlayer Server*. A window as shown below will appear.
+
+.. image:: images/multiplayerserver.png
+  :align: center
+  :scale: 160%
+
+First only the three first lines will be shown. As soon as the first player enters the game 
+(he must select the URL and the port of the standalone multiplayer server; furthermore he must select 
+the *Client* button, enter a User Name and click on *Start MP*) , he becomes appointed as the dispatcher, 
+and the standalone multiplayer server starts displaying all messages sent and received.
+At this point all other players can enter the game.
+
+
 Save and resume
 ===============