# JGR's Patchpack - Additions to NewGRF Specifications (NML)

## 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.

### Builtin functions

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

This returns true if the given extended feature is present and has a version within the specified minimum and maximum (inclusive).
This function should only be used after the grf{} block.
In most cases it is not necessary to use this function, as extended properties (listed below) which are not supported are simply skipped/ignored.

### Railtypes properties

Property | Value range | Comment
--- | --- | ---
enable_programmable_pre_signals | 0 or 1 | Enable programmable pre-signal graphics in railtype signals. Programmable pre-signals have a signal type (getbits(extra_callback_info2, 16, 8)) of 6.
enable_no_entry_signals | 0 or 1 | Enable no-entry signal graphics in railtype signals. No-entry signals have a signal type (getbits(extra_callback_info2, 16, 8)) of 7. No-entry signals always have a signal state of red.

enable_restricted_signals

0 or 1

Enable restricted signal flag in railtype signals.
When enabled, bit 24 of variable extra_callback_info2 is set if the signal is restricted (has a routing restriction program attached).
When enabled, the "Show restricted electric signals using default graphics" client setting and signal post recolouring is not applied.
This flag must only be set if a different sprite is returned when bit 24 of extra_callback_info2 is set.

enable_signal_recolour

0 or 1

Enable recolouring of graphics in railtype signals.
When enabled, in addition to returning a sprite, register 0x100 may be set to the following using STORE_TEMP:

Bits | Meaning
--- | ---
0 - 23 | Recolour sprite to use. Set to 0 for no recolouring.
24 - 31 | Reserved, set to zero.

If recolouring is not optional, the feature name: action0_railtype_recolour should be checked using the extended_feature_test function and if necessary a suitable fallback used or error message shown.
If the OpenTTD version does not support this property/feature, then the property would ordinarily be ignored/skipped and no recolouring would be done.

extra_aspects

0 - 6

The value is the number of additional signal aspects to use (e.g. 4-aspect signalling should use a value of 2).
When set, the lowest byte of extra_callback_info2 (signal state) may have the given number of additional values starting from 02:

Value | Meaning
--- | ---
00 | Red signal
01 | Green signal
02 | 1st extra aspect (e.g. yellow)
03 | 2nd extra aspect (e.g. double yellow)
... | Further extra aspects...

The provided value is currently clamped to be within the range 0 - 6 (inclusive).
N.B. Realistic braking must be enabled for additional signal aspects to be used

disable_realistic_braking | 0 or 1 | When this property is set realistic braking is disabled for trains of this railtype even when realistic braking is otherwise in effect.

### Roadtype properties

Property | Value range | Comment
--- | --- | ---

roadtype_extra_flags

bitmask(ROADTYPE_EXTRA_FLAG_XXX, ...)

NO_SCRIPT_BUILD
  Scripts (AI/GS) may not build this roadtype
NO_TOWN_MODIFY
  Towns may not modify tiles of this roadtype in any way whatsoever

### Tramtype properties

Property | Value range | Comment
--- | --- | ---

tramtype_extra_flags

bitmask(TRAMTYPE_EXTRA_FLAG_XXX, ...)

NO_SCRIPT_BUILD
  Scripts (AI/GS) may not build this tramtype
NO_TOWN_MODIFY
  Towns may not modify tiles of this tramtype in any way whatsoever

### Object properties

Property | Value range | Comment
--- | --- | ---
use_land_ground | 0 or 1 | Sets whether to use the underlying ground as the object ground sprite, ignoring the ground sprite provided in the sprite layout. When enabled, the ground sprite will be bare ground, grass, snow, desert, etc. as if it were a clear ground tile. In edge foundation mode, the ground may be coast/shore when flooded.

edge_foundation_mode

[mode0, mode1, mode2, mode3]

Enables edge foundation mode for the object.
This property is intended for objects which are positioned at the edge of a tile, and only require a level edge, not a completely level tile.
Foundations will only be added as required to get a suitable level edge.
The format is one mode value per view. If the object has fewer than 4 views then some of the values provided in the property will not be used, and may be 0. All four values must be constants.
Each mode value should be one of:

Value | Meaning
--- | ---
DIAGDIR_NE | North-east edge
DIAGDIR_SE | South-east edge
DIAGDIR_SW | South-west edge
DIAGDIR_NW | North-west edge

combined with 0 or more flags using the | operator:

Value | Meaning
--- | ---
OBJECT_EF_FLAG_ADJUST_Z | Change z-position for the building sprite to the height of the edge
OBJECT_EF_FLAG_FOUNDATION_LOWER | If the height of the edge is lower than the maximum height of the tile, build a foundation

flood_resistant | 0 or 1 | Sets whether the object is flood resistant. Flood resistance is always enabled for objects which can be built on water. This property can be used to enable flood resistance without enabling the object to be built on water.

### Replace new sprites

Type | Number of sprites | Comment
--- | --- | ---

PROGRAMMABLE_PRE_SIGNAL

32

Programmable pre-signals

Signal graphics come in groups of 16. These groups contain sprites in the same order as sprites 1275-1290 in trg1[r].grf and Action 5 type 4 (signals); red, then green, for each of: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing.

Group | Contents
--- | ---
0 | Semaphore programmable pre-signals
1 | Lighted programmable pre-signals

NO_ENTRY_SIGNAL

16

No-entry signals

No-entry signal graphics come in groups of 8. These groups contain sprites in the same order as the red sprites of 1275-1290 in trg1[r].grf and Action 5 type 4 (signals); red only, for each of: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing.

Group | Contents
--- | ---
0 | Semaphore no-entry signals
1 | Lighted no-entry signals

### 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.

Property | Value range | Comment
--- | --- | ---
enable_programmable_pre_signals | 0 or 1 | Enable programmable pre-signal graphics. Programmable pre-signals have a signal type (getbits(extra_callback_info2, 16, 8)) of 6.
enable_no_entry_signals | 0 or 1 | Enable no-entry signal graphics. No-entry signals have a signal type (getbits(extra_callback_info2, 16, 8)) of 7. No-entry signals always have a signal state of red.

enable_restricted_signals

0 or 1

Enable restricted signal flag.
When enabled, bit 24 of variable extra_callback_info2 is set if the signal is restricted (has a routing restriction program attached).
When enabled, the "Show restricted electric signals using default graphics" client setting and signal post recolouring is not applied.
This flag must only be set if a different sprite is returned when bit 24 of extra_callback_info2 is set.

enable_signal_recolour

0 or 1

Enable recolouring of graphics
When enabled, in addition to returning a sprite, register 0x100 may be set to the following using STORE_TEMP:

Bits | Meaning
--- | ---
0 - 23 | Recolour sprite to use. Set to 0 for no recolouring.
24 - 31 | Reserved, set to zero.

extra_aspects

0 - 6

The value is the number of additional signal aspects to use (e.g. 4-aspect signalling should use a value of 2).
When set, the lowest byte of extra_callback_info2 (signal state) may have the given number of additional values starting from 02:

Value | Meaning
--- | ---
00 | Red signal
01 | Green signal
02 | 1st extra aspect (e.g. yellow)
03 | 2nd extra aspect (e.g. double yellow)
... | Further extra aspects...

The provided value is currently clamped to be within the range 0 - 6 (inclusive).
N.B. Realistic braking must be enabled for additional signal aspects to be used

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