5d351a14d2
This is only passable in one direction, but does not have a signal or show an aspect in the opposite direction Add a setting for whether this is shown in the signal UI. Off by default.
254 lines
12 KiB
HTML
254 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|
<title>JGR's Patchpack - Additions to NewGRF Specifications (NML)</title>
|
|
<style type="text/css">
|
|
td li { white-space: nowrap; text-align: left; }
|
|
th { white-space: nowrap; text-align: center; }
|
|
td, th { border: 1px solid #CCCCCC; padding: 0px 5px; }
|
|
table { border-collapse: collapse; empty-cells: show; }
|
|
span.code { font-family: "Courier New", Courier, mono; color: darkgreen; }
|
|
pre.code { font-family: "Courier New", Courier, mono; color: blue; background-color: #f8f9fa; border: 1px solid #eaecf0; padding: 1em; }
|
|
dt { font-weight: bold; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h2>Additions to NewGRF Specifications in JGR's Patchpack in NML</h2>
|
|
<p>This document describes non-standard additions to the <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Main">Official OpenTTD NML Specifications</a> which are present in this patchpack and the associated <a href="https://github.com/JGRennison/nml">NML fork</a>.
|
|
<p>These additions MAY also be present in other patchpacks. They MAY be removed or moved in future, if necessary.</p>
|
|
|
|
<p>Not all standard NewGRF features are supported by NML, consequently not all non-standard additions to the specifications are supported by this patchpack's associated NML fork, or are listed in this document.<br />
|
|
See the associated <a href="newgrf-additions.html">non-NML document</a> for more details.</p>
|
|
|
|
<p>All of the non-standard features listed below will automatically emit suitable feature tests, conditionals, etc. such that NewGRFs which use these features will work correctly
|
|
on OpenTTD versions which do not support these features, including standard trunk OpenTTD and older/other patchpack versions.</p>
|
|
|
|
<h3><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions">Builtin functions</a></h3>
|
|
|
|
<p>
|
|
<h4>extended_feature_test(feature_name[, min_version[, max_version]])</h4>
|
|
This returns true if the given extended feature is present and has a version within the specified minimum and maximum (inclusive).<br />
|
|
This function should only be used after the grf{} block.<br />
|
|
In most cases it is not necessary to use this function, as extended properties (listed below) which are not supported are simply skipped/ignored.
|
|
</p>
|
|
|
|
<h3><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#Railtype_properties">Railtypes properties</a></h3>
|
|
<table>
|
|
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
|
|
<tr><td>enable_programmable_pre_signals</td><td>0 or 1</td>
|
|
<td>
|
|
Enable programmable pre-signal graphics in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
|
|
Programmable pre-signals have a signal type (<span class="code">getbits(extra_callback_info2, 16, 8)</span>) of 6.
|
|
</td>
|
|
</tr>
|
|
<tr><td>enable_no_entry_signals</td><td>0 or 1</td>
|
|
<td>
|
|
Enable no-entry signal graphics in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
|
|
No-entry signals have a signal type (<span class="code">getbits(extra_callback_info2, 16, 8)</span>) of 7.<br />
|
|
No-entry signals always have a signal state of red.
|
|
</td>
|
|
</tr>
|
|
<tr><td>enable_restricted_signals</td><td>0 or 1</td>
|
|
<td>
|
|
Enable restricted signal flag in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
|
|
When enabled, bit 24 of variable <span class="code">extra_callback_info2</span> is set if the signal is restricted (has a routing restriction program attached).<br />
|
|
When enabled, the "Show restricted electric signals using default graphics" client setting and signal post recolouring is not applied.<br />
|
|
This flag must only be set if a different sprite is returned when bit 24 of <span class="code">extra_callback_info2</span> is set.
|
|
</td>
|
|
</tr>
|
|
<tr><td>enable_signal_recolour</td><td>0 or 1</td>
|
|
<td>
|
|
Enable recolouring of graphics in <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
|
|
When enabled, in addition to returning a sprite, register 0x100 may be set to the following using STORE_TEMP:
|
|
<table>
|
|
<tr><th>Bits</th><th>Meaning</th></tr>
|
|
<tr><td>0 - 23</td><td>Recolour sprite to use. Set to 0 for no recolouring.</td></tr>
|
|
<tr><td>24 - 31</td><td>Reserved, set to zero.</td></tr>
|
|
</table>
|
|
<br />
|
|
If recolouring is not optional, the feature name: <span class="code">action0_railtype_recolour</span> should be checked using the
|
|
<span class="code">extended_feature_test</span> function
|
|
and if necessary a suitable fallback used or error message shown.<br />
|
|
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.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h3><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Roadtypes#Roadtype_properties">Roadtype properties</a></h3>
|
|
<table>
|
|
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
|
|
<tr><td>roadtype_extra_flags</td><td>bitmask(ROADTYPE_EXTRA_FLAG_XXX, ...)</td>
|
|
<td>
|
|
<dl>
|
|
<dt>NO_SCRIPT_BUILD</dt>
|
|
<dd>Scripts (AI/GS) may not build this roadtype</dd>
|
|
<dt>NO_TOWN_MODIFY</dt>
|
|
<dd>Towns may not modify tiles of this roadtype in any way whatsoever</dd>
|
|
</dl>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h3><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Tramtypes#Tramtype_properties">Tramtype properties</a></h3>
|
|
<table>
|
|
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
|
|
<tr><td>tramtype_extra_flags</td><td>bitmask(TRAMTYPE_EXTRA_FLAG_XXX, ...)</td>
|
|
<td>
|
|
<dl>
|
|
<dt>NO_SCRIPT_BUILD</dt>
|
|
<dd>Scripts (AI/GS) may not build this tramtype</dd>
|
|
<dt>NO_TOWN_MODIFY</dt>
|
|
<dd>Towns may not modify tiles of this tramtype in any way whatsoever</dd>
|
|
</dl>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h3><a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Replace_new_sprites">Replace new sprites</a></h3>
|
|
<table>
|
|
<tr><th>Type</th><th>Number of sprites </th><th>Comment</th></tr>
|
|
<tr><td>PROGRAMMABLE_PRE_SIGNAL</td><td>32</td>
|
|
<td>
|
|
<b>Programmable pre-signals</b>
|
|
<p>Signal graphics come in groups of 16. These groups contain sprites in the same order as sprites 1275-1290 in trg1[r].grf and <a href="https://newgrf-specs.tt-wiki.net/wiki/Action5#04_Signal_graphics.">Action 5 type 4 (signals)</a>;
|
|
red, then green, for each of: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing.
|
|
<table>
|
|
<tr><th>Group</th><th>Contents</th></tr>
|
|
<tr><td>0</td><td>Semaphore programmable pre-signals</td></tr>
|
|
<tr><td>1</td><td>Lighted programmable pre-signals</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
<tr><td>NO_ENTRY_SIGNAL</td><td>16</td>
|
|
<td>
|
|
<b>No-entry signals</b>
|
|
<p>No-entry signal graphics come in groups of 8. These groups contain sprites in the same order as the red sprites of 1275-1290 in trg1[r].grf and <a href="https://newgrf-specs.tt-wiki.net/wiki/Action5#04_Signal_graphics.">Action 5 type 4 (signals)</a>;
|
|
red only, for each of: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing.
|
|
<table>
|
|
<tr><th>Group</th><th>Contents</th></tr>
|
|
<tr><td>0</td><td>Semaphore no-entry signals</td></tr>
|
|
<tr><td>1</td><td>Lighted no-entry signals</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h3>Signal graphics using switches</h3>
|
|
<p>
|
|
This feature allows signal sprites to be specified using switches in a very similar manner to <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a> in
|
|
<span class="code">item (FEAT_RAILTYPES) { graphics { signals: ... } }</span> blocks.<br />
|
|
However this applies to all signals, not only those of a particular rail type.<br />
|
|
Railtype signal graphics have a higher priority than general signal graphics as set here.<br />
|
|
<br />
|
|
Variables: <span class="code">extra_callback_info1</span>, <span class="code">extra_callback_info2</span>, and <span class="code">terrain_type</span>
|
|
are the same as for <a href="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br />
|
|
<br />
|
|
This feature is not supported by standard OpenTTD or by standard NML.<br/>
|
|
If the use of this feature is not optional, the feature name: <span class="code">action3_signals_custom_signal_sprites</span> should be checked using the
|
|
<span class="code">extended_feature_test</span> function
|
|
and if necessary a suitable fallback used or error message shown.<br />
|
|
<br />
|
|
An <span class="code">item (FEAT_SIGNALS, custom_signals, 0) { }</span> block should be used to define properties and graphics.<br />
|
|
The graphics block should contain a single default switch.
|
|
</p>
|
|
<table>
|
|
<tr><th>Property</th><th>Value range</th><th>Comment</th></tr>
|
|
<tr><td>enable_programmable_pre_signals</td><td>0 or 1</td>
|
|
<td>
|
|
Enable programmable pre-signal graphics.<br />
|
|
Programmable pre-signals have a signal type (<span class="code">getbits(extra_callback_info2, 16, 8)</span>) of 6.
|
|
</td>
|
|
</tr>
|
|
<tr><td>enable_no_entry_signals</td><td>0 or 1</td>
|
|
<td>
|
|
Enable no-entry signal graphics.<br />
|
|
No-entry signals have a signal type (<span class="code">getbits(extra_callback_info2, 16, 8)</span>) of 7.<br />
|
|
No-entry signals always have a signal state of red.
|
|
</td>
|
|
</tr>
|
|
<tr><td>enable_restricted_signals</td><td>0 or 1</td>
|
|
<td>
|
|
Enable restricted signal flag.<br />
|
|
When enabled, bit 24 of variable <span class="code">extra_callback_info2</span> is set if the signal is restricted (has a routing restriction program attached).<br />
|
|
When enabled, the "Show restricted electric signals using default graphics" client setting and signal post recolouring is not applied.<br />
|
|
This flag must only be set if a different sprite is returned when bit 24 of <span class="code">extra_callback_info2</span> is set.
|
|
</td>
|
|
</tr>
|
|
<tr><td>enable_signal_recolour</td><td>0 or 1</td>
|
|
<td>
|
|
Enable recolouring of graphics<br />
|
|
When enabled, in addition to returning a sprite, register 0x100 may be set to the following using STORE_TEMP:
|
|
<table>
|
|
<tr><th>Bits</th><th>Meaning</th></tr>
|
|
<tr><td>0 - 23</td><td>Recolour sprite to use. Set to 0 for no recolouring.</td></tr>
|
|
<tr><td>24 - 31</td><td>Reserved, set to zero.</td></tr>
|
|
</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:
|
|
<pre class="code">
|
|
grf {
|
|
...
|
|
}
|
|
|
|
if (!extended_feature_test("action3_signals_custom_signal_sprites")) {
|
|
error(FATAL, string(STR_UNSUPPORTED_VERSION));
|
|
}
|
|
|
|
switch (FEAT_SIGNALS, SELF, switch_signals, ...) {
|
|
...
|
|
}
|
|
|
|
|
|
item (FEAT_SIGNALS, custom_signals, 0) {
|
|
property {
|
|
enable_signal_recolour: 1;
|
|
}
|
|
|
|
graphics {
|
|
switch_signals;
|
|
}
|
|
}
|
|
</pre>
|
|
</p>
|
|
</body>
|
|
</html>
|