Add implementation of multi-aspect signalling and GRF support

Requires realistic braking See: #247
2021-08-28 12:51:06 +01:00
parent 6546f6deba
commit b2ef6c0de8
28 changed files with 917 additions and 35 deletions
--- a/docs/landscape.html
+++ b/docs/landscape.html
@@ -508,6 +508,8 @@

         <li>m3 bits 7..4: bit set = signal 3..0 present</li>
         <li>m4 bits 7..4: bit clear = signal 3..0 shows red</li>
+         <li style="color: blue">m7 bits 5..3: signal aspect for signal 0 or 1 (only valid if signal is present and not red, and multi-aspect signalling is in effect)</li>
+         <li style="color: blue">m7 bits 2..0: signal aspect for signal 2 or 3 (only valid if signal is present and not red, and multi-aspect signalling is in effect)</li>
        </ul>
       </li>
       <li>m2 bits 8..10: track reserved for pbs
@@ -1740,6 +1742,8 @@
       <li>m6 bit 0: set = entrance signal shows green, clear = entrance signal shows red</li>
       <li>m2 bit 15: for bridge entrances only: storage for visual red/green state of signals starting from 15 is allocated outside the map array</li>
       <li>m2 bits 14..4: for bridge entrances only: for signals 0..10 on bridge, signal is visually red if corresponding bit in 4..14 is set</li>
+       <li>m3 bits 5..3: entrance signal aspect (only valid if signal is present and not red, and multi-aspect signalling is in effect)</li>
+       <li>m3 bits 2..0: exit signal aspect (only valid if signal is present and not red, and multi-aspect signalling is in effect)</li>
      </ul>
     </li>
     <li>m5 bits 3..2: transport type
--- a/docs/landscape_grid.html
+++ b/docs/landscape_grid.html
@@ -104,7 +104,7 @@ the array so you can quickly see what is used and what is not.
      <td class="bits"><span class="free">OOOO</span> <span class="used" title="Ground type: fences, snow, desert">XXXX</span></td>
      <td class="bits"><span class="used" title="Rail tile type: rail, rail with signals, depot">OO</span> <span class="used" title="Track pieces">XXXXXX</span></td>
      <td class="bits" rowspan=3><span class="free">OOOO OOOO</span></td>
-      <td class="bits" rowspan=3><span class="free">OOOO OOOO</span></td>
+      <td class="bits"><span class="free">OOOO OOOO</span></td>
      <td class="bits" rowspan=2><span class="free">OOOO</span> <span class="patch" title="Secondary railway type (used for lower or right track when two parallel tracks on tile)">PPPP PP</span><span class="used" title="Railway type">XX XXXX</span></td>
    </tr>
    <tr>
@@ -113,6 +113,7 @@ the array so you can quickly see what is used and what is not.
      <td class="bits"><span class="used" title="Signals present">XXXX</span> <span class="free">OOOO</span></td>
      <td class="bits"><span class="used" title="Signals colors">XXXX</span> <span class="used" title="Ground type: fences, snow, desert">XXXX</span></td>
      <td class="bits"><span class="used" title="Rail tile type: rail, rail with signals, depot">O1</span> <span class="used" title="Track pieces">XXXXXX</span></td>
+      <td class="bits"><span class="free">OO</span> <span class="patch" title="Signal aspects">PPPPPP</span></td>
    </tr>
    <tr>
      <td class="caption">depot</td>
@@ -120,6 +121,7 @@ the array so you can quickly see what is used and what is not.
      <td class="bits"><span class="free">OOOO</span> <span class="free">OOOO</span></td>
      <td class="bits"><span class="free">OOOO</span> <span class="used" title="Ground type: fences, snow, desert (fences on depot are not valid)">XXXX</span></td>
      <td class="bits"><span class="used" title="Rail tile type: rail, rail with signals, depot">11</span><span class="free">O</span><span class="used" title="PBS reservation">X</span> <span class="free">OO</span><span class="used" title="Depot exit direction">XX</span></td>
+      <td class="bits"><span class="free">OOOO OOOO</span></td>
      <td class="bits"><span class="free">OOOO OOOO OO</span><span class="used" title="Railway type">XX XXXX</span></td>
    </tr>
    <tr>
@@ -285,7 +287,7 @@ the array so you can quickly see what is used and what is not.
      <td class="caption">tunnel entrance</td>
      <td class="bits" rowspan=3><span class="free">OOO</span> <span class="used" title="Owner">XXXXX</span></td>
      <td class="bits"><span class="patch-pool" title="Tunnel index on pool (or overflow sentinel)">PPPP PPPP PPPP PPPP</span></td>
-      <td class="bits" rowspan=4><span class="rearrange" title="Owner of tram (road only; a rearrangement can free some of these bits)">XXXX</span> <span class="free">OOOO</span></td>
+      <td class="bits" rowspan=4><span class="rearrange" title="Owner of tram (road only; a rearrangement can free some of these bits)">XXXX</span> <span class="free">OOOO</span><br /><span class="free">OO</span> <span class="patch" title="Entrance/exit signal aspects (rail only)">PPPPPP</span></td>
      <td class="bits"><span class="free">OO</span><span class="used" title="Road type">XX XXXX</span></td>
      <td class="bits"><span class="used" title="Bridge or tunnel bit">O</span><span class="patch" title="Signal simulation mode (rail only)">PP</span><span class="rearrange" title="PBS reservation (rail; a rearrangement can free some of these bits)">X</span> <span class="used" title="Transport type">XX</span> <span class="used" title="Direction of the tunnel/bridge">XX</span></td>
      <td class="bits"><span class="patch" title="PBS mode, exit signal state">PP</span><span class="free">OO OO</span><span class="patch" title="Semaphore/light mode, entrance signal state">PP</span></td>
--- a/docs/newgrf-additions-nml.html
+++ b/docs/newgrf-additions-nml.html
@@ -66,6 +66,23 @@
 			If the OpenTTD version does not support this property/feature, then the property would ordinarily be ignored/skipped and no recolouring would be done.
 		</td>
 	</tr>
+	<tr><td>extra_aspects</td><td>0 - 6</td>
+		<td>
+			The value is the number of additional signal aspects to use (e.g. 4-aspect signalling should use a value of 2).<br />
+			When set, the lowest byte of <span class="code">extra_callback_info2</span> (signal state) may have the given number of additional values starting from 02:
+			<table>
+			<tr><th>Value</th><th>Meaning</th></tr>
+			<tr><td>00</td><td>Red signal</td></tr>
+			<tr><td>01</td><td>Green signal</td></tr>
+			<tr><td>02</td><td>1st extra aspect (e.g. yellow)</td></tr>
+			<tr><td>03</td><td>2nd extra aspect (e.g. double yellow)</td></tr>
+			<tr><td>...</td><td>Further extra aspects...</td></tr>
+			</table>
+			<br />
+			The provided value is currently clamped to be within the range 0 - 6 (inclusive).<br />
+			N.B. Realistic braking must be enabled for additional signal aspects to be used
+		</td>
+	</tr>
 	<tr><td>disable_realistic_braking</td><td>0 or 1</td>
 		<td>
 			When this property is set realistic braking is disabled for trains of this railtype even when realistic braking is otherwise in effect.
@@ -161,6 +178,23 @@
 			</table>
 		</td>
 	</tr>
+	<tr><td>extra_aspects</td><td>0 - 6</td>
+		<td>
+			The value is the number of additional signal aspects to use (e.g. 4-aspect signalling should use a value of 2).<br />
+			When set, the lowest byte of <span class="code">extra_callback_info2</span> (signal state) may have the given number of additional values starting from 02:
+			<table>
+			<tr><th>Value</th><th>Meaning</th></tr>
+			<tr><td>00</td><td>Red signal</td></tr>
+			<tr><td>01</td><td>Green signal</td></tr>
+			<tr><td>02</td><td>1st extra aspect (e.g. yellow)</td></tr>
+			<tr><td>03</td><td>2nd extra aspect (e.g. double yellow)</td></tr>
+			<tr><td>...</td><td>Further extra aspects...</td></tr>
+			</table>
+			<br />
+			The provided value is currently clamped to be within the range 0 - 6 (inclusive).<br />
+			N.B. Realistic braking must be enabled for additional signal aspects to be used
+		</td>
+	</tr>
 	</table>
 	<p>
 	Custom signal sprites example:
--- a/docs/newgrf-additions.html
+++ b/docs/newgrf-additions.html
@@ -241,6 +241,22 @@
 	</table></p>
 	<p>The property length is 1 byte. 0 is disabled (default). 1 is enabled.</p>
 	<p>This is indicated by the feature name: <font face="monospace">action0_railtype_recolour</font>, version 1</p>
+	<h4 id="railtype_extra_aspects">Set number of additional signal aspects (mappable property: railtype_extra_aspects)</h4>
+	<p>This applies to <a href="https://newgrf-specs.tt-wiki.net/wiki/Action3/Railtypes#Signal_sprites_.280B.29">Action 2/3 - Railtype custom signal sprites</a>.<br />
+	The value is the number of additional signal aspects to use (e.g. 4-aspect signalling should use a value of 2).<br />
+	When set, the lowest byte of variable 0x18 (SS: signal state) may have the given number of additional values starting from 02:
+	<table>
+	<tr><th>Value</th><th>Meaning</th></tr>
+	<tr><td>00</td><td>Red signal</td></tr>
+	<tr><td>01</td><td>Green signal</td></tr>
+	<tr><td>02</td><td>1st extra aspect (e.g. yellow)</td></tr>
+	<tr><td>03</td><td>2nd extra aspect (e.g. double yellow)</td></tr>
+	<tr><td>...</td><td>Further extra aspects...</td></tr>
+	</table></p>
+	<p>The property length is 1 byte.<br />
+	The provided value is currently clamped to be within the range 0 - 6 (inclusive).</p>
+	<p>N.B. Realistic braking must be enabled for additional signal aspects to be used.</p>
+	<p>This is indicated by the feature name: <font face="monospace">action0_railtype_extra_aspects</font>, version 1</p>
 	<h4 id="railtype_disable_realistic_braking">Disable use of realistic braking with this rail type (mappable property: railtype_disable_realistic_braking)</h4>
 	<p>When this property is set realistic braking is disabled for trains of this railtype even when realistic braking is otherwise in effect.<br />
 	The property length is 1 byte. 0 is realistic braking is not disabled for this railtype. 1 is disable realistic braking for this railtype.
@@ -319,6 +335,22 @@
 	The Action 0 Id field is not used, the value is ignored.
 	</p>
 	<p>This is indicated by the feature name: <font face="monospace">action0_signals_recolour</font>, version 1</p>
+	<h4 id="signals_extra_aspects">Set number of additional signal aspects (mappable property: signals_extra_aspects)</h4>
+	<p>This applies to <a href="#a3signals_custom_signal_sprites">Action 2/3 Signals (Feature 0E) custom signal sprites</a> for this GRF.<br />
+	The value is the number of additional signal aspects to use (e.g. 4-aspect signalling should use a value of 2).<br />
+	When set, the lowest byte of variable 0x18 (SS: signal state) may have the given number of additional values starting from 02:
+	<table>
+	<tr><th>Value</th><th>Meaning</th></tr>
+	<tr><td>00</td><td>Red signal</td></tr>
+	<tr><td>01</td><td>Green signal</td></tr>
+	<tr><td>02</td><td>1st extra aspect (e.g. yellow)</td></tr>
+	<tr><td>03</td><td>2nd extra aspect (e.g. double yellow)</td></tr>
+	<tr><td>...</td><td>Further extra aspects...</td></tr>
+	</table></p>
+	<p>The property length is 1 byte.<br />
+	The provided value is currently clamped to be within the range 0 - 6 (inclusive).</p>
+	<p>N.B. Realistic braking must be enabled for additional signal aspects to be used.</p>
+	<p>This is indicated by the feature name: <font face="monospace">action0_signals_extra_aspects</font>, version 1</p>
 	<br />
 	<br />
 	<h3 id="varaction2_station"><a href="https://newgrf-specs.tt-wiki.net/wiki/VariationalAction2/Stations">Variational Action 2 - Stations</a></h3>