<h2>Additions to NewGRF Specifications in JGR's Patchpack</h2>
<p>This document describes non-standard additions to the <ahref="https://newgrf-specs.tt-wiki.net/wiki/Main_Page">Official OpenTTD NewGRF Specifications</a> which are present in this patchpack.
<p>A subset of the features listed below are also supported in a fork of NML, see the associated <ahref="newgrf-additions-nml.html">NML document</a> for more details.</p>
<p>NewGRFs which use any of these features SHOULD use the <ahref="#feature-test">feature testing</a> mechanism described below to check whether individual added features are supported.</p>
<p>Feature tests can be safely used on implementations which do not implement the described feature test mechanism because unknown Action 14 blocks are ignored,
and the observable result (in global variable 0x9D) is equivalent to the case where all feature tests have failed, indicating that the feature is not present.</p>
<p>Within an FTST chunk, the SETP binary (type B) field contains the bit number to set/clear in
<ahref="https://newgrf-specs.tt-wiki.net/wiki/GlobalVariables">global variable</a> 0x9D (TTD Platform) to store the result of the test. This is 1 byte.<br/>
If the test is successful, the bit is set (to 1), otherwise the bit is cleared (to 0).<br/>
The bit number MUST be in the range: 4 ≤ bit number ≤ 31. These bits can be assumed to be 0 on implementations which do not support this feature test mechanism.<br/>
Global variable 0x9D can then be tested by using a standard <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action7">Action 7 or 9</a>, or a standard <ahref="https://newgrf-specs.tt-wiki.net/wiki/VariationalAction2">Variational Action 2</a>.<br/>
If this field is omitted, no bit is set or cleared, and the test is not observable.
<p>Each A0PM chunk (type C) describes an individual property mapping.<br/>
Sub-chunks within each A0PM chunk may appear in any order, however except where otherwise noted each sub-chunk SHOULD only appear ONCE within an individual A0PM chunk.</p>
<p>Property mapping can be safely used on implementations which do not implement the property mapping mechanism if Action 0 sprites which use mapped property IDs are skipped if one or more of:
<ul>
<li>The global variable 0x8D is checked to determine whether the property mapping operation was successful.</li>
<li>The feature name <fontface="monospace">property_mapping</font> is checked for.</li>
</ul>
Unknown Action 14 blocks are ignored, and do not need to be skipped.</p>
<p>Within an A0PM chunk, the FEAT binary (type B) field contains the <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action0#Feature">Action 0 feature ID</a>. This is 1 byte.</p>
<p>Within an A0PM chunk, the PROP binary (type B) field contains the property ID to allocate to the named property, this value can used in Action 0 sprites. This is 1 byte.<br/>
It is possible to override existing properties, however this use is not recommended.</p>
<p>Within an A0PM chunk, the SETT binary (type B) field contains the bit number to set/clear in
<ahref="https://newgrf-specs.tt-wiki.net/wiki/GlobalVariables">global variable</a> 0x8D (TTD version) to store whether the mapping operation was successful. This is 1 byte.<br/>
If the operation is successful, the bit is set (to 1), otherwise the bit is cleared (to 0).<br/>
The bit number MUST be in the range: 4 ≤ bit number ≤ 31. These bits can be assumed to be 0 on implementations which do not support this property mapping mechanism.<br/>
Global variable 0x8D can then be tested by using a standard <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action7">Action 7 or 9</a>, or a standard <ahref="https://newgrf-specs.tt-wiki.net/wiki/VariationalAction2">Variational Action 2</a>.<br/>
If this field is omitted, no bit is set or cleared.
<p>Within an A0PM chunk, the FLBK binary (type B) field contains the fallback mode. This is 1 byte.<br/>
The fallback mode may take the following values:
<table>
<tr><th>Value</th><th>Behaviour</th></tr>
<tr><td>0</td><td>Attempts to map an unknown property name are ignored. Use of the mapped property in an Action 0 is ignored. This is the default.</td></tr>
<tr><td>1</td><td>Attempts to map an unknown property name are ignored. Use of the mapped property in an Action 0 is an error.</td></tr>
<tr><td>2</td><td>Attempting to map an unknown property name is an error.</td></tr>
</table>
Attempts to set a fallback mode other than those listed above are silently ignored. More fallback modes MAY be added in future versions of this mechanism.<br/>
This chunk MAY be specified more than once, in which case the last specified valid value is used.<br/>
Note that even when using fallback mode 0, above, if the property mapping feature is not present, then use of the mapped property ID in an Action 0 is an error.
Note that each use of the mapped property ID is followed by Num-info iterations of the size and data pair above. See: <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action0">Action 0 Specification</a>.
<p>This property allows building bridges over stations.<br/>
The bridge height property defines minimum clearances required for a bridge for each of the 8 station layouts (or 0 to not allow any bridge). Values are given in height level units (1 level == 8px).<br/>
Each height value is 1 byte, the total property length is 8 bytes.
<h4id="railtype_enable_programmable_signals">Enable custom signal sprites for programmable pre-signals (mappable property: railtype_enable_programmable_signals)</h4>
<h4id="railtype_enable_restricted_signals">Enable restricted signal flag for custom signal sprites (mappable property: railtype_enable_restricted_signals)</h4>
<p>This applies to <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action3/Railtypes#Signal_sprites_.280B.29">Action 2/3 - Railtype custom signal sprites</a>.<br/>
When enabled, bit 24 of variable 18 (extra callback info) is set if the signal is restricted (has a routing restriction program attached).<br/>
<h4id="railtype_enable_signal_recolour">Enable recolouring for custom signal sprites (mappable property: railtype_enable_signal_recolour)</h4>
<p>This applies to <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action3/Railtypes#Signal_sprites_.280B.29">Action 2/3 - Railtype custom signal sprites</a>.<br/>
When enabled, in addition to returning a sprite, register 0x100 may be set to the following:
<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></p>
<p>The property length is 1 byte. 0 is disabled (default). 1 is enabled.</p>
<p>This is indicated by the feature name: <fontface="monospace">action0_railtype_recolour</font>, version 1</p>
<h4id="railtype_extra_aspects">Set number of additional signal aspects (mappable property: railtype_extra_aspects)</h4>
<p>This applies to <ahref="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: <fontface="monospace">action0_railtype_extra_aspects</font>, version 1</p>
<h4id="railtype_disable_realistic_braking">Disable use of realistic braking with this rail type (mappable property: railtype_disable_realistic_braking)</h4>
<h4id="global_extra_station_names">Extra station names (mappable property: global_extra_station_names)</h4>
<p>This adds extra station names for use when all the avilable station names for a given town have been used.<br/>
The string should have the same format and use the same ID range as
<ahref="https://newgrf-specs.tt-wiki.net/wiki/Action0/Industries#Default_name_for_nearby_station_.2824.29">industry - default name for nearby station</a>.<br/>
The Action 0 ID field is ignored. This property always adds a new station name string instead of overwriting an existing one.<br/>
<p>Note that Action 0 feature 0E is not supported (does nothing) in standard OpenTTD.</p>
<p>This implementation of feature 0E is not the same as that in TTDPatch.</p>
<h4id="signals_enable_programmable_signals">Enable custom signal sprites for programmable pre-signals (mappable property: signals_enable_programmable_signals)</h4>
<p>This enables <ahref="#a3signals_custom_signal_sprites">Action 2/3 Signals (Feature 0E) custom signal sprites</a> for programmable pre-signals for this GRF.<br/>
Programmable pre-signals have the signal type value: 06.<br/>
The property length is 1 byte. 0 is disabled (default). 1 is enabled.<br/>
The Action 0 Id field is not used, the value is ignored.
</p>
<p>This is indicated by the feature name: <fontface="monospace">action0_signals_programmable_signals</font>, version 1</p>
<h4id="signals_enable_no_entry_signals">Enable custom signal sprites for no-entry signals (mappable property: signals_enable_no_entry_signals)</h4>
<p>This enables <ahref="#a3signals_custom_signal_sprites">Action 2/3 Signals (Feature 0E) custom signal sprites</a> for no-entry signals for this GRF.<br/>
No-entry signals have the signal type value: 07.<br/>
The property length is 1 byte. 0 is disabled (default). 1 is enabled.
</p>
<p>This is indicated by the feature name: <fontface="monospace">action0_signals_no_entry_signals</font>, version 1</p>
<h4id="signals_enable_restricted_signals">Enable restricted signal flag for custom signal sprites (mappable property: signals_enable_restricted_signals)</h4>
<p>This applies to <ahref="#a3signals_custom_signal_sprites">Action 2/3 Signals (Feature 0E) custom signal sprites</a> for this GRF.<br/>
When enabled, bit 24 of variable 18 (extra callback info) 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 should only be set if the Action 2/3 actually returns a different sprite when bit 24 of variable 18 is set.<br/>
The property length is 1 byte. 0 is disabled (default). 1 is enabled.<br/>
The Action 0 Id field is not used, the value is ignored.
</p>
<p>This is indicated by the feature name: <fontface="monospace">action0_signals_restricted_signals</font>, version 1</p>
<p>Note that Action 3 feature 0E is not supported (does nothing) in standard OpenTTD.</p>
<p>This implementation of feature 0E is not the same as that in TTDPatch.</p>
<h4id="a3signals_custom_signal_sprites">Custom signal sprites using Action 2/3 (action 3 ID: 0)</h4>
<p>This feature allows using Action 3 to assign an Action 2 chain which dynamically resolves signal sprites, in a very similar way to that of <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action3/Railtypes#Signal_sprites_.280B.29">Action 2/3 - Railtype custom signal sprites</a>,<br/>
however, this applies to all signals, not only those of a particular rail type.</p>
<p>Variational Action 2 variables 10, 18 and 40 are available and have the same format as in <ahref="https://newgrf-specs.tt-wiki.net/wiki/VariationalAction2/Railtypes">VariationalAction2/Railtypes</a>.</p>
<p>Rail type custom signal sprites have a higher priority than custom signal sprites for all signals as set here.</p>
<p>Note that this is not a generic callback, the sprite group must be assigned to ID 0 (further IDs may be allocated for other purposes in future).</p>
<p>This is indicated by the feature name: <fontface="monospace">action3_signals_custom_signal_sprites</font>, version 1</p>
<p>See <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action14">Action 14 Specification</a> and <ahref="https://newgrf-specs.tt-wiki.net/wiki/Action5">Action 5 Specification</a> for background information.</p>
<p>The action 5 type ID mapping mechanism has the feature name: <fontface="monospace">action5_type_id_mapping</font>, this document describes version 1.</p>
<p>Users of this mechanism SHOULD at minimum test for the presence of the feature above or test variable 8D, below.</p>
<p>Each A5TM chunk (type C) describes an individual action 5 type ID mapping.<br/>
Sub-chunks within each A5TM chunk may appear in any order, however except where otherwise noted each sub-chunk SHOULD only appear ONCE within an individual A5TM chunk.</p>
<p>Action 5 type ID mapping can be safely used on implementations which do not implement the type ID mapping mechanism if Action 5 sprites which use mapped type IDs are skipped if one or more of:
<ul>
<li>The global variable 0x8D is checked to determine whether the type ID mapping operation was successful.</li>
<li>The feature name <fontface="monospace">action5_type_id_mapping</font> is checked for.</li>
</ul>
Unknown Action 14 blocks are ignored, and do not need to be skipped.</p>
<p>Within an A5TM chunk, the TYPE binary (type B) field contains the type ID to allocate to the named type, this value can used in Action 5 sprites. This is 1 byte. The value MUST be < 128 (i.e bit 7 must be clear).<br/>
It is possible to override existing type IDs, however this use is not recommended.</p>
<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 <ahref="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.
<h4id="no_entry_signals">No-entry signal graphics (mappable type: no_entry_signals)</h4>
<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 <ahref="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.
