diff --git a/docs/newgrf-additions-nml.html b/docs/newgrf-additions-nml.html index a4f3f58b56..581990b10e 100644 --- a/docs/newgrf-additions-nml.html +++ b/docs/newgrf-additions-nml.html @@ -30,6 +30,7 @@

Sections

diff --git a/docs/newgrf-additions.html b/docs/newgrf-additions.html index 5729edf4a1..eaf354397f 100644 --- a/docs/newgrf-additions.html +++ b/docs/newgrf-additions.html @@ -30,6 +30,7 @@
@@ -671,6 +672,11 @@

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.

+

In the case where a parent/related scope is used to access a different feature (e.g. the town feature as the parent scope for objects), + the feature ID used here is that associated with the scope where the variable is used.
+ To map a town variable, the feature ID should be the result of mapping the "town" feature name using the feature mapping mechanism, + this is not necessarily the feature ID used directly in the variational action 2.

+

Shift to replace: 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).
@@ -974,6 +980,7 @@ Feature nameDescription road_stopsCustom road stops (bus stops, lorry stops and road waypoints) new_landscapeCustom landscape graphics (currently rocky tiles only) + townTowns (the parent scope for stations, objects, etc.) diff --git a/docs/newgrf-town-nml.html b/docs/newgrf-town-nml.html new file mode 100644 index 0000000000..acce091346 --- /dev/null +++ b/docs/newgrf-town-nml.html @@ -0,0 +1,121 @@ + + + + + JGR's Patchpack - NewGRF Town Feature Additions to NewGRF Specifications in NML + + + +

NewGRF Town Feature Additions to NewGRF Specifications in JGR's Patchpack in NML

+

This document describes the non-standard additions to the town feature in the Official OpenTTD NML Specifications, as implemented in this patchpack, and the associated NML fork

+

This feature allows directly referencing the town feature.
+ Ordinarily this is only accessible as the parent scope for the features: stations, bridges, houses, industries, objects, road stops.

+

This feature may not necessarily match implementations in other patches, branches, etc.
+ This feature as implemented here MAY also be present in other patchpacks.

+ +

The feature identifier is FEAT_TOWN.

+ +

See the NewGRF additions (NML) document for background information on additions to NML.

+ +

See the associated non-NML document for more details on the additions to the NewGRF town feature.

+ +

This feature will be automatically skipped when loaded into a version of OpenTTD which does not support this feature.
+ If this feature is the only significant thing in this GRF, the extended_feature_test(...) function SHOULD be called with the specific feature(s) used and some message, error or other form of + signalling to the user used to inform the user that this version of OpenTTD does not support the feature, if the return value is false.
+ Otherwise the GRF could silently do nothing instead of the expected functionality, creating confusion for end users.

+ +

Sections: +

+ +

Additional Town Variables

+ +

See NML town variables for context.

+ + + + + + + + + + +
NameValue rangeCommentRequires feature
num_houses_uncapped0..4294967295Number of town houses (not clamped to 0xFFFF)town_uncapped_variables, version 1
population_uncapped0..4294967295Town population (not clamped to 0xFFFF)town_uncapped_variables, version 1
town_zone_0_radius_square_uncapped0..4294967295Town zone 0 radius squared (not clamped to 0xFFFF)town_uncapped_variables, version 1
town_zone_1_radius_square_uncapped0..4294967295Town zone 1 radius squared (not clamped to 0xFFFF)town_uncapped_variables, version 1
town_zone_2_radius_square_uncapped0..4294967295Town zone 2 radius squared (not clamped to 0xFFFF)town_uncapped_variables, version 1
town_zone_3_radius_square_uncapped0..4294967295Town zone 3 radius squared (not clamped to 0xFFFF)town_uncapped_variables, version 1
town_zone_4_radius_square_uncapped0..4294967295Town zone 4 radius squared (not clamped to 0xFFFF)town_uncapped_variables, version 1
+ +

Town Generic Callbacks

+ +

Currently only the town_zone callback is defined.
+ This requires the feature: town_zone_callback, version 1. +

+ + 
+	item (FEAT_TOWN, ..., GENERIC_CALLBACK) {
+		graphics {
+			town_zone: ...;
+		}
+	}
+
+ +

This callback is called whenever the zone radii of a town need to be recalculated.
+ This can occur when:
+

+

+ +

The callback is not called if the town zone radii calculations have been manually overriden by settings.

+ +

The return value of the callback is the version of the result format returned by the callback.
+ Currently only version 0 is defined.
+ The callback must store the values of the town zone radii into registers: 0x100 to 0x104, for zones 0 to 4 respectively, using STORE_TEMP. +

+ +

A callback failure result should be returned to use the default town zone radii calculation (or to allow another GRF to handle the callback).

+ +

The num_houses_uncapped variable should be used instead of num_houses, otherwise the results may be incorrect for large towns.
+ Implementers of this callback may assume that the town_uncapped_variables feature is present.

+ +

Syntax example

+

+ 

+grf {
+	...
+}
+
+if (!extended_feature_test("town_zone_callback")) {
+	error(FATAL, string(STR_UNSUPPORTED_VERSION));
+}
+
+switch (FEAT_TOWN, SELF, town_zone_cb,
+		[
+			STORE_TEMP(num_houses_uncapped * (is_city ? 32 : 16), 0x100),
+			STORE_TEMP((num_houses_uncapped >> 3) * 9, 0x101),
+			STORE_TEMP(0, 0x102),
+			STORE_TEMP((num_houses_uncapped >> 3) * 5, 0x103),
+			STORE_TEMP((num_houses_uncapped >> 3) * 3, 0x104)
+		]) {
+	return 0;
+}
+
+item (FEAT_TOWN, town_cb, GENERIC_CALLBACK) {
+	graphics {
+		town_zone: town_zone_cb;
+	}
+}
+
+

+ + diff --git a/docs/newgrf-town.html b/docs/newgrf-town.html new file mode 100644 index 0000000000..10c5f948f7 --- /dev/null +++ b/docs/newgrf-town.html @@ -0,0 +1,113 @@ + + + + + JGR's Patchpack - NewGRF Town Feature Additions to NewGRF Specifications + + + +

NewGRF Town Feature Additions to NewGRF Specifications in JGR's Patchpack

+

This document describes the non-standard additions to the town feature in the Official OpenTTD NewGRF Specifications, as implemented in this patchpack.

+ +

The town feature is ordinarily only accessible via the parent scope from the features: stations, bridges, houses, industries, objects, road stops.

+

Mapping a feature ID to the town feature allows referencing it directly, this is useful for:
+

+

+ +

NewGRFs which use this feature MUST use the feature ID mapping mechanism to map the town feature to a local feature ID.

+

This feature is indicated by the feature name: town_feature, version 1.
+ The feature name to use for feature ID mapping is town.
+ +

This feature may not necessarily match implementations in other patches, branches, etc.
+ This feature as implemented here MAY also be present in other patchpacks.

+

See the NewGRF additions document for background information on additions to the NewGRF specifications.

+ +

The functionality listed below is also supported in a fork of NML, see the associated NML town feature and NML additions documents for more details.

+ +

Actions:

+

+ +

Variational Action 2 - Town

+ + Note: non-variational action 2 sprites should ONLY be used to implement the return callback failure pattern. + +

See the Variational Action 2 Specification for background information.

+ + Variables: + + + + + + + + + +
Mappable nameDescription
town_house_countNumber of town houses
town_populationTown population
town_zone_0_radius_squareTown zone 0 radius squared
town_zone_1_radius_squareTown zone 1 radius squared
town_zone_2_radius_squareTown zone 2 radius squared
town_zone_3_radius_squareTown zone 3 radius squared
town_zone_4_radius_squareTown zone 4 radius squared
+ +

Number of town house (mappable variable: town_house_count)

+

This is the same as town variable B6, except 32 bits and not clamped to a maximum value of 0xFFFF.

+

This requires town_uncapped_variables, version 1.

+ +

Town population (mappable variable: town_population)

+

This is the same as town variable 82, except 32 bits and not clamped to a maximum value of 0xFFFF.

+

This requires town_uncapped_variables, version 1.

+ +

Town zone [0 .. 4] radius squared (mappable variable: town_zone_0_radius_square, town_zone_1_radius_square, town_zone_2_radius_square, town_zone_3_radius_square, town_zone_4_radius_square)

+

This is the same as town variables 94, 96, 98, 9A, 9C, except 32 bits and not clamped to a maximum value of 0xFFFF.

+

This requires town_uncapped_variables, version 1.

+ +
+ +

Action 3 - Town

+ +

See the Action 3 Specification for background information.

+ +

Only generic callbacks are supported, the "number of IDs" field in the action 3 must be set to 0.

+ +

The variational action 2 sprite group referenced must be a callback handler which properly branches on the value of callback variable 0C.

+ +

The following callbacks are defined:

+ + + + +
Callback IDPurposeEnabled if
0xEC008001Custom town zone radiiThe town_zone_callback feature is tested for
+ +

Town zone radii callback 0xEC008001:

+ +

The town_zone_callback feature must be tested for to enable this generic callback.

+ +

This callback is called whenever the zone radii of a town need to be recalculated.
+ This can occur when:
+

+

+ +

The callback is not called if the town zone radii calculations have been manually overriden by settings.

+ +

The return value of the callback is the version of the result format returned by the callback.
+ Currently only version 0 is defined.
+ The callback must store the values of the town zone radii into registers: 0x100 to 0x104, for zones 0 to 4 respectively. +

+ +

A callback failure result should be returned to use the default town zone radii calculation (or to allow another GRF to handle the callback).

+ +

The town_house_count variable should be used instead of variable B6, otherwise the results may be incorrect for large towns.
+ Implementers of this callback may assume that the town_uncapped_variables feature is present.

+ +