From 2dda1c43512e6d71096041fdd8f892d56ca20883 Mon Sep 17 00:00:00 2001 From: Jonathan G Rennison Date: Sat, 10 Nov 2018 12:49:44 +0000 Subject: [PATCH] Documentation: Add docs on NewGRF spec additions --- docs/newgrf-additions.html | 73 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/newgrf-additions.html diff --git a/docs/newgrf-additions.html b/docs/newgrf-additions.html new file mode 100644 index 0000000000..648f9bfcac --- /dev/null +++ b/docs/newgrf-additions.html @@ -0,0 +1,73 @@ + + + + + Additions to NewGRF Specifications + + + +

Additions to NewGRF Specifications in thi branch

+

This document describes non-standard additions to the Official OpenTTD NewGRF Specifications which are present in this branch. +

This additions MAY also be present in other branches/repositories/etc. They MAY be removed or moved in future, if necessary.

+

NewGRFs which use any of these features SHOULD use the feature testing mechanism described below to check whether individual added features are supported.

+ +

Action 14 - Feature Tests

+

See Action 14 Specification for background information.

+

Feature Test: C "FTST"

+

Each FTST chunk (type C) describes an individual feature test.
+ Sub-chunks within each FTST chunk may appear in any order, however each sub-chunk SHOULD only appear ONCE within an individual FTST chunk.

+

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.

+

Feature Name: C "FTST" -> T "NAME"

+

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.
+ If the named feature is not present, or if this field is omitted, the version is 0.
+ If the named feature is present, the version number will be at least 1.

+

The feature testing mechanism itself has the feature name: feature_test, this document describes version 1.

+

Feature Minimum Version: C "FTST" -> B "MINV"

+

Within an FTST chunk, the MINV binary (type B) field contains the minimum (inclusive) (≥) version to accept. This is a Word (2 bytes).
+ The default value is 1.

+

Feature Maximum Version: C "FTST" -> B "MAXV"

+

Within an FTST chunk, the MINV binary (type B) field contains the maximum (inclusive) (≤) version to accept. This is a Word (2 bytes).
+ The default value is 0xFFFF (no maximum).

+

Feature Set Global Variable 0x9D Bit: C "FTST" -> B "SETP"

+

Within an FTST chunk, the SETP binary (type B) field contains the bit number to set/clear in + global variable 0x9D (TTD Platform) to store the result of the test. This is 1 byte.
+ If the test is successful, the bit is set (to 1), otherwise the bit is cleared (to 0).
+ 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.
+ Global variable 0x9D can then be tested by using a standard Action 7 or 9, or a standard Variational Action 2.
+ If this field is omitted, no bit is set or cleared, and the test is not observable. +

+
+

Example:

+ 
+// 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
+
+ +