Merge branch 'master' into new-advanced-coupler

.appveyor.yml

@@ -3,8 +3,12 @@ skip_branch_with_pr: true
 image: Visual Studio 2017
 install:
 - ps: >-
+    $ErrorActionPreference = "Stop"
+
     choco install --yes --no-progress lazarus 7zip.portable xna31
 
+    if ($LASTEXITCODE -ne 0) { throw "Chocolatey failed to install all required packages - use the 're-build' option to try again" }
+
     (New-Object Net.WebClient).DownloadFile('https://github.com/electron/rcedit/releases/download/v1.1.1/rcedit-x86.exe', 'rcedit-x86.exe')
 
     $env:PATH="$env:PATH;C:\lazarus;$((Get-ChildItem -Recurse C:\lazarus\fpc\strip.exe).DirectoryName);C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\bin"

README.md

@@ -1,5 +1,16 @@
 # Open Rails
 
+## Builds and downloads
+
+Type | Version  | Status | Downloads
+-- | -- | -- | --
+Official website and in-app updates | Stable   | - | [Downloads](http://www.openrails.org/download/program/?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
+Official website and in-app updates | Testing  | [![Build status](https://james-ross.co.uk/projects/or/testing/ci_status.svg)](https://james-ross.co.uk/projects/or/testing/ci_log.txt) | [Downloads](http://www.openrails.org/download/program/?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
+Official website and in-app updates | Unstable | [![Build status](https://james-ross.co.uk/projects/or/ci_status.svg)](https://james-ross.co.uk/projects/or/ci_log.txt) | [Downloads](https://james-ross.co.uk/projects/or/builds?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
+Code verification | Stable   | - | -
+Code verification | Testing  | [![Build status](https://ci.appveyor.com/api/projects/status/37hhwwna5809xyhl/branch/master?svg=true)](https://ci.appveyor.com/project/openrails/openrails/branch/master) | [Downloads](https://ci.appveyor.com/project/openrails/openrails/branch/master/artifacts)
+Code verification | Unstable | [![Build status](https://ci.appveyor.com/api/projects/status/37hhwwna5809xyhl/branch/unstable?svg=true)](https://ci.appveyor.com/project/openrails/openrails/branch/unstable) | [Downloads](https://ci.appveyor.com/project/openrails/openrails/branch/unstable/artifacts)
+
 ## Open Rails and Microsoft Train Simulator
 
 Our project provides a train simulator for the largest collection of digital content in the world - routes, rolling stock and activities - initially developed for Microsoft's Train Simulator product.

Source/Documentation/Manual/cabs.rst

@@ -171,6 +171,37 @@ Here is an example of a cab light control block within the .cvf file::
             )
 
 
+Signed Traction Braking control
+-------------------------------
+
+This cabview control shows the signed value of the force (+ve or -ve, that is 
+tractive or due to dynamic braking) as displayed 
+in many real loco cabs. The control is ORTS_SIGNED_TRACTION_BRAKING. 
+For comparison, the MSTS-compatible TRACTION_BRAKING cabview control shows the 
+absolute value of the force. 
+Here is an example of a cab light control block within the .cvf file::
+
+
+            Dial (
+                Type ( ORTS_SIGNED_TRACTION_BRAKING DIAL )
+                Position ( 319 223 3 32 )
+                Graphic ( ../../Common.Cab/CabE464/AgoDin.ace )
+                Style ( NEEDLE )
+                ScaleRange ( -761 1600 )
+                ScalePos ( 190 70 )
+                Units ( AMPS )
+                Pivot ( 36 )
+                DirIncrease ( 0 )
+                )
+
+Signed Traction Total Braking control
+-------------------------------------
+
+ORTS_SIGNED_TRACTION_TOTAL_BRAKING control behaves and is defined like 
+ORTS_SIGNED_TRACTION_BRAKING, with the only difference that the braking 
+force does include also the train brake force in addition to the dynamic 
+brake force.
+
 Further OR cab controls
 -----------------------
 
@@ -306,6 +337,25 @@ Note that you cannot use the MS Cabview editor on the .cvf file after having
 inserted these optional lines, because the editor will delete these added 
 lines when the file is saved.
 
+Rotation of Digital controls
+----------------------------
+
+One of the drawbacks of rendering a cabview in 2D is that some parts of it 
+are not shown with a frontal, horizontal, view. Displaying a horizontal digital 
+control on it generates an unrealistc effect. This is the rationale of following 
+entry, to be added within a Digital cabview control block in the .cvf file::
+
+  ORTSAngle ( 5 )
+
+The number in parenthesis is the angle in degrees with respect to the horizontal 
+(positive for counterclockwise rotation).
+
+Here an example of a red max speed indication that has been rotated by 5 degrees
+
+.. image:: images/cabs-digitals-rotation.png
+
+Rotation may be applied, with the same syntax, also to DigitalClock cab controls.
+
 3D cabs
 =======
 

Source/Documentation/Manual/driving.rst

@@ -196,7 +196,7 @@ The following information is displayed in the basic display:
   appears displaying the actual gear. ``N`` means no gear inserted.
 - FPS = Number of Frames rendered per second
 
-If the :ref:`Autopilot <options-autopilot>` is active, an additional line 
+When applicable, an additional line indicationg whether Autopilot is active or not 
 will be shown.
 
 An example of the basic HUD for Diesel locomotives:
@@ -702,8 +702,8 @@ route.
 .. image:: images/driving-dispatcher.png
 
 The dispatcher window shows the route layout and monitors the movement of 
-all trains. While the player train is identified by the ``PLAYER`` string 
-(or by a ``0`` if autopilot mode is enabled), AI trains are identified by 
+all trains. While the player train is identified by the ``0`` string, 
+AI trains are identified by 
 their OR number (that is also shown in the :ref:`Extended HUD for Dispatcher 
 Information <driving-hud-dispatcher>`), followed by the service name. 
 Static consists are identified as in MSTS.
@@ -800,8 +800,7 @@ original route, its path information in the dispatcher info HUD is displayed in
 Station platform stops are re-assigned to adjacent platforms, if available. Events and 
 waiting points in the abandoned part of route will be lost.
 
-The re-routed train may be also the player train (be it autopiloted or not), provided the
-Autopilot option is checked.
+The re-routed train may be also the player train (be it autopiloted or not).
 
 Additional Train Operation Commands
 ===================================
@@ -969,14 +968,21 @@ to better understand what is possible with turntables and transfertables.
 Autopilot Mode
 ==============
 
+When in activity mode or in Explore in activity mode, through this feature 
+it is possible to stay
+in the cab of the player train, but to let Open Rails move the train,
+respecting path, signals, speeds and station stops.
+
+It is possible to switch the player train between autopilot mode and
+player driven mode at run time.
+
 Autopilot mode is not a simulation of a train running with cruise control; 
 instead, it is primarily a way to test activities more easily and quickly; 
 but it can also be used to run an activity (or part of it, as it is 
 possible to turn autopilot mode on or off at runtime) as a trainspotter or 
 a visitor within the cab.
 
-Autopilot mode is enabled with the related checkbox in the Simulation 
-Options. It is active only in activity mode (i.e. not in explorer or 
+Autopilot mode is active only in activity mode (i.e. not in explorer or 
 timetable modes).
 
 When starting the game with any activity, you are in player driving mode. 
@@ -1024,9 +1030,7 @@ General
 -------
 
 This function only works in activity mode, and allows the player to select 
-another (existing) train from a list and to start driving it. It requires 
-that the Experimental Options ``Autopilot`` and ``Extended AI Shunting`` be 
-checked. 
+another (existing) train from a list and to start driving it.
 
 This function can be called more than once. A new information window has 
 been created to support this function: the ``Train List`` window (opened 
@@ -1206,22 +1210,32 @@ depressed.
 
 The commands for each of the views are described below.
 
-- Key 1 opens the 2D driver's view from the interior of the controlling cab 
-  of the player locomotive. The entire cab view can be moved to other cabs 
-  (if available) in the player train by successive presses of Ctrl+E; the 
-  train must be stopped and the direction switch in Neutral. The view can be 
-  changed to the fixed left, front, or right view by clicking the left, up or 
-  right arrow keys. (The 2D view is constructed from three 2D images, so the 
-  actual camera position can only be modified by editing the contents of the 
-  .cvf file.) The headout views (if available) are selected by ``Home`` 
-  (right hand side, looking forward) or ``End`` (left hand side, looking 
-  back) and the headout view direction is controlled by the mouse with the 
-  right button depressed. If there are multiple locomotives, ``<Alt+PgUp>``
-  and ``<Alt+PgDn>`` move the headout views.
+- Key ``<1>`` opens the 2D driver's view from the interior of the controlling 
+  cab of the player locomotive. The 2D view can be cycled between the fixed 
+  left, front, and right views with the ``<Left>`` and ``<Right>`` arrow keys. 
+  The cab itself can be hidden with the ``<Shift+1>`` key. (The 2D view is 
+  constructed from three 2D images, so the actual camera position can only be 
+  modified by editing the contents of the .cvf file.) If there is a mismatch 
+  between the aspect ratio of the (optionally stretched) cab and the aspect 
+  ratio of the monitor, OR will clip the cab and show only the portion that fits 
+  within the display, as described in 
+  :ref:`2D cab stretching <options-cab-stretch>`. This clip can be panned around 
+  to reveal the rest of the cab with the ``<Up>``, ``<Down>``, ``<Alt+Left>``, 
+  and ``<Alt+Right>`` keys. Alternatively, if placed into letterboxing mode, 
+  which activates with the ``<Ctrl+1>`` key, OR will render the full cab 
+  without a clip and cover the remaining space with black bars.
 - Key ``<Alt+1>`` opens the 3D driver's view (if the locomotive has a 3D 
   cabview file) from the interior of the controlling cab of the player 
   locomotive. The camera position and view direction are fully player 
   controllable.
+- The entire cab view can be moved to other cabs (if available) in the player 
+  train by successive presses of ``<Ctrl+E>``; the train must be stopped and the 
+  direction switch in Neutral.
+- The headout views (if available) are selected by ``<Home>`` (right hand side, 
+  looking forward) or ``<End>`` (left hand side, looking back) and the headout 
+  view direction is controlled by the mouse with the right button depressed. If 
+  there are multiple locomotives, ``<Alt+PgUp>`` and ``<Alt+PgDn>`` move the 
+  headout views.
 
 Rotation of the camera view in any direction is controlled by the mouse 
 with the right-hand button depressed (or alternatively by the four arrow