Merge branch 'openrails:master' into master

Author: Weter-ORTS

Source/Documentation/Manual/cabs.rst

@@ -466,6 +466,60 @@ if e.g. the wiper moves from left to right and back, only the frames related
 to the motion from left to right have to be included. For the reverse 
 motion the same frames are used from last to first. SwitchVal can vary from 0 to 1.
 
+Multiple screen pages on displays
+---------------------------------
+
+Modern locomotives have one or more displays in their cabs, and often in such 
+displays it is possible to switch among more screen pages. Fields and controls 
+described in this paragraph enable the implementation of .cvf files with such 
+functionality, for both 2D and 3D cabs.
+
+In the .cvf control blocks following further fields may be optionally present::
+
+  ORTSDisplay ( numeric ), indicating the display ID number (from 0 to 7) 
+  to which the control is linked; if such field is missing, display ID number 
+  zero is assumed;
+
+  ORTSScreenPage ( alphanumeric-string ) indicating the screen ID string to 
+  which the control is linked; that means that the control is displayed/may be 
+  operated only if its screen is active in that moment; a missing entry 
+  indicates that the control is displayed independently from the selected screen page; 
+  at game start such controls are enabled, plus the ones with line 
+  ORTSScreenPage ( "default" ); more ORTSScreenPage() entries in a single control 
+  are possible.
+
+A new on/off control, called ORTS_SCREEN_SELECT is available, which, in addition to the usual fields and to 
+the optional fields ORTSDisplay and ORTSScreenPage contains one or more of following fields::
+
+  ORTSNewScreenPage ( alphanumeric-string numeric ): when the control is clicked, 
+  the controls with field ORTSScreenPage equal to the string of this field and 
+  with field ORTSDisplay equal to the numeric will be displayed on such display 
+  in place of the ones displayed up to that moment. if the numeric is missing within 
+  ORTSNewScreenPage, the involved display is the one referenced in field ORTSDisplay 
+  of ORTS_SCREEN_SELECT.
+
+A further control is available, named ORTS_STATIC_DISPLAY, which is specially devoted to the loading of the 
+background of screen pages (their static part). 
+Here is an example of usage of it::
+
+	MultiStateDisplay (
+		Type ( ORTS_STATIC_DISPLAY MULTI_STATE_DISPLAY )
+		Position ( 246 151 105 16 )
+		Graphic ( semproniostatic.ace )
+		States ( 1 1 1
+			State (
+				Style ( 0 )
+				SwitchVal ( 0 )
+			)
+		)
+			ORTSScreenPage ( "sempronio" )
+		)
+
+With this block, the static part of the "sempronio" screen page is loaded on display 0 when such screen 
+becomes the active one.
+
+.cvf files not using fields and controls listed in this paragraph work as usual, with no changes needed. 
+
 Further OR cab controls
 -----------------------
 
@@ -480,6 +534,44 @@ 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.
 
+.. _cabs-generic-items:
+
+Cab controls for generic items
+------------------------------
+
+OR supports the cabview controls for two generic two-state items. 
+The cabview controls aree called ``<ORTS_GENERIC_ITEM1>`` and 
+``<ORTS_GENERIC_ITEM2>``. Their state can be toggled also by respectively 
+clicking keys ``<Shift+.>`` and ``<Shift+,>``.
+
+Sound events are associated, that is::
+
+   240: GenericItem1On
+   241: GenericItem1Off
+   242: GenericItem2On
+   243: GenericItem2Off
+
+Animations within the .s file of the locomotive, either stopped/moving or 
+two-state can be associated to the item state. Linked stopped/moving (wiper type) 
+animations are named ``<ORTSITEM1CONTINUOUS>`` and ``<ORTSITEM2CONTINUOUS>``. 
+Linked two-state animations (doors type) are named ``<ORTSITEM1TWOSTATE>`` and
+``<ORTSITEM2TWOSTATE>``. 
+The default animation speed for stopped/moving type animations is 8 FPS. 
+It may be modified with following parameter in the .sd file::
+
+   ESD_CustomAnimationSpeed ( 8 )
+
+Examples of use are fan control, open/close of aerodynamic coverages of couplers 
+in high speed trains, menu pages switching.
+
+Animations within the 3D cab .s file are also available, as follows::
+
+        ORTS_ITEM1CONTINUOUS
+        ORTS_ITEM2CONTINUOUS
+        ORTS_ITEM1TWOSTATE
+        ORTS_ITEM2TWOSTATE
+
+in analogy to the four animations for the locomotive .s file.
 
 High-resolution Cab Backgrounds and Controls
 --------------------------------------------
@@ -808,3 +900,13 @@ Here below is an example of an entry for a 3D cab::
   ScaleRange ( 0 5000 )
   Units ( LBS )
   ) 
+
+Alignment for digital controls
+------------------------------
+
+For backwards compatibility reasons, ``Justification ( 1 )``, ``Justification ( 2 )`` and 
+``Justification ( 3 )`` all lead to a left alignment of the digital in 3Dcabs.
+
+``Justification ( 5 )`` must be used for center alignment, and ``Justification ( 6 )`` 
+must be used for right alignment. ``Justification ( 4 )`` leads to left alignment. 
+

Source/Documentation/Manual/driving.rst

@@ -1606,8 +1606,8 @@ key assignment list shown by pressing ``<F1>``.
 In addition, Open Rails offers functionality similar to the time 
 acceleration switch for MSTS. 
 
-Use ``<Alt+PgUp>`` or ``<Alt+PgDn>`` keys to increase or decrease the 
-speed of the game clock.
+Use ``<Ctrl+Alt+PgUp(Numkey)>`` or ``<Ctrl+Alt+PgDn(Numkey)>`` keys to increase or decrease the 
+speed of the game clock. ``<Ctrl+Alt+Home(Numkey)>`` resets the speed.
 
 In a multiplayer session, all clients' time, weather and season selections 
 are overridden by those set by the server.

Source/Documentation/Manual/images/cover_image.png

@@ -720,7 +720,14 @@ instead::
 			Type ( ORTS_ETCS SCREEN_DISPLAY )
 			Position ( 280 272 320 240 )
 			Units ( KM_PER_HOUR )
+			Parameters (
+				Mode FullSize
+			)
 		)
+		
+The following DMI size variants are available: FullSize (displays the whole DMI), SpeedArea
+(displays only the left part with information about distance and speed) and PlanningArea
+(displays only the planning area and navigation buttons).
 
 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>`.

Source/Documentation/Manual/images/physics-dpu-window.png

@@ -2031,18 +2031,106 @@ Some of the cab monitoring gauges provide visibility of what is happening on the
 the "closest" powered car near the Control car and uses its information.
 
 
-Engines -- Multiple Units in Same Consist or AI Engines
-=======================================================
-
-In an OR player train one locomotive is controlled by the player, while
-the other units are controlled by default by the train's MU (multiple
-unit) signals for braking and throttle position, etc. The
-player-controlled locomotive generates the MU signals which are passed
-along to every unit in the train. For AI trains, the AI software directly
-generates the MU signals, i.e. there is no player-controlled locomotive.
+Multiple Units of Locomotives in Same Consist
+=============================================
+
+In an OR player train one locomotive is controlled by the player, while 
+the other units are controlled by default by the train's MU (multiple 
+unit) signals for braking and throttle position, etc. The 
+player-controlled locomotive generates the MU signals which are passed 
+along to every unit in the train. 
+
+Distributed Power
+-----------------
+
+This is applicable only to trains hauled by diesel locomotives equipped with 
+dynamic brakes.
+
+More locomotive groups may be present in American long freight trains; a 
+locomotive group is defined as a set of locomotives that have no wagons in 
+between. 
+Groups different from the group including the lead locomotive are called 
+remote groups.
+
+Remote groups can be controlled in two modes: *synchronous* or 
+*asynchronous*. Locomotives in the player train can be arranged to be part of 
+one of the two above control groups. So each locomotive group (except the lead one,
+which always belongs to the *sync* control group) 
+can be either part the *sync*  or of the *async* control group. However, if a 
+locomotive group is part of the *async* control group, all locomotive groups behind 
+it must also be part of the *async* control group.
+
+The arrangement can be changed during run, 
+which in real life is performed by using the locomotive's onboard computer 
+(e.g. Locotrol).
+
+This functionality is necessary in American long-train freight 
+operations. An example use case is when a train finished climbing a 
+mountain pass. At this point the lead locomotives have to start dynamic 
+braking driving downhill, while the trailing units still need to keep pushing 
+the train's end uphill. The locomotive driver has the possibility to build 
+the *fence*, i.e. move the last locomotive group to the *async* control group. 
+
+While locomotives in *sync* control group always copy the traction and dynamic 
+brake settings of the lead (man-controlled) locomotive, for locomotives in 
+*async* control group these can be adjusted independently. Other controls, like 
+reverser and air brake are always synchronized throughout the whole train, 
+and changing reverser setting or applying air brakes will force *async* 
+controlled locomotives to fall back to idle. 
+
+The *fence* between *sync* and *async* control groups can be moved back and forth 
+along the train. This is useful when there are one or more middle-train 
+locomotive groups in the consist. However it is not possible to move the 
+fence to separate two directly interconnected locomotives: such locomotives 
+can be rearranged only together.  
+
+If the driver dismantles the *fence*, by moving it after the last locomotive 
+group, all locomotive groups are moved back to *sync* control group, and 
+therefore all locomotives will work in sync with the leading one.
+All-sync operation is also the default, when the game starts. 
+
+Traction and dynamic brake settings for *sync* group can be controlled by the 
+usual keys: ``<A>`` and ``<D>``. The following additional controls are 
+available for controlling the *async* group settings:
+
+- Move To Back -- ``<Ctrl+Shift+O>``: Move one locomotive group to back (*async*) 
+  control group (*fence* is moved towards the front of the train).
+- Move To Front -- ``<Ctrl+O>``: Move one locomotive group to front (*sync*) 
+  control group (*fence* is moved towards the back of the train).
+- Traction -- ``<Ctrl+L>``: Switch *async* group to traction mode.
+- Idle -- ``<Ctrl+Shift+L>``: Switch *async* group to idle state.
+- Brake -- ``<Ctrl+'> (key two positions at the right of L)``: Switch *async* 
+  group to dynamic braking mode.
+- More -- ``<Ctrl+U>``: Increase *async* group traction or dynamic brake by a notch, 
+  depending on its mode setting.
+- Less -- ``<Ctrl+Shift+U>``: Decrease *async* group traction or dynamic brake by a notch, 
+  depending on its mode setting.
+
+HUD shows the sync--async configuration in line *Multiple Units* on main page.
+When it reads e.g. "2--2 | 1", then it means that front and middle-train 
+double-unit locomotives are controlled in *sync* with the leading unit, 
+while the trailing pushing unit is controlled *async* independently. 
+The actual set value of traction or dynamic brake of *async* group is shown in 
+lines *Throttle* and *Dynamic Brake*, respectively, in brackets, e.g.: 
+Throttle: 0% (50%).
+
+The complete distributed power configuration is displayed in the 
+Distributed Power Info extended HUD page, where the state of all locomotives 
+in the train are shown, as well as in the *Train DPU Info* window, which is 
+displayed after pressing ``<Shift+F9>``, and which shows only the state of the first 
+locomotive of each locomotive group, as occurs also in displays of real 
+locomotives.
+
+.. image:: images/physics-dpu-window.png
+
+Engines of AI Trains
+--------------------
+
+For AI trains, the AI software directly generates the remote control
+signals, i.e. there is no player-controlled locomotive. 
 In this way, all engines use the same physics code for power and friction.
 
-This software model will ensure that non-player controlled engines will
+This software model will ensure that non-player controlled engines will 
 behave exactly the same way as player controlled ones.
 
 .. _physics-braking:

Source/Documentation/Manual/options.rst

@@ -391,6 +391,18 @@ Trigger       Function
 235           AirConditioningOff
 =========     =====================================
 
+Triggers from 240 to 243 associated to the two generic items 
+(see :ref:`here <cabs-generic-items>`) :
+
+=========     =====================================
+Trigger       Function
+=========     =====================================
+240           GenericItem1On
+241           GenericItem1Off
+242           GenericItem2On
+243           GenericItem2Off
+=========     =====================================
+
 Variable Triggers
 -----------------
 

Source/Documentation/Manual/physics.rst

@@ -303,11 +303,9 @@ Special Rows
   will read that path. If not, it will read the 'normal' path, and will then 
   store this as binary for future use. Binary paths are stored in a subdirectory 
   named ``OpenRails`` which must be created in the Paths directory of the route.
-  
-  **Important:**
 
-    - If a path is edited, the binary version must be deleted manually, otherwise the program will still use this older version.
-    - If a route is edited, such that the .tdb might have been changed, all binary paths must be deleted.
+  Note: If a path or the route is edited, then the binary data will be out of date.
+  If so, it is deleted and re-created automatically when the user starts the route.
 
 - ``#consist`` row 
 

Source/Documentation/Manual/sound.rst

@@ -43,6 +43,7 @@ public enum UserCommand
         [GetString("Display Station Labels")] DisplayStationLabels,
         [GetString("Display Switch Window")] DisplaySwitchWindow,
         [GetString("Display Train Operations Window")] DisplayTrainOperationsWindow,
+        [GetString("Display Train Dpu Window")] DisplayTrainDpuWindow,
         [GetString("Display Next Station Window")] DisplayNextStationWindow,
         [GetString("Display Compass Window")] DisplayCompassWindow,
         [GetString("Display Train List Window")] DisplayTrainListWindow,
@@ -204,11 +205,22 @@ public enum UserCommand
         [GetString("Control ImmediateRefill")] ControlImmediateRefill,
         [GetString("Control Turntable Clockwise")] ControlTurntableClockwise,
         [GetString("Control Turntable Counterclockwise")] ControlTurntableCounterclockwise,
-        [GetString("Control Generic 1")] ControlGeneric1,
-        [GetString("Control Generic 2")] ControlGeneric2,
+        [GetString("Control Generic Item 1")] ControlGenericItem1,
+        [GetString("Control Generic Item 2")] ControlGenericItem2,
+        [GetString("Control TCS Generic 1")] ControlTCSGeneric1,
+        [GetString("Control TCS Generic 2")] ControlTCSGeneric2,
         [GetString("Control Cab Radio")] ControlCabRadio,
         [GetString("Control AI Fire On")] ControlAIFireOn,
         [GetString("Control AI Fire Off")] ControlAIFireOff,
         [GetString("Control AI Fire Reset")] ControlAIFireReset,
+
+        //Distributed power
+        [GetString("Control DP Move To Front")] ControlDPMoveToFront,
+        [GetString("Control DP Move To Back")] ControlDPMoveToBack,
+        [GetString("Control DP Traction")] ControlDPTraction,
+        [GetString("Control DP Idle")] ControlDPIdle,
+        [GetString("Control DP Brake")] ControlDPBrake,
+        [GetString("Control DP More")] ControlDPMore,
+        [GetString("Control DP Less")] ControlDPLess,
     }
 }

Source/Documentation/Manual/timetable.rst

@@ -388,8 +388,10 @@ static void InitializeCommands(UserCommandInput[] Commands)
             Commands[(int)UserCommand.ControlForwards] = new UserCommandKeyInput(0x11);
             Commands[(int)UserCommand.ControlGearDown] = new UserCommandKeyInput(0x12, KeyModifiers.Shift);
             Commands[(int)UserCommand.ControlGearUp] = new UserCommandKeyInput(0x12);
-            Commands[(int)UserCommand.ControlGeneric1] = new UserCommandKeyInput(0x33, KeyModifiers.Control);
-            Commands[(int)UserCommand.ControlGeneric2] = new UserCommandKeyInput(0x34, KeyModifiers.Control);
+            Commands[(int)UserCommand.ControlGenericItem1] = new UserCommandKeyInput(0x33, KeyModifiers.Shift);
+            Commands[(int)UserCommand.ControlGenericItem2] = new UserCommandKeyInput(0x34, KeyModifiers.Shift);
+            Commands[(int)UserCommand.ControlTCSGeneric1] = new UserCommandKeyInput(0x33, KeyModifiers.Control);
+            Commands[(int)UserCommand.ControlTCSGeneric2] = new UserCommandKeyInput(0x34, KeyModifiers.Control);
             Commands[(int)UserCommand.ControlHandbrakeFull] = new UserCommandKeyInput(0x28, KeyModifiers.Shift);
             Commands[(int)UserCommand.ControlHandbrakeNone] = new UserCommandKeyInput(0x27, KeyModifiers.Shift);
             Commands[(int)UserCommand.ControlHeadlightDecrease] = new UserCommandKeyInput(0x23, KeyModifiers.Shift);
@@ -436,6 +438,14 @@ static void InitializeCommands(UserCommandInput[] Commands)
 
             Commands[(int)UserCommand.ControlWaterScoop] = new UserCommandKeyInput(0x15);
             Commands[(int)UserCommand.ControlWiper] = new UserCommandKeyInput(0x2F);
+            // Distributed power
+            Commands[(int)UserCommand.ControlDPMoveToFront] = new UserCommandKeyInput(0x18, KeyModifiers.Control); //O
+            Commands[(int)UserCommand.ControlDPMoveToBack] = new UserCommandKeyInput(0x18, KeyModifiers.Control | KeyModifiers.Shift); //O
+            Commands[(int)UserCommand.ControlDPTraction] = new UserCommandKeyInput(0x26, KeyModifiers.Control); //L
+            Commands[(int)UserCommand.ControlDPIdle] = new UserCommandKeyInput(0x26, KeyModifiers.Control | KeyModifiers.Shift); //L
+            Commands[(int)UserCommand.ControlDPBrake] = new UserCommandKeyInput(0x28, KeyModifiers.Control); //
+            Commands[(int)UserCommand.ControlDPMore] = new UserCommandKeyInput(0x16, KeyModifiers.Control); //U
+            Commands[(int)UserCommand.ControlDPLess] = new UserCommandKeyInput(0x16, KeyModifiers.Control | KeyModifiers.Shift); //U
 
             Commands[(int)UserCommand.DebugClockBackwards] = new UserCommandKeyInput(0x0C);
             Commands[(int)UserCommand.DebugClockForwards] = new UserCommandKeyInput(0x0D);
@@ -475,6 +485,7 @@ static void InitializeCommands(UserCommandInput[] Commands)
             Commands[(int)UserCommand.DisplaySwitchWindow] = new UserCommandKeyInput(0x42);
             Commands[(int)UserCommand.DisplayTrackMonitorWindow] = new UserCommandModifiableKeyInput(0x3E, Commands[(int)UserCommand.DisplayNextWindowTab]);
             Commands[(int)UserCommand.DisplayTrainOperationsWindow] = new UserCommandKeyInput(0x43);
+            Commands[(int)UserCommand.DisplayTrainDpuWindow] = new UserCommandKeyInput(0x43, KeyModifiers.Shift);
 
             Commands[(int)UserCommand.GameAutopilotMode] = new UserCommandKeyInput(0x1E, KeyModifiers.Alt);
             Commands[(int)UserCommand.GameChangeCab] = new UserCommandKeyInput(0x12, KeyModifiers.Control);