Skip to content

Commit fde18cf

Browse files
SteelFillSteelFill
committed
First pass for new lights features
1 parent b02a6e5 commit fde18cf

File tree

5 files changed

+708
-157
lines changed

5 files changed

+708
-157
lines changed

‎Source/Documentation/Manual/features-rollingstock.rst

Lines changed: 269 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,272 @@ For a full list of parameters, see :ref:`Developing OR Content - Parameters and
99
Train Engine Lights
1010
===================
1111

12-
OR supports the whole set of lights accepted by MSTS.
12+
OR supports the whole set of lights accepted by MSTS, MSTS-bin, and adds many new
13+
options to enhance the variety and complexity of lighting systems that can be recreated.
14+
15+
Lights with multiple conditions
16+
-------------------------------
17+
18+
In the original MSTS light implementation, each light could only have one set of
19+
activation conditions. If the same light were to be activated in multiple situations,
20+
(for example, a light which should turn on for both the front and rear units)
21+
the entire light would need to be included twice, just with different conditions.
22+
23+
.. index::
24+
single: Conditions
25+
26+
Open Rails now allows for a single light to have multiple ``Conditions ()`` blocks.
27+
If *any* one set of conditions is fulfilled, the light will be enabled. If no conditions
28+
are specified, the light will be assumed to be on always. An example of how this can
29+
be used to simplify ``Lights`` implementation is included below::
30+
31+
Light (
32+
comment( Nose light bright )
33+
Conditions (
34+
Headlight ( 3 )
35+
Unit ( 2 )
36+
)
37+
FadeIn ( 0.5 )
38+
FadeOut ( 0.5 )
39+
States ( 1
40+
State (
41+
LightColour ( FFffffe6 )
42+
Radius ( 0.6 )
43+
Position ( 0.0 4.12 6.55 )
44+
)
45+
)
46+
)
47+
Light (
48+
comment( Nose light bright DPU )
49+
Conditions (
50+
Headlight ( 3 )
51+
Unit ( 4 )
52+
)
53+
FadeIn ( 0.5 )
54+
FadeOut ( 0.5 )
55+
States ( 1
56+
State (
57+
LightColour ( FFffffe6 )
58+
Radius ( 0.6 )
59+
Position ( 0.0 4.12 6.55 )
60+
)
61+
)
62+
)
63+
64+
This set of two lights can be simplified to one light like this::
65+
66+
Light (
67+
comment( Nose light bright )
68+
Conditions (
69+
Headlight ( 3 )
70+
Unit ( 2 )
71+
)
72+
Conditions (
73+
Headlight ( 3 )
74+
Unit ( 4 )
75+
)
76+
FadeIn ( 0.5 )
77+
FadeOut ( 0.5 )
78+
States ( 1
79+
State (
80+
LightColour ( FFffffe6 )
81+
Radius ( 0.6 )
82+
Position ( 0.0 4.12 6.55 )
83+
)
84+
)
85+
)
86+
87+
Both of these snippets produce the same result: a light that turns on when the
88+
headlights are bright and the unit is first, or the last unit reversed (ie:
89+
distributed power). However, by specifying multiple conditions, the second
90+
implementation takes up much less space and guarentees that both modes of the
91+
light have the exact same ``States``. There is no hard limit on the number
92+
of conditions a light can have.
93+
94+
.. _features-light-conditions:
95+
96+
Open Rails specific lighting conditions
97+
---------------------------------------
98+
99+
Open Rails also adds a set of new lighting conditions which offer additional
100+
flexibility in creating detailed light behaviors. Note that each of these
101+
must be inside the ``Conditions ()`` block of a ``Light ()`` in the .eng/.wag
102+
file to function. All conditions are optional and can be mixed and matched
103+
as needed, though only one of each condition can be included per conditions
104+
block!
105+
106+
.. index::
107+
single: Conditions(ORTSBattery
108+
109+
Battery Switch
110+
''''''''''''''
111+
112+
The light condition ``ORTSBattery`` allows a light to respond to the state of
113+
the :ref:`battery switch subsystem <physics-battery-switch>`. The valid settings
114+
and associated conditions for the light to turn *on* are as follows:
115+
116+
- ``ORTSBattery ( 0 )`` Battery state is ignored (default)
117+
- ``ORTSBattery ( 1 )`` Battery switch must be on
118+
- ``ORTSBattery ( 2 )`` Battery switch must be off
119+
120+
.. index::
121+
single: Conditions(Brake
122+
123+
Friction Brakes
124+
'''''''''''''''
125+
126+
The ``Brake`` condition can be used to create brake indicator lights
127+
which turn on or off when the friction brakes are applied. Dynamic brakes
128+
have no effect.
129+
130+
- ``Brake ( 0 )`` Brake application/release is ignored (default)
131+
- ``Brake ( 1 )`` Brakes must be released
132+
- ``Brake ( 2 )`` Brakes must be applied
133+
134+
.. index::
135+
single: Conditions(Reverser
136+
137+
Reverser
138+
''''''''
139+
140+
``Reverser`` is a very powerful condition that gives lights the ability
141+
to be enabled by the selected direction of travel. Note that a flipped
142+
locomotive or wagon will automatically flip the sensed reverser setting
143+
to ensure lights shine in the correct direction. Also, steam locomotive
144+
cutoff values between -10% and 10% will be detected as 'neutral'.
145+
146+
- ``Reverser ( 0 )`` Reverser direction is ignored (default)
147+
- ``Reverser ( 1 )`` Reverser direction must be forward
148+
- ``Reverser ( 2 )`` Reverser direction must be reverse
149+
- ``Reverser ( 3 )`` Reverser direction must be neutral
150+
- ``Reverser ( 4 )`` Reverser direction must be forward or reverse
151+
- ``Reverser ( 5 )`` Reverser direction must be forward or neutral
152+
- ``Reverser ( 6 )`` Reverser direction must be reverse or neutral
153+
154+
.. index::
155+
single: Conditions(Doors
156+
157+
Passenger Doors
158+
'''''''''''''''
159+
160+
Many pieces of passenger rolling stock have indicator lights to inform
161+
the crew :ref:`passenger doors <features-passenger-doors>` are open. The
162+
``Doors`` condition is suited to this type of lighting.
163+
164+
- ``Doors ( 0 )`` Passenger doors are ignored (default)
165+
- ``Doors ( 1 )`` Passenger doors must all be closed
166+
- ``Doors ( 2 )`` Passenger doors on the left must be open
167+
- ``Doors ( 3 )`` Passenger doors on the right must be open
168+
- ``Doors ( 4 )`` Passenger doors on both sides must be open
169+
- ``Doors ( 5 )`` Passenger doors on either the left or right must be open
170+
171+
.. index::
172+
single: Conditions(Horn
173+
single: ORTSHornLightsTimer
174+
175+
Horn (Automatic Flashing Ditch Lights)
176+
''''''''''''''''''''''''''''''''''''''
177+
178+
Open Rails now supports the ability to configure flashing ditch lights
179+
(or any other type of horn activated auxiliary lighting)
180+
with the ``Horn`` light condition. When the horn is sounded, lights
181+
with the horn condition will (de)activate, and remain (de)activated
182+
for a time after the horn stops sounding. The standard timer is 30
183+
seconds, but can be changed by placing a ``ORTSHornLightsTimer``
184+
token in the ``engine()`` section of the locomotive with flashing lights.
185+
If ``ORTSHornLightsTimer( 0s )`` is set, the lights will only activate
186+
while the horn is sounding and immediately stop afterward.
187+
188+
- ``Horn ( 0 )`` Horn state is ignored (default)
189+
- ``Horn ( 1 )`` Horn must not have been sounded recently
190+
- ``Horn ( 2 )`` Horn must have been sounded recently
191+
192+
Note that the solid ditch lights state should use ``Horn(1)`` to
193+
prevent these lights overlapping the flashing state. An example
194+
implementation of a flashing ditch light's conditions (many other
195+
details removed for clarity) is provided below::
196+
197+
Light (
198+
comment( Right ditch light )
199+
Conditions (
200+
Headlight ( 3 )
201+
Unit ( 2 )
202+
Horn ( 1 )
203+
)
204+
States ( 1
205+
State (
206+
LightColour ( FFFFFFFF )
207+
Radius ( r )
208+
Position ( x y z )
209+
)
210+
)
211+
)
212+
Light (
213+
comment( Right ditch light Flashing )
214+
Conditions (
215+
Headlight ( 3 )
216+
Unit ( 2 )
217+
Horn ( 2 )
218+
)
219+
States ( 2
220+
State (
221+
LightColour ( FFFFFFFF )
222+
Radius ( r )
223+
Transition ( 1 )
224+
Duration ( 0.5 )
225+
Position ( x y z )
226+
)
227+
State (
228+
LightColour ( FFFFFFFF )
229+
Radius ( r )
230+
Transition ( 1 )
231+
Duration ( 0.5 )
232+
Position ( x y z )
233+
)
234+
)
235+
)
236+
237+
.. index::
238+
single: Conditions(Bell
239+
single: ORTSBellLightsTimer
240+
241+
Bell (Automatic Flashing Ditch Lights)
242+
''''''''''''''''''''''''''''''''''''''
243+
244+
Similar to ``Horn``, the ``Bell`` condition is useful for replicating
245+
systems with flashing lights activated by the bell, though this is
246+
less common than using the horn. Like with the horn, a timer can be
247+
set to keep the lights activated for a time after the bell starts ringing.
248+
Unlike with the horn, this timer is set to 0 seconds by default, meaning
249+
the lights will only remain (de)activated while the bell is currently ringing.
250+
If a timer is desired, ``engine(ORTSBellLightsTimer`` can be used in
251+
the locomotive's .eng file.
252+
253+
- ``Bell ( 0 )`` Bell state is ignored (default)
254+
- ``Bell ( 1 )`` Bell must not have been ringing recently
255+
- ``Bell ( 2 )`` Bell must have been ringing recently or is ringing now
256+
257+
.. index::
258+
single: Conditions(Brake
259+
260+
Multiple Unit Configuration (Locomotives Only)
261+
''''''''''''''''''''''''''''''''''''''''''''''
262+
263+
Some MU systems send headlight signals through the wires connecting locomotives,
264+
but do not or cannot send these signals through wagons/coaches to remote
265+
locomotives (eg: distributed power, banking locomotives, etc.). The ``MU``
266+
light condition allows for some flexibility in adjusting light behavior depending
267+
on a locomotive's physical connection to the lead locomotive (or lack thereof).
268+
While meant for locomotives only, wagons are always treated as remote locomotives
269+
for the purposes of calculation.
270+
271+
- ``MU ( 0 )`` Locomotives's connection to the lead locomotive is ignored (default)
272+
- ``MU ( 1 )`` Locomotive must be the lead locomotive itself
273+
- ``MU ( 2 )`` Locomotive must be in the same group of locomotives as the lead locomotive
274+
- This condition will also be fulfilled for the lead locomotive itself.
275+
- ``MU ( 3 )`` Locomotive must be in a different group to the lead locomotive
276+
277+
13278

14279
Tilting trains
15280
==============
@@ -588,7 +853,7 @@ the ``.load-or`` files in a consistent way: ``40HCtriton.load-or`` is suggested
588853
container type and ``triton`` the brand painted on the container.
589854

590855
Format of the .load-or file
591-
'''''''''''''''''''''''
856+
'''''''''''''''''''''''''''
592857

593858
Here below a sample of a ``.load-or`` file::
594859

@@ -1217,6 +1482,8 @@ shape movement, however for greater accuracy the modeler can add specific values
12171482
``ORTSLengthAirHose``. In addition the length values suggested in the Derailment Coefficient should
12181483
also be added.
12191484

1485+
.. _features-passenger-doors:
1486+
12201487
Passenger doors
12211488
===============
12221489

‎Source/Documentation/Manual/physics.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4560,7 +4560,8 @@ Example::
45604560
)
45614561
)
45624562

4563-
The state of the battery switch can be used in the :ref:`power supply scripts <features-scripting-powersupply>` and the :ref:`cabview controls <cabs-battery-switch>`.
4563+
The state of the battery switch can be used in the :ref:`power supply scripts <features-scripting-powersupply>`,
4564+
:ref:`cabview controls <cabs-battery-switch>`, and :ref:`train car lighting <features-light-conditions>`.
45644565

45654566
.. _physics-master-key:
45664567

0 commit comments

Comments
 (0)