mirror of
https://github.com/JGRennison/OpenTTD-patches.git
synced 2024-10-31 15:20:10 +00:00
264 lines
18 KiB
HTML
264 lines
18 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</title>
|
|
<style type="text/css">
|
|
span.abuse { font-family: "Courier New", Courier, mono; background-color: rgb(255, 58, 31); }
|
|
span.option{ font-family: "Courier New", Courier, mono; background-color: rgb(255,255, 30); }
|
|
span.free { font-family: "Courier New", Courier, mono; background-color: rgb(30, 178, 54); }
|
|
span.used { font-family: "Courier New", Courier, mono; }
|
|
span.used_p{ font-family: "Courier New", Courier, mono; background-color: cyan; }
|
|
td.bits { white-space: nowrap; text-align: center; font-family: "Courier New", Courier, mono; }
|
|
td.caption { white-space: nowrap; text-align: left; }
|
|
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; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<h2>Additions to NewGRF Specifications in JGR's Patchpack</h2>
|
|
<p>This document describes non-standard additions to the <a href="https://newgrf-specs.tt-wiki.net/wiki/Main_Page">Official OpenTTD NewGRF Specifications</a> which are present in this patchpack.
|
|
<p>These additions MAY also be present in other patchpacks. They MAY be removed or moved in future, if necessary.</p>
|
|
<p>NewGRFs which use any of these features SHOULD use the <a href="#feature-test">feature testing</a> mechanism described below to check whether individual added features are supported.</p>
|
|
|
|
<h3 id="feature-test">Action 14 - Feature Tests</h3>
|
|
<p>See <a href="https://newgrf-specs.tt-wiki.net/wiki/Action14">Action 14 Specification</a> for background information.</p>
|
|
<h4>Feature Test: C "FTST"</h4>
|
|
<p>Each FTST chunk (type C) describes an individual feature test.<br />
|
|
Sub-chunks within each FTST chunk may appear in any order, however each sub-chunk SHOULD only appear ONCE within an individual FTST chunk.</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>
|
|
<h4>Feature Name: C "FTST" -> T "NAME"</h4>
|
|
<p>Within an FTST chunk, the NAME text (type T) field contains the name of the feature to test for. The value of the language ID byte is ignored.<br />
|
|
If the named feature is not present, or if this field is omitted, the version is 0.<br />
|
|
If the named feature is present, the version number will be at least 1.</p>
|
|
<p>The feature testing mechanism itself has the feature name: <font face="monospace">feature_test</font>, this document describes version 1.</p>
|
|
<h4>Feature Minimum Version: C "FTST" -> B "MINV"</h4>
|
|
<p>Within an FTST chunk, the MINV binary (type B) field contains the minimum (inclusive) (≥) version to accept. This is a Word (2 bytes).<br />
|
|
The default value is 1.</p>
|
|
<h4>Feature Maximum Version: C "FTST" -> B "MAXV"</h4>
|
|
<p>Within an FTST chunk, the MAXV binary (type B) field contains the maximum (inclusive) (≤) version to accept. This is a Word (2 bytes).<br />
|
|
The default value is 0xFFFF (no maximum).</p>
|
|
<h4>Feature Set Global Variable 0x9D Bit: C "FTST" -> B "SETP"</h4>
|
|
<p>Within an FTST chunk, the SETP binary (type B) field contains the bit number to set/clear in
|
|
<a href="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 <a href="https://newgrf-specs.tt-wiki.net/wiki/Action7">Action 7 or 9</a>, or a standard <a href="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>
|
|
<br />
|
|
<h4>Example NFO:</h4>
|
|
<pre>
|
|
// Set bit 4 of global variable 0x9D if sample_feature_1 is present with a version of at least 4
|
|
// Set bit 5 of global variable 0x9D if sample_feature_2 is present with a version of at least 5 and at most 6
|
|
-1 * -1 14
|
|
"C" "FTST"
|
|
"T" "NAME" 00 "sample_feature_1" 00
|
|
"B" "MINV" \w2 \w4
|
|
"B" "SETP" \w1 04
|
|
00
|
|
"C" "FTST"
|
|
"T" "NAME" 00 "sample_feature_2" 00
|
|
"B" "MINV" \w2 \w5
|
|
"B" "MAXV" \w2 \w6
|
|
"B" "SETP" \w1 05
|
|
00
|
|
00
|
|
....
|
|
// Skip 1 sprite if bit 4 of global variable 0x9D is not set (indicating that sample_feature_1 with a version of at least 4 is NOT present)
|
|
-1 * -1 07 9D 01 \70 04 01
|
|
</pre>
|
|
<br />
|
|
<h3 id="property-mapping">Action 14 - Property Mapping for Action 0</h3>
|
|
<p>See <a href="https://newgrf-specs.tt-wiki.net/wiki/Action14">Action 14 Specification</a> and <a href="https://newgrf-specs.tt-wiki.net/wiki/Action0">Action 0 Specification</a> for background information.</p>
|
|
<p>The property mapping mechanism has the feature name: <font face="monospace">property_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>
|
|
<h4>Property Mapping: C "A0PM"</h4>
|
|
<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 <font face="monospace">property_mapping</font> is checked for.</li>
|
|
</ul>
|
|
Unknown Action 14 blocks are ignored, and do not need to be skipped.</p>
|
|
<h4>Property Name: C "A0PM" -> T "NAME"</h4>
|
|
<p>Within an A0PM chunk, the NAME text (type T) field contains the name of the property to map. The value of the language ID byte is ignored.</p>
|
|
<h4>Action 0 Feature ID: C "A0PM" -> B "FEAT"</h4>
|
|
<p>Within an A0PM chunk, the FEAT binary (type B) field contains the <a href="https://newgrf-specs.tt-wiki.net/wiki/Action0#Feature">Action 0 feature ID</a>. This is 1 byte.</p>
|
|
<h4>Property ID: C "A0PM" -> B "PROP"</h4>
|
|
<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>
|
|
<h4 id="SETT">Success Indicator Global Variable 0x8D Bit: C "A0PM" -> B "SETT"</h4>
|
|
<p>Within an A0PM chunk, the SETT binary (type B) field contains the bit number to set/clear in
|
|
<a href="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 <a href="https://newgrf-specs.tt-wiki.net/wiki/Action7">Action 7 or 9</a>, or a standard <a href="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>
|
|
<h4 id="FLBK">Fallback Mode: C "A0PM" -> B "FLBK"</h4>
|
|
<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.
|
|
</p>
|
|
<h4>Format of remapped properties</h4>
|
|
All properties which are mapped by this mechanism have the format:
|
|
<table>
|
|
<tr><th>Size</th><th>Name</th><th>Meaning</th></tr>
|
|
<tr><td>B*</td><td>num</td><td>Size of the data in bytes</td></tr>
|
|
<tr><td>V</td><td>data</td><td>Property data</td></tr>
|
|
</table>
|
|
Note that num is an extended byte, see <a href="https://newgrf-specs.tt-wiki.net/wiki/GRFActionsDetailed">GRFActionsDetailed</a>.<br />
|
|
If the size of the data does provided is not valid for the given property, the attempt to set the property MAY be ignored or partially applied.<br />
|
|
Note that each use of the mapped property ID is followed by Num-info iterations of the size and data pair above. See: <a href="https://newgrf-specs.tt-wiki.net/wiki/Action0">Action 0 Specification</a>.
|
|
<h4>Example NFO:</h4>
|
|
<pre>
|
|
// Map station property "sample_station_property" to property id 0xF8, and set bit 4 of global variable 0x8D if successful
|
|
-1 * -1 14
|
|
"C" "A0PM"
|
|
"T" "NAME" 00 "sample_station_property" 00
|
|
"B" "FEAT" \w1 04
|
|
"B" "PROP" \w1 F8
|
|
"B" "SETT" \w1 4
|
|
00
|
|
00
|
|
....
|
|
// Skip 1 sprite if bit 4 of global variable 0x8D is not set (indicating that station property sample_station_property is NOT present)
|
|
-1 * -1 07 8D 01 \70 04 01
|
|
// Set sample_station_property for station ID 10 to 2 byte value: AB CD
|
|
-1 * -1 00 04 01 01 10 F8 02 AB CD
|
|
</pre>
|
|
<br />
|
|
|
|
<h3><a href="https://newgrf-specs.tt-wiki.net/wiki/Action0/Stations">Action 0 - Stations</a></h3>
|
|
<h4><a href="https://newgrf-specs.tt-wiki.net/wiki/Action0/Stations#Minimum_bridge_height_.281B.29">Minimum bridge height (1B, or mappable property: station_min_bridge_height)</a></h4>
|
|
<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.
|
|
</p>
|
|
<p>This is indicated by the feature name: <font face="monospace">action0_station_prop1B</font>, version 1</p>
|
|
<h4>Disallowed bridge pillars (mappable property: station_disallowed_bridge_pillars)</h4>
|
|
<p>This property describes which bridge pillars are not allowed on the station tile.<br />
|
|
It consists of 8 pillar flags, for each of the 8 station layouts.<br />
|
|
Each set of flags is 1 byte, the total property length is 8 bytes.<br />
|
|
Each set of flags has the format described in the bridge_pillar_flags property section, below.
|
|
</p>
|
|
<p>This is indicated by the feature name: <font face="monospace">action0_station_disallowed_bridge_pillars</font>, version 1</p>
|
|
|
|
<br />
|
|
The 8 station layouts are described below.
|
|
<table>
|
|
<tr><th>Station layout</th><th>Axis</th><th>Default Appearance</th></tr>
|
|
<tr><td>0</td><td>X</td><td>plain platform</td></tr>
|
|
<tr><td>1</td><td>Y</td><td>plain platform</td></tr>
|
|
<tr><td>2</td><td>X</td><td>platform with building</td></tr>
|
|
<tr><td>3</td><td>Y</td><td>platform with building</td></tr>
|
|
<tr><td>4</td><td>X</td><td>platform with roof, left side</td></tr>
|
|
<tr><td>5</td><td>Y</td><td>platform with roof, left side</td></tr>
|
|
<tr><td>6</td><td>X</td><td>platform with roof, right side</td></tr>
|
|
<tr><td>7</td><td>Y</td><td>platform with roof, right side</td></tr>
|
|
</table>
|
|
<br />
|
|
|
|
<h3><a href="https://newgrf-specs.tt-wiki.net/wiki/Action0/Bridges">Action 0 - Bridges</a></h3>
|
|
<h4>Menu icons (14, or mappable property: bridge_menu_icon)</h4>
|
|
<p>This property sets the GUI menu icon for bridge type, this is displayed when constructing a bridge<br />
|
|
This has the format:
|
|
<table>
|
|
<tr><th>Size</th><th>Field</th><th>Description</th></tr>
|
|
<tr><td>W</td><td>Sprite</td><td>Sprite ID</td></tr>
|
|
<tr><td>W</td><td>Recolour</td><td>Recolour sprite/value</td></tr>
|
|
</table>
|
|
The total property length is 4 bytes.
|
|
</p>
|
|
<p>This is indicated by the feature name: <font face="monospace">action0_bridge_prop14</font>, version 1</p>
|
|
<h4>Bridge pillars (mappable property: bridge_pillar_flags)</h4>
|
|
<p>This property describes the pillars present for each bridge sprite table.<br />
|
|
It consists of 6 pairs of pillar flags, for bridge sprite tables 0 - 5.<br />
|
|
Each pair consists of: X direction flags, Y direction flags<br />
|
|
Each set of flags is 1 byte, the total property length is 12 bytes.<br />
|
|
Each set of flags has the format:
|
|
<table>
|
|
<tr><th>Bit</th><th>Value</th><th>Meaning</th></tr>
|
|
<tr><td>0</td><td>1</td><td>Pillar is present in west corner</td></tr>
|
|
<tr><td>1</td><td>2</td><td>Pillar is present in south corner</td></tr>
|
|
<tr><td>2</td><td>4</td><td>Pillar is present in east corner</td></tr>
|
|
<tr><td>3</td><td>8</td><td>Pillar is present in north corner</td></tr>
|
|
<tr><td>4</td><td>10</td><td>Pillar is present along entire north-east edge</td></tr>
|
|
<tr><td>5</td><td>20</td><td>Pillar is present along entire south-east edge</td></tr>
|
|
<tr><td>6</td><td>40</td><td>Pillar is present along entire south-west edge</td></tr>
|
|
<tr><td>7</td><td>80</td><td>Pillar is present along entire north-west edge</td></tr>
|
|
</table>
|
|
</p>
|
|
<p>This is indicated by the feature name: <font face="monospace">action0_bridge_pillar_flags</font>, version 1</p>
|
|
<h4>More bridges (16 instead of 13)</h4>
|
|
<p>This is indicated by the feature name: <font face="monospace">more_bridge_types</font>, version 1</p>
|
|
<h3><a href="https://newgrf-specs.tt-wiki.net/wiki/VariationalAction2/Stations">Variational Action 2 - Stations</a></h3>
|
|
<h4>Track type in purchase list (42)</h4>
|
|
<p>This is indicated by the feature name: <font face="monospace">varaction2_station_var42</font>, version 1</p>
|
|
<br />
|
|
<h3 id="feature-test">Action 14 - Type ID Mapping for Action 5</h3>
|
|
<p>See <a href="https://newgrf-specs.tt-wiki.net/wiki/Action14">Action 14 Specification</a> and <a href="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: <font face="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>
|
|
<h4>Action 5 type ID Mapping: C "A5TM"</h4>
|
|
<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 <font face="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>
|
|
<h4>Property Name: C "A5TM" -> T "NAME"</h4>
|
|
<p>Within an A5TM chunk, the NAME text (type T) field contains the name of the type to map. The value of the language ID byte is ignored.</p>
|
|
<h4>Property ID: C "A5TM" -> B "TYPE"</h4>
|
|
<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>
|
|
<h4>Success Indicator Global Variable 0x8D Bit: C "A5TM" -> B "SETT"</h4>
|
|
<p>This behaves identically to the <a href="#SETT">C "A0PM" -> B "SETT"</a> case, above</p>
|
|
<h4>Fallback Mode: C "A5TM" -> B "FLBK"</h4>
|
|
<p>This behaves identically to the <a href="#FLBK">C "A0PM" -> B "FLBK"</a> case, above</p>
|
|
<h4>Example NFO:</h4>
|
|
<pre>
|
|
// Map action5 type "sample_action5_type" to type id 0x70, and set bit 5 of global variable 0x8D if successful
|
|
-1 * -1 14
|
|
"C" "A5TM"
|
|
"T" "NAME" 00 "sample_action5_type" 00
|
|
"B" "TYPE" \w1 70
|
|
"B" "SETT" \w1 5
|
|
00
|
|
00
|
|
....
|
|
// Skip 3 sprites if bit 5 of global variable 0x8D is not set (indicating that station property sample_action5_type is NOT present)
|
|
-1 * -1 07 8D 01 \70 05 03
|
|
// Set 2 sprites at offset 7 into sample_action5_type
|
|
-1 * -1 05 F0 02 07
|
|
-1 sprites/sample.png 546 8 09 23 33 -26 0
|
|
-1 sprites/sample.png 594 8 09 23 33 -5 0
|
|
</pre>
|
|
<h4>Programmable signal graphics (mappable type: programmable_signals)</h4>
|
|
<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 signals</td></tr>
|
|
<tr><td>1</td><td>Lighted programmable signals</td></tr>
|
|
</table>
|
|
</p>
|
|
<p>This is indicated by the feature name: <font face="monospace">action5_programmable_signals</font>, version 1</p>
|
|
</body>
|
|
</html>
|