NML:IndustryTiles

NewGRF Meta Language

Preface

Getting started

Graphics files

Blocks

Units

Expressions

Elementary values

Builtin functions

Language files

Lists of props, vars and CBs

Warnings

Additional references

NewGRF compatibility

Deprecated syntax

Changes from NML 0.2 to 0.3

Changes from NML 0.3 to 0.4

Changes from NML 0.4 to 0.5

Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain

NML Tutorial

Props, Vars and CBs

General

• variables

Vehicles

• common props | vars | CBs
• train | roadveh | ship | aircr props

Stations

• properties | variables | callbacks

Canals

• properties | variables | callbacks

Bridges

• properties | variables | callbacks

Towns

Houses

• properties | variables | callbacks

Industries

• common variables
• industry props | vars | CBs
• tile props | vars | CBs

Cargos

• properties | variables | callbacks

Airports

• airport props | vars | CBs
• tile props | vars | CBs

Objects

• properties | variables | callbacks

Railtypes

• properties | variables | callbacks

Roadtypes

• properties | variables | callbacks

Tramtypes

• properties | variables | callbacks

This page contains information on industry tile properties, variables and callbacks. Industries are closely related.

Industry tile ID allocation

Industry tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. You should start your item definition with the 'substitute'-property, which allocates a new industry tile. The value of this property should be the ID of a default industry tile, which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Furthermore, you can set the 'override'-property, which will cause the existing industry tile to be replaced with your item. You should use this if you are for example defining a coal mine which changes production more dynamically. If your type is not a direct replacement of an existing item, don't set this property.

Industry tile properties

property	value range	comment
substitute	0..174	Number of the default industry tile that replaces this one, if this industry tile is not available for some reason. This property must be set first, before any other properties or graphics. All properties of the old type are copied to your new house.
override	0..174	id of the default industry tile which this industry tile replaces. This will cause your industry tile to be placed instead of the default industry tile. This is ignored, if the default industry tile has already been overridden. You can define this property multiple times
accepted_cargos	Array with up to 3 [cargo_id, amount]-pairs. NML 0.5 1.9 Array with up to 16 [cargo_id, amount]-pairs.	The cargos that are accepted by this tile. CargoID is a cargo type from your cargo translation table, amount is the acceptance of the given cargo in 1/8 units. Example: to make a tile accept both COAL and IORE you could use this: accepted_cargos: [[COAL, 8], [IORE, 8]]; Example: for a tile that doesn't any cargos at all you'd use: accepted_cargos: []; See also INDTILE_FLAG_ACCEPT_ALL.
land_shape_flags	bitmask(Land shape flags)
callback_flags	bitmask(INDTILE_CBF_XXX, INDTILE_CBF_YYY)	Do not set this, unless you use old-style callbacks.
animation_info	Array [ANIMATION_XXX, frame-count]	XXX = [LOOPING | NON_LOOPING], 1..253 frames
animation_speed	0..16	Speed of animation, see animation speed table for the meaning of the values.
animation_triggers	bitmask(ANIM_TRIGGER_INDTILE_XXX, ... )	Bitmask of triggers that will trigger the anim_control callback, see the table below.
special_flags	bitmask(INDTILE_FLAG_XXX)	INDTILE_FLAG_RANDOM_ANIMATION set this if the decision in anim_control callback needs random bits via extra_callback_info1 INDTILE_FLAG_ACCEPT_ALL NML 0.5 1.9 In addition to the cargotypes set by accepted_cargos, the tile accepts all cargotypes which the industry accepts. This considers industry property cargo_types and callback cargo_input. This does not consider industry callback stop_accept_cargo. This property adds 8/8 acceptance for the matching cargotypes. You can list negative acceptances (-8/8) in property 13 to exclude specific cargos. Tile callback cargo_type_accept overrides all acceptances including those added by this flag.

Land shape flags

Flag	Meaning
LSF_CANNOT_LOWER_NW_EDGE	North-west edge cannot be lowered
LSF_CANNOT_LOWER_NE_EDGE	North-east edge cannot be lowered
LSF_CANNOT_LOWER_SW_EDGE	South-west edge cannot be lowered
LSF_CANNOT_LOWER_SE_EDGE	South-east edge cannot be lowered
LSF_ONLY_ON_FLAT_LAND	This tile can only be built on flat land
LSF_ALLOW_ON_WATER	The land/water check is disabled for this tile so it can be built on water. If you need more control over this use callback "tile_check".

Common variables

The following variables are available to both industries and industry tiles. All of them require an x, y offset. For industries, this offset is unsigned and relative to the northernmost tile. For industry tiles, it is signed and relative to the current tile.

name	value range	comment
nearby_tile_slope	SLOPE_XXX	See tile slopes for an overview of possible values
nearby_tile_is_water	1 if the tile is water, 0 otherwise
nearby_tile_terrain_type	TILETYPE_XX	TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
nearby_tile_water_class	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	0..120	The height of the lowest corner of the given tile.
nearby_tile_class	Tile class
nearby_tile_animation_frame	0..255	Animation frame of the given tile
nearby_tile_industrytile_id	0x00aa, 0xFFbb, 0xFFFE or 0xFFFF	0x00aa: The tile is an industry tile defined in this GRF with tile id aa. 0xFFbb: The tile is an original industry tile with id bb. 0xFFFE: The tile is an industry tile defined in another GRF. 0xFFFF: The tile is not an industry tile or it belongs to another industry.

Industry tile variables

name	value range	comment
construction_state	0..3	Current construction state of the industry tile.
terrain_type	TILETYPE_XX	TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
town_zone	town zone	The town zone of the current tile.
relative_x	0..255	X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
relative_y	0..255	Y-coordinate (top left -> bottom right) of the tile relative to the northernmost tile.
relative_pos	0xYYXX	A combination of relative_x and relative_y in the format 0xYYXX. Useful if you want to check for a single position. The builtin function relative_coord(x, y) may be useful when making comparisons.
animation_frame	0..255	Current animation frame.

Industry tiles have access to the common variables described above. Additionally, they have access to the following:

name	arguments	comment
nearby_tile_is_same_industry	x, y	Parameters indicate a signed tile offset relative to the current tile. Returns 1 if the tile is part of the same industry, 0 otherwise

Industry tile callbacks

callback	return value	comment
default	Sprite layout	Graphics for the industry tile
random_trigger	N/A	See random switch for more information.
anim_next_frame	Next animation frame or CB_RESULT_XXX	Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. extra_callback_info1: 32 random bits, if enabled in the special_flags property. Returning a sound effect in the high byte will cause that sound effect to be played. Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
anim_control	Next animation frame or CB_RESULT_XXX	Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION | STOP_ANIMATION | DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played. extra_callback_info1: 32 random bits, if enabled in the special_flags property. getbits(extra_callback_info2, 0, 8): Reason for the callback trigger, see the table below. Note that you need to enable the wanted triggers in the animation_triggers property. Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
anim_speed	0 .. 16	Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
cargo_type_accept	type1 + (type2 << 5) + (type3 << 10)	Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from accepted_cargos are used instead. Bits 0..4: First cargo type. Bits 5..9: Second cargo type. Bits 10..14: Third cargo type.
cargo_amount_accept	amt1 + (amt2 << 4) + (amt3 << 8)	Acceptance for each cargo amount in 1/8th. If this callback is not implemented or fails, the values from accepted_cargos are used instead. Cargo types are from the cargo_type_accept callback, or the accepted_cargos property if that callback failed. Bits 0..3: Acceptance of first cargo type. Bits 4..7: Acceptance of second cargo type. Bits 8..11: Acceptance of third cargo type.
tile_check	Same as for the location_check industry callback	Called before constructing the industry, so nothing exists on the map yet. Since the industry isn't built yet, so you can't access industry variables. From the tile variables, relative x/y/position, town zone are available, as well as the class, height, slope, terrain type and water status of nearby tiles. getbits(extra_callback_info2, 0, 8): The industry layout number. getbits(extra_callback_info2, 8, 8): The creation type Note: use of this callback will deactivate the use of the landshape flags. If this callback is not implemented or fails, the land_shape_flags property will be used instead to determine if the slope is suitable. This also means that without this callback, the tile may not be built on steep slopes.
foundations	CB_RESULT[_NO]_FOUNDATIONS	Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
autoslope	CB_RESULT[_NO]_AUTOSLOPE	Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.

Location check results

The following values can be used as return values for the location_check callback for industries and the tile_check callback for industry tiles and objects.

return value	meaning
string(..)	Item can't be built, show the string as error message.
CB_RESULT_LOCATION_ALLOW	Item can be built.
CB_RESULT_LOCATION_DISALLOW	Item can't be built, display the default error message. This is "site unsuitable" for industries and industry tiles, and "land sloped in wrong direction" for objects.
CB_RESULT_LOCATION_DISALLOW_ONLY_RAINFOREST	Item can't be built, display the "...can only be built in rainforest areas" error message.
CB_RESULT_LOCATION_DISALLOW_ONLY_DESERT	Item can't be built, display the "...can only be built in desert areas" error message.
CB_RESULT_LOCATION_DISALLOW_ONLY_ABOVE_SNOWLINE	Item can't be built, display the "...can only be built above the snow-line" error message.
CB_RESULT_LOCATION_DISALLOW_ONLY_BELOW_SNOWLINE	Item can't be built, display the "...can only be built below the snow-line" error message.
CB_RESULT_LOCATION_DISALLOW_NOT_ON_OPEN_SEA	Item can't be built, display the "...can't build on open sea" error message.
CB_RESULT_LOCATION_DISALLOW_NOT_ON_CANAL	Item can't be built, display the "...can't build on canal" error message
CB_RESULT_LOCATION_DISALLOW_NOT_ON_RIVER	Item can't be built, display the "...can't build on river" error message.

Animation triggers

Trigger	Meaning
ANIM_TRIGGER_INDTILE_CONSTRUCTION_STATE	the construction state changes
ANIM_TRIGGER_INDTILE_TILE_LOOP	the tile is processed in the periodic processing loop
ANIM_TRIGGER_INDTILE_INDUSTRY_LOOP	the industry of the tile is processed in the periodic processing loop (synchronized for all tiles)
ANIM_TRIGGER_INDTILE_RECEIVED_CARGO	the industry of the tile receives input cargo from a station (synchronized for all tiles)
ANIM_TRIGGER_INDTILE_DISTRIBUTES_CARGO	the industry distributes its output cargo to one of the stations nearby (synchronized for all tiles)