## NewGRF New Landscape Addition to NewGRF Specifications in JGR's Patchpack in NML

This document describes the non-standard addition of the NewGRF new landscape feature to the Official OpenTTD NML Specifications, as implemented in this patchpack, and the associated NML fork

This feature allows NewGRF custom graphics using switches and spritesets for landscape tiles. Currently this includes: rock tiles.

This feature may not necessarily match implementations of additional landscape graphics features in other patches, branches, etc.
This feature as implemented here MAY also be present in other patchpacks.

The feature identifier is FEAT_NEWLANDSCAPE.
There is no permanent storage associated with this feature.

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

See the associated non-NML document for more details on the NewGRF new landscape 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, then extended_feature_test("new_landscape") SHOULD be called 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:

- IDs
- Properties
- Variables
- Syntax example

### New Landscape IDs

The ID field for an item must be set to one of the IDs in the table below (further IDs may be allocated for other purposes in future).

ID | Landscape type
--- | ---
NEW_LANDSCAPE_ID_ROCKS | Rocky tiles

### New Landscape Properties

Property | Value range | Comment
--- | --- | ---
enable_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.
enable_draw_snowy_rocks | 0 or 1 | Enable drawing of rock tiles covered by snow, for this GRF. (This only takes effect from new_landscape version 2).

### New Landscape Variables

Name | Value range | Comment
--- | --- | ---
terrain_type | TILETYPE_XXX | XXX = NORMAL | DESERT | RAIN_FOREST | SNOW
tile_slope | SLOPE_XXX | See tile slopes for an overview of possible values
tile_height | 0..255 | Height of the lowest corner of the tile
tile_hash | 0..4294967295 | Hash value derived from the coordinates of the tile, suitable for pseudo-randomising graphics
landscape_type | NEW_LANDSCAPE_TYPE_XXX | Landscape type XXX = ROCKS
snow_present | 0 or 1 | Snow is present on this tile, at any density.This requires new_landscape, version 2.
ground_density | 0..3 | Ground density (if snow_present is 1, this is the snow density).This requires new_landscape, version 2.

Variables that require one or more parameters:

Name | Arguments | Value range | Comment
--- | --- | --- | ---
nearby_tile_slope | x, y offset (-8..7) | SLOPE_XXX | Slope of a nearby tile
nearby_tile_is_same_type | x, y offset (-8..7) | 0 | 1 | Is nearby tile the same landscape type as this one?
nearby_tile_is_water | x, y offset (-8..7) | 0 | 1 | Is nearby tile a water tile?
nearby_tile_terrain_type | x, y offset (-8..7) |  | See terrain_type
nearby_tile_water_class | x, y offset (-8..7) | WATER_CLASS_XXX | XXX = [NONE | SEA | CANAL | RIVER] Note that tiles for which nearby_tile_is_water is 0 may still have a water class, e.g. industry tiles with water beneath them.
nearby_tile_height | x, y offset (-8..7) |  | The minimum height of the given tile in height level units
nearby_tile_class | x, y offset (-8..7) | tile class |
nearby_tile_info | x, y offset (-8..7) |  | Above nearby tile variables in one variable (all of variable 0x60)

### Syntax example

    grf {
    	...
    }

    if (!extended_feature_test("new_landscape")) {
    	error(FATAL, string(STR_UNSUPPORTED_VERSION));
    }

    spriteset spriteset_rocks {
    	/* 19 tile sprites in the standard order */
    }

    switch (FEAT_NEWLANDSCAPE, SELF, switch_rocks, ...) {
    	...
    }

    item (FEAT_NEWLANDSCAPE, item_rocks, NEW_LANDSCAPE_ID_ROCKS)  {
    	property {
    		enable_recolour: 0;
    	}
    	graphics {
    		default: switch_rocks;
    	}
    }