Additions to NewGRF Specifications in JGR's Patchpack in NML

This document describes non-standard additions to the Official OpenTTD NML Specifications which are present in this patchpack and the associated NML fork.

These additions MAY also be present in other patchpacks. They MAY be removed or moved in future, if necessary.

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.
See the associated non-NML document for more details.

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.

All of the non-standard variables listed below will return 0 on OpenTTD versions which do not support these features/variables, including standard trunk OpenTTD and older/other patchpack versions.

Features with separate pages

• Road stops (FEAT_ROADSTOPS)
• New landscape (FEAT_NEWLANDSCAPE)
• Towns (the parent scope for stations, objects, etc.) (FEAT_TOWN)

Sections

• Builtin functions
• Additional switch types
• Ship callbacks
• House variables
• Railtype properties
• Railtype variables
• Roadtype properties
• Tramtype properties
• Object IDs
• Object properties
• Object variables
• Airport tile variables
• Global variables properties
• Replace new sprites
• Signal graphics using switches

Builtin functions

extended_feature_test(feature_name[, min_version[, max_version]])

Additional switch types

In addition to SELF and PARENT, switches for vehicle features may use one of the following types below.
(These are mostly the same as in random_switch).
The 'x' parameter (count x vehicles in given direction) is currently required to be a compile-time constant between 0 and 255.

These require the more_varaction2_types feature. If this feature is not present, switches of these types will produce a CB_FAILED result.

Ship callbacks

The articulated_part callback is also available for ships.
Additional ship parts are not used for graphics, they are only used for additional cargo capacity, the default graphics chain is unused.
The default graphics chain for the primary vehicle may check the cargo states of the other ship parts if required.
Additional ship parts may be refitted individually.

This requires the multi_part_ships feature.

From version 3 of the multi_part_ships feature, spritegroup loading/loaded cargo thresholds refer to the entire ship, not just the first vehicle.

Added callback: refit_part_name
This callback is called on the primary vehicle to get the name of each part of the ship (e.g. the name of each cargo hold) in the refit window.
This is not called for ships of only one part.
The callback handler should return a string or CB_RESULT_NO_TEXT.
If this callback is not handled or if CB_RESULT_NO_TEXT is returned, a default name is used.
getbits(extra_callback_info1, 0, 8) contains the index of the part of the ship. The first/primary part is 0, each subsequent part increases the value by 1.

House variables

Variables in the table below which are not supported by the version of OpenTTD being used return a value of 0.

Railtype properties

Railtype variables

Variables in the table below which are not supported by the version of OpenTTD being used return a value of 0.

Roadtype properties

Tramtype properties

Object IDs

Object IDs are NewGRF-local and can be freely chosen in the 0..63999 range, as of the more_objects_per_grf feature.
When loaded into a version of OpenTTD without this feature, IDs are limited to the range: 0..254. Any objects with IDs outside this range will be skipped.

Object properties

Object variables

Variables in the table below which are not supported by the version of OpenTTD being used return a value of 0.

Airport tile variables

Variables in the table below which are not supported by the version of OpenTTD being used return a value of 0.

Global variables properties

The variables listed below should set inside an item and property block of the form:

item (FEAT_GLOBALVARS) {
	property {
		...
	}
}

Syntax example:

item (FEAT_GLOBALVARS) {
	property {
		lighthouse_generate_amount: 255;
		transmitter_generate_amount: 0;
		extra_station_name: [string(STR_STATION_NAME1), bitmask(EXTRA_STATION_NAME_FLAG_RAIL)];
		extra_station_name: [string(STR_STATION_NAME2), bitmask(EXTRA_STATION_NAME_FLAG_ROAD, EXTRA_STATION_NAME_FLAG_TOWN_CENTRE_ONLY)];
	}
}
		

Replace new sprites

Signal graphics using switches

This feature allows signal sprites to be specified using switches in a very similar manner to railtype signals in item (FEAT_RAILTYPES) { graphics { signals: ... } } blocks.
However this applies to all signals, not only those of a particular rail type.
Railtype signal graphics have a higher priority than general signal graphics as set here.

Variables: extra_callback_info1, extra_callback_info2, and terrain_type are the same as for railtype signals.

This feature is not supported by standard OpenTTD or by standard NML.
If the use of this feature is not optional, the feature name: action3_signals_custom_signal_sprites should be checked using the extended_feature_test function and if necessary a suitable fallback used or error message shown.

An item (FEAT_SIGNALS, custom_signals, 0) { } block should be used to define properties and graphics.
The graphics block should contain a single default switch.

Custom signal sprites example:

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;
	}
}