<h2>Additions to NewGRF Specifications in JGR's Patchpack in NML</h2>
<p>This document describes non-standard additions to the <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Main">Official OpenTTD NML Specifications</a> which are present in this patchpack and the associated <ahref="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 <ahref="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>
<p>All of the non-standard variables listed below will return 0 on OpenTTD versions which do not support these features/variables, including standard trunk OpenTTD and older/other patchpack versions.</p>
In addition to SELF and PARENT, switches for vehicle features may use one of the following types below.<br/>
(These are mostly the same as in <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Random_switch">random_switch</a>).<br/>
The 'x' parameter (count x vehicles in given direction) is currently required to be a compile-time constant between 0 and 255.
<table>
<tr><th>Type</th><th>Meaning</th></tr>
<tr><td>BACKWARD_SELF(x)</td><td>Count x vehicles backward (away from the engine), starting at the vehicle itself</td></tr>
<tr><td>FORWARD_SELF(x)</td><td>Count x vehicles forward (towards the engine), starting at the vehicle itself</td></tr>
<tr><td>BACKWARD_ENGINE(x)</td><td>Count x vehicles backward, starting at the leading engine</td></tr>
<tr><td>BACKWARD_SAMEID(x)</td><td>Count x vehicles backward, starting at the first vehicle in the chain with the same ID</td></tr>
</table>
<p>These require the <spanclass="code">more_varaction2_types</span> feature. If this feature is not present, switches of these types will produce a CB_FAILED result.</p>
This callback is called on the primary vehicle to get the name of each part of the ship (e.g. the name of each cargo hold) in the refit window.<br/>
This is not called for ships of only one part.<br/>
The callback handler should return a string or CB_RESULT_NO_TEXT.<br/>
If this callback is not handled or if CB_RESULT_NO_TEXT is returned, a default name is used.<br/>
<spanclass="code">getbits(extra_callback_info1, 0, 8)</span> contains the index of the part of the ship. The first/primary part is 0, each subsequent part increases the value by 1.
<tr><td>enable_restricted_signals</td><td>0 or 1</td>
<td>
Enable restricted signal flag in <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a>.<br/>
When enabled, bit 24 of variable <spanclass="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 <spanclass="code">extra_callback_info2</span> is set.
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 <spanclass="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
This property is intended for objects which are positioned at the edge of a tile, and only require a level edge, not a completely level tile.<br/>
Foundations will only be added as required to get a suitable level edge.<br/>
The format is one mode value per view. If the object has fewer than 4 views then some of the values provided in the property will not be used, and may be 0.
<tr><td>OBJECT_EF_FLAG_INCLINE_FOUNDATION</td><td>Use inclined instead of a flat foundations where possible. (Slopes with one corner raised where the height of the edge is at the maximum height of the tile).</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_CLEAR</td><td>Clear/bare dirt</td><td>If use_land_ground is enabled, the underlying ground type will be used instead</td></tr>
<tr><td>OBJECT_VIEWPORT_MAP_TILE_TYPE_TREES</td><td>Trees</td><td>The specific tree count and ground type/density can be set using map_tile_subtype</td></tr>
<tr><td>lighthouse_generate_amount</td><td>0 .. 255</td><td>Sets the frequency at which lighthouse objects are generated during map generation</td></tr>
<tr><td>transmitter_generate_amount</td><td>0 .. 255</td><td>Sets the frequency at which transmitter objects are generated during map generation</td></tr>
<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 <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.
<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.
This feature allows signal sprites to be specified using switches in a very similar manner to <ahref="https://newgrf-specs.tt-wiki.net/wiki/NML:Railtypes#signals">railtype signals</a> in
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: <spanclass="code">extra_callback_info1</span>, <spanclass="code">extra_callback_info2</span>, and <spanclass="code">terrain_type</span>
are the same as for <ahref="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: <spanclass="code">action3_signals_custom_signal_sprites</span> should be checked using the
<spanclass="code">extended_feature_test</span> function
and if necessary a suitable fallback used or error message shown.<br/>
<br/>
An <spanclass="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.
<tr><td>enable_restricted_signals</td><td>0 or 1</td>
<td>
Enable restricted signal flag.<br/>
When enabled, bit 24 of variable <spanclass="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 <spanclass="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>
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 <spanclass="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
Set which electric signal types may be built using this signal style for the most recently defined style (defined using the <spanclass="code">define_style</span> property).<br/>
At least one of this property and <spanclass="code">style_semaphore_enabled</span> should be set to a non-zero value, as otherwise
no signal types will be enabled for this custom signal style.<br/>
If PROG or NO_ENTRY are set, it is not necessary to also set <spanclass="code">enable_programmable_pre_signals</span> or <spanclass="code">enable_no_entry_signals</span>.
Set which semaphore signal types may be built using this signal style for the most recently defined style (defined using the <spanclass="code">define_style</span> property).<br/>
See <spanclass="code">style_electric_enabled</span>, above.
Set whether reserve through is unconditionally enabled for the most recently defined style (defined using the <spanclass="code">define_style</span> property).
This property only makes a difference when the "limit train lookahead to signal aspect" game setting is enabled.<br/>
This limits the signal aspect which the hypothetical train driver can "read" from the signal without affecting signal aspect propagation to other signals, or variable <spanclass="code">extra_callback_info2</span>.<br/>
<tr><td>style_lookahead_single_signal_only</td><td>0 or 1</td>
<td>
Set the look-ahead to single signal only mode for the most recently defined style (defined using the <spanclass="code">define_style</span> property).<br/>
<tr><td>style_combined_normal_shunt</td><td>0 or 1</td>
<td>
Enable functioning as a combined normal aspect and shunt signal for the most recently defined style (defined using the <spanclass="code">define_style</span> property).<br/>
When enabled and displaying a shunt aspect, the signal state in the lowest byte of <spanclass="code">extra_callback_info2</span> will have the value: 0xFF.
Set whether signals should be drawn on the opposite side of the track for the most recently defined style (defined using the <spanclass="code">define_style</span> property).
<tr><td>style_realistic_braking_only</td><td>0 or 1</td>
<td>
Set whether signals using this style may only be built when realistic braking is enabled, for the most recently defined style (defined using the <spanclass="code">define_style</span> property).
