From 15955bc2790159754c96f32a36f19fd49bf8201b Mon Sep 17 00:00:00 2001 From: Jonathan G Rennison Date: Mon, 24 Jan 2022 02:00:50 +0000 Subject: [PATCH] Documentation: Initial NFO docs on variable remapping --- docs/newgrf-additions.html | 59 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/docs/newgrf-additions.html b/docs/newgrf-additions.html index 9e526e282c..c5f607f096 100644 --- a/docs/newgrf-additions.html +++ b/docs/newgrf-additions.html @@ -402,11 +402,70 @@ The property length is 1 byte. 0 is disabled (default). 1 is enabled.

This is indicated by the feature name: action0_object_flood_resistant, version 1


+

Action 14 - Variable Mapping for Variational Action 2

+

See Action 14 Specification and Variational Action 2 Specification for background information.

+

The variable mapping mechanism has the feature name: variable_mapping, this document describes version 1.

+

Unlike property mappings, it is not necessary to perform a feature test or check a mapping success variable before using a mapped variable.

+

Remapped variables are accessed by reading from variable 0x11 using a varadjust shift-num and and-mask which exactly matches that specified in the variable mapping.
+ In the absence of any successful variable mapping, variable 0x11 has all bits set to 0 and attempting to read from it with any shift-num and and-mask value + results in a value of 0 without producing an error.

+

Reading a mapped variable on a version of OpenTTD which does not support this variable mapping mechanism or which does not support the requested variable, returns a value of 0.

+

If more than one variable mapping is made for the same combination of feature ID, shift-num and and-mask, it is implementation-defined which mapping is used.
+ Each variable mapping SHOULD use a unique combination of feature ID, shift-num and and-mask.

+

Variable Mapping: C "A2VM"

+

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

+

Unknown Action 14 blocks are ignored, and do not need to be skipped.

+

+

Property Name: C "A2VM" -> T "NAME"

+

Within an A2VM chunk, the NAME text (type T) field contains the name of the variable to map. The value of the language ID byte is ignored.

+

Action 0 Feature ID: C "A2VM" -> B "FEAT"

+

Within an A2VM chunk, the FEAT binary (type B) field contains the Variational Action 2 feature ID. This is 1 byte.

+

Property ID: C "A2VM" -> B "RSFT"

+

Within an A2VM chunk, the RSFT binary (type B) field contains the Variational Action 2 varadjust shift-num value to look for. This is 1 byte.
+ The shift-num value must be < 32 (0x20).
+ If this is not specified, a value of 0 is assumed.

+

Property ID: C "A2VM" -> B "RMSK"

+

Within an A2VM chunk, the RMSK binary (type B) field contains the Variational Action 2 varadjust and-mask value to look for. This is 4 bytes.
+ When using byte or word sized variational action 2s, the and-mask is zero-extended to 32 bits before comparing with this value.
+ If this is not specified, a value of 0 is assumed.

+

Property ID: C "A2VM" -> B "VSFT"

+

Within an A2VM chunk, the VSFT binary (type B) field contains the replacement Variational Action 2 varadjust shift-num value to use on the mapped variable. This is 1 byte.
+ The shift-num value must be < 32 (0x20).
+ If this is not specified, a value of 0 is assumed.

+

Property ID: C "A2VM" -> B "VMSK"

+

Within an A2VM chunk, the RMSK binary (type B) field contains the replacement Variational Action 2 varadjust and-mask value to use on the mapped variable. This is 4 bytes.
+ If this is not specified, a value of 0 is assumed.

+

Success Indicator Global Variable 0x8D Bit: C "A2VM" -> B "SETT"

+

This behaves identically to the C "A0PM" -> B "SETT" case, above

+

Example NFO:

+ 
+// Map station variable "sample_station_variable" with a shift-num of 4 and an and-mask of 0xFF, to reads of variable 0x11 with a shift-num of 1 and an and-mask of 0x2, and set bit 4 of global variable 0x8D if successful
+-1 * -1 14
+	"C" "A2VM"
+		"T" "NAME" 00 "sample_station_variable" 00
+		"B" "FEAT" \w1 04
+		"B" "RSFT" \w1 1
+		"B" "RMSK" \w4 \dx00000002
+		"B" "VSFT" \w1 4
+		"B" "VMSK" \w4 \dx000000FF
+		"B" "SETT" \w1 4
+		00
+	00
+....
+ -1 * 15       02 04 03 81        // Action2, Feature 04 (stations), action2ID 03, 1-byte variable
+                   11 01 02       // variable 11 (remapping variable or 0), shift 01, mask 0x02 (these exactly match the remapping above)
+                                  // This is remapped to ‐‐> sample_station_variable with a shift of 04 and a mask of 0xFF
+                   01             // check one range
+                   02 00    00 04 // range 00 - 04: link to action2ID 02
+                   01 00          // default:       link to action2ID 01
+

Variational Action 2 - Stations

Track type in purchase list (42)

This is indicated by the feature name: varaction2_station_var42, version 1


+

Action 3 - Signals (Feature 0E)

Note that Action 3 feature 0E is not supported (does nothing) in standard OpenTTD.

This implementation of feature 0E is not the same as that in TTDPatch.