Archives/OpenTTD-patches
2
0
Fork 0
mirror of https://github.com/JGRennison/OpenTTD-patches.git synced 2024-11-11 13:10:45 +00:00
Code Issues Packages Projects Releases Wiki Activity
c4e3c2cd75
OpenTTD-patches/docs/newgrf-additions-nml.html

254 lines
12 KiB
HTML
Raw Normal View History

Documentation: Add NML documentation for non-standard NewGRF features
2020-10-19 18:43:57 +00:00
<!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; }
DocumentationL Update NML additions
2021-08-23 01:26:07 +00:00
pre.code { font-family: "Courier New", Courier, mono; color: blue; background-color: #f8f9fa; border: 1px solid #eaecf0; padding: 1em; }
Documentation: Add NML documentation for non-standard NewGRF features
2020-10-19 18:43:57 +00:00
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>
DocumentationL Update NML additions
2021-08-23 01:26:07 +00:00
<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>
Documentation: Add NML documentation for non-standard NewGRF features
2020-10-19 18:43:57 +00:00
<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>
Add new signal type: no-entry signal 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.
2021-09-04 02:14:09 +00:00
<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>
Documentation: Add NML documentation for non-standard NewGRF features
2020-10-19 18:43:57 +00:00
<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>
DocumentationL Update NML additions
2021-08-23 01:26:07 +00:00
<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>
Add implementation of multi-aspect signalling and GRF support Requires realistic braking See: #247
2021-08-28 11:51:06 +00:00
<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>
Add NewGRF railtype flag to disable realistic braking for vehs of that type See: #242
2021-04-15 19:19:04 +00:00
<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>
Documentation: Add NML documentation for non-standard NewGRF features
2020-10-19 18:43:57 +00:00
</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>
Add new signal type: no-entry signal 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.
2021-09-04 02:14:09 +00:00
<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>
Documentation: Add NML documentation for non-standard NewGRF features
2020-10-19 18:43:57 +00:00
</table>
DocumentationL Update NML additions
2021-08-23 01:26:07 +00:00
<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>
Add new signal type: no-entry signal 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.
2021-09-04 02:14:09 +00:00
<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>
DocumentationL Update NML additions
2021-08-23 01:26:07 +00:00
<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>
Add implementation of multi-aspect signalling and GRF support Requires realistic braking See: #247
2021-08-28 11:51:06 +00:00
<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>
DocumentationL Update NML additions
2021-08-23 01:26:07 +00:00
</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>
Documentation: Add NML documentation for non-standard NewGRF features
2020-10-19 18:43:57 +00:00
</body>
</html>
Reference in New Issue Copy Permalink