Merge remote-tracking branch 'upstream/master' into pr/890

Author: Looky1173

Build.cmd

@@ -163,7 +163,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
-7za.exe a -r -tzip -x^^!.* -x^^!obj -x^^!lib -x^^!_build -x^^!*.bak -x^^!Website "OpenRails-%Mode%-Source.zip" "Source" || GOTO :error
+7za.exe a -r -tzip -x^^!.* -x^^!obj -x^^!lib -x^^!_build -x^^!*.bak "OpenRails-%Mode%-Source.zip" "Source" || GOTO :error
 
 ENDLOCAL
 GOTO :EOF

Docs/Contributing.md

@@ -20,14 +20,22 @@ You are free to make any modifications to the Open Rails code that you like; tha
 
 In most cases, you can get started immediately with making the changes and creating a pull request. We do ask for some additional steps to be taken for some bugs and all new features, but they can come before or after the pull request. Please feel free to share ideas and proposals as pull requests!
 
-**Note:** You must start your work from the "master" branch and merged pull requests back into the "master" branch, unless we direct you otherwise.
+**Note:** You must fork the Open Rails repository before you start working on it. We do not allow you to push branches to the official repository.
+
+**Note:** You should do your work on separate branches; they must be created from the "master" branch and pull requests must merge back into the "master" branch, unless we direct you otherwise.
 
 ### Documentation and translations
 
 If you'd like to improve the [documentation](./), [manual](../Source/Documentation/Manual), or [translations](../Source/Locales) you can get started immediately.
 
 There are no requirements for the pull request.
 
+### Contributed projects
+
+If you'd like to improve the [contributed projects](../Source/Contrib) you can get started immediately.
+
+There are no requirements for the pull request.
+
 ### Bug process
 
 If you'd like to fix a bug, you can get started immediately. If the fix turns out to be very small, you do not even need a bug report. Otherwise, you will need to make sure it has been reported on [our bug tracker on Launchpad](https://bugs.launchpad.net/or). If it has not, you can report the bug *and* fix it!
@@ -154,7 +162,7 @@ When we start preparing for a new Stable Version, all code in the Testing Versio
 
 ### Submitting your code
 
-When you're done writing code, you should make a pull request on GitHub. The title and description of the requests should concisely indicate what bug or feature you've implemented and you will need to include links to whichever of the following are appropriate:
+When you're done writing code, you should make a pull request on GitHub from your fork's branch back to the official repository's "master" branch. The title and description of the requests should concisely indicate what bug or feature you've implemented and you will need to include links to whichever of the following are appropriate:
 
 * Bug report
 * Road-map card

Docs/Readme.md

@@ -10,7 +10,7 @@ Open Rails is a free train simulator supporting the world's largest range of dig
 ## Documentation
 
 * [Read the FAQ](http://www.openrails.org/learn/faq/?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
-* [Read the manual online](https://open-rails.readthedocs.io/en/1.3.1/) or the PDF included with the program, found in the main menu under "Documents"
+* [Read the manual online](https://open-rails.readthedocs.io/en/latest/) or the PDF included with the program, found in the main menu under "Documents"
 * [Get additional materials, including tutorials, from our website](http://www.openrails.org/learn/manual-and-tutorials/?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
 * [Read more about the project on our website](http://www.openrails.org/discover/open-rails/?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
 

Source/Documentation/Manual/appendices.rst

@@ -58,6 +58,11 @@ Voltage                 volt                        V
 Mass Flow                                           g/h
 \                                                   kg/h
 \                       lb/h                        lb/h        lb/h
+Volumetric Flow         m^3/s           air flow    m^3/s
+                                        meters
+\                                                   ft^3/min
+\                                                   L/min
+\                                                   L/s
 Speed                   m/s             other       m/s         m/s             meter per second
 \                                                   km/h
 \                                                   kph         kph             kilometer per hour
@@ -123,7 +128,8 @@ The following folders are also written to by Open Rails.
    Save images          AppData\\Roaming\\Open Rails\\shunt_1 2021-07-18 19.46.35.png
    Replays              AppData\\Roaming\\Open Rails\\shunt_1 2021-07-18 19.46.35.replay
    Evaluations          AppData\\Roaming\\Open Rails\\shunt_1 2021-07-18 19.46.35.dbfeval
-   Loading progress bar AppData\\Roaming\\Open Rails\\Load Cache\\3cd9... ...0ce2.dat
+   Loading progress bar AppData\\Roaming\\Open Rails\\Cache\\Load\\3cd9... ...0ce2.cache-or
+   Timetable path files AppData\\Roaming\\Open Rails\\Cache\\Path\\4ae2... ...4132.cache-or
    ==================== ========================================================================================
 
 

Source/Documentation/Manual/cabs.rst

@@ -679,6 +679,37 @@ An example of implementation of the above controls in a .cvf file follows::
 		)
 
 
+Air Flow Meter
+--------------
+
+.. index::
+   single:  ORTS_AIR_FLOW_METER
+
+This cabview control is used on some locomotives, particularly in North America, to show the
+volumetric flow rate of air moving from the main res to the brake pipe during release/recharge.
+Such an indication can be used to determine when brake pipe charging is complete,
+measure the amount of brake pipe leakage, and so on.
+The control will only function on locomotives with air brakes.
+
+Here is an example implementation of ORTS_AIR_FLOW_METER as an analog dial::
+
+
+		Dial (
+			Type ( ORTS_AIR_FLOW_METER DIAL )
+			Position ( 258 271 1 32 )
+			Graphic ( "white_needle.ace" )
+			Style ( NEEDLE )
+			ScaleRange ( 0 150 )
+			ScalePos ( 295 65 )
+			Units ( CUBIC_FT_MIN )
+			Pivot ( 24 )
+			DirIncrease ( 0 )
+		)
+
+Applicable user-defined units are CUBIC_FT_MIN, LITERS_S, LITERS_MIN, and CUBIC_M_S. Cubic meters per
+second will be used if no units are specified.
+
+
 Animated 2D Wipers
 ------------------
 
@@ -819,6 +850,8 @@ and the mirrors.
 The control blocks are like the one shown for the cab light. The Type strings 
 are ORTS_LEFTDOOR, ORTS_RIGHTDOOR and ORTS_MIRRORS.
 
+Animation for 2D cab windows is described :ref:`here <features-windows>` .
+
 .. _cabs-generic-items:
 
 Cab controls for generic items
@@ -1025,6 +1058,7 @@ Rotation may be applied, with the same syntax, also to DigitalClock cab controls
 
 Display and animation of cabview controls in side views of 2D cabs
 ------------------------------------------------------------------
+.. _cabs-side-views:
 
 This is possible adding after the CabViewControls ( ) compound block an 
 ORTSCabviewControls ( ) compound block, that has the same format as the 
@@ -1154,6 +1188,40 @@ Development Rules
         StartDirection ( 12 0 0 )
     )
 
+- If also a rear cab is present, a second ``ORTS3DCab`` has to be added, 
+  as follows::
+
+     ORTS3DCab(
+        ORTS3DCabFile ( Cab.s )
+        ORTS3DCabHeadPos ( 0.9 2.4 5.2 )
+        RotationLimit ( 40 60 0 )
+        StartDirection ( 12 180 0 )
+    )
+
+- Alternate 3D cab viewpoints may be added, as in the example here below::
+
+      ORTSAlternate3DCabViewPoints
+                         (
+        ORTSAlternate3DCabViewPoint(
+           ORTS3DCabFile ( Cab.s )
+           ORTS3DCabHeadPos ( 0.9 2.4 5.2 )
+           RotationLimit ( 40 60 0 )
+           StartDirection ( 12 0 0 )
+                        )
+        ORTSAlternate3DCabViewPoint(
+          ORTS3DCabFile ( Cab.s )
+          ORTS3DCabHeadPos ( -0.8 2.4 5.2 )
+          RotationLimit ( 40 60 0 )
+          StartDirection ( 12 30 0 )
+                        )
+                        )
+
+
+-  To switch between alternate cab viewpoints ``Ctrl-Shift-1`` must be pressed.
+   If there aren't alternate viewpoints defined, and if there is no rear cab, 
+   pressing ``Ctrl-Shift-1`` toggles between the base viewpoint and a symmetrical 
+   one on the longitudinal axis.
+
 .. index::
    single: EXTERNALWIPERS
    single: AMMETER
@@ -1177,6 +1245,7 @@ Development Rules
   font. If no ace is specified, the default will be used.
 - Mirrors and doors can be operated from 3D cabs. The names used are 
   ``LEFTDOOR``, ``RIGHTDOOR`` and ``MIRRORS``.
+- Animation for 3D cab windows is described :ref:`here <features-windows>` .  
 - like the 2D cabs, also 3D cabs can have a night version. Night textures, named like the 
   corresponding day textures, must be located within a ``NIGHT`` subfolder of the 
   ``CABVIEW3D`` folder. To enable night cabs an ``.sd`` file with the same name as the 

Source/Documentation/Manual/driving.rst

@@ -537,13 +537,16 @@ By clicking in this menu it is possible:
   for both electric and diesel locomotives;
 - to connect or disconnect locomotive operation with that of the player 
   locomotive;
-- to connect or disconnect the car's air hoses from the rest of the consist;
-- to toggle the angle cocks on the air hoses at either end of the car 
-  between open and closed;
-- to toggle the bleed valve on the car to vent the air pressure from the 
+- enable or disable the battery switch;
+- to connect or disconnect the Electric Train Supply;
+- to connect or disconnect the car's brake hoses from the rest of the consist;
+- to open or close the angle cocks on the air hoses at either end of the car;
+- to open or close the bleed valve on the car to vent the air pressure from the 
   car's reservoir and release the air brakes to move the car without brakes 
   (e.g. humping, etc.).
 
+Grayed out choices are not applicable for the chosen car.
+
 By toggling the angle cocks on individual cars it is possible to close 
 selected angle cocks of the air hoses so that when the cars are uncoupled, 
 the air pressure in the remaining consist (and optionally in the uncoupled 
@@ -764,7 +767,9 @@ The following information is displayed in the basic display:
   Train brake HUD line has two Brake Reservoir pressure numbers: the first is 
   the Equalization Reservoir (EQ) and the second is the Brake Cylinder (BC) 
   pressure. The two BP numbers report the brake pressure in the lead engine 
-  and in the last car of the train. The unit of measure used for brake 
+  and in the last car of the train. Additionally, the brake flow is shown,
+  which measures the rate of air flowing into the brake pipe during release
+  and recharge. The unit of measure used for brake 
   pressure is defined by the option :ref:`Pressure unit <options-pressure>`.
 - Engine Brake = percentage of independent engine brake. Not fully 
   releasing the engine brake will affect train brake pressures.
@@ -1088,10 +1093,24 @@ More information on connecting brakes and manipulating the brake hose
 connections can be found :ref:`here <physics-hud-brake>` and 
 :ref:`here <driving-car-operations>`.
 
-Doors and Mirror Commands
--------------------------
-
-Note that the standard keys in OR for these commands are different from 
+Doors, Mirror and Windows Commands
+----------------------------------
+.. _driving-anim-commands:
+
+Note that these commands are active only if the trainset is equipped with 
+the related animations.
+
+===================     =====================================
+Command                 Function
+===================     =====================================
+``<Q>``                 Door left open/close   
+``<Shift+Q>``           Door right open/close
+``<Shift+V>``           Mirror rotate clock/counterclockwise
+``<Ctrl+Q>``            Window left open/close
+``<Ctrl+Shift+Q>``      Window right open/close
+===================     =====================================
+
+Note that the standard keys for doors and mirror in OR are different from 
 those of MSTS.
 
 Wheelslip Reset