NML:Objects

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

Object IDs

Object IDs are NewGRF-local and can therefore freely be chosen in the 0..255 range. An object is allocated by setting the 'class'-property, which should therefore be set first. Overriding the default objects (e.g. transmitter, lighthouse) is not (yet) possible.

Object properties

property	value range	comment
class	String literal of length 4	Unlike station classes, there is currently no default yet. You have to set the class ID before any other property or graphics. Characters allowed in the IDs are A-Z, 0-9. While you are technically free to chose your own class, it's highly recommended you stick to one of the default classes.
classname	string	You only need to set this for one object in every class.
name	string
climates_available	bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)	XXX = [TEMPERATE | ARCTIC | TROPICAL | TOYLAND], alternatively NO_CLIMATE or ALL_CLIMATES
size	[x, y]	Size in x and y direction. Both x and y must be compiletime constants
build_cost_multiplier		multiplicator to the base purchase cost
remove_cost_multiplier		multiplicator to the base removal cost
introduction_date	date	The date this object becomes available to build.
end_of_life_date	date	The last date this object is buildable. Must be at least 365 days after introduction_date
object_flags	bitmask(OBJ_FLAG_XXX, OBJ_FLAG_YYY)	See list of object flags
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
callback_flags	bitmask(OBJ_CBF_XXX, OBJ_CBF_YYY)	Do not set this, unless you use old-style callbacks.
height	0..255	Height of the object / 8. For example if your object is 16 pixels height you should set height to 2. In OpenTTD this property is used to determine the height of the build object window; the height for the object preview is set to 32 + "value of property" * 8. The property is also used to determine how high a bridge must be if it is allowed by the bit in object_flags.
num_views	1, 2 or 4	Objects may have "views", i.e. different graphical representations, e.g. used to show rotated views of an object. Number of views may be 1, 2, or 4. Default value is 1. For non-square objects, x and y sizes are swapped for odd views. Use variable view to determine the view of a built object.

Default object classes

Please refer to the list of object labels in the NewGRF Specs. The default class names listed there are recommended, you still need to set the class name for at least one object in every class or you risk to end up with objects in a class without a name. If multiple NewGRFs define objects for the same class the name defined in the last NewGRF will be used.

List of object flags

Name	Meaning
OBJ_FLAG_ONLY_SE	Only available in the scenario editor (incompatible with OBJ_FLAG_ONLY_INGAME)
OBJ_FLAG_IRREMOVABLE	Object cannot be removed with the normal dynamite tool. In OpenTTD you can only remove the object with the magic bulldozer cheat, in TTDPatch you can remove it by holding ctrl while using the bulldozer tool. The cost of removing this object is multiplied by 25.
OBJ_FLAG_ANYTHING_REMOVE	Anything can remove this object (owned land behavior)
OBJ_FLAG_ON_WATER	Allow construction of the object on water
OBJ_FLAG_REMOVE_IS_INCOME	Removal cost is actually income (owned land behaviour)
OBJ_FLAG_NO_FOUNDATIONS	Do not display foundations if on a slope
OBJ_FLAG_ANIMATED	Setting this flag will allow the object's animation counter to be increased, must be set if you plan to make use of animations.
OBJ_FLAG_ONLY_INGAME	Only available during game play (incompatible with OBJ_FLAG_ONLY_SE)
OBJ_FLAG_2CC	Allows 2cc mapping for objects instead of the default 1cc
OBJ_FLAG_NOT_ON_LAND	Disallows construction on land (implies OBJ_FLAG_ON_WATER)
OBJ_FLAG_DRAW_WATER	Draws the water under the object. Only applies when built on top of a water tile, also replaces the ground tile of the object completely. Does not work when object built on sloped water tiles.
OBJ_FLAG_ALLOW_BRIDGE	Allow bridge over the object taking the building height into account.
OBJ_FLAG_RANDOM_ANIMATION	Random bits in the "next animation frame" callback

Object variables

name	value range	comment
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.
terrain_type	TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
tile_slope	SLOPE_XXX	See tile slopes for an overview of possible values
build_date		The date this object was build.
animation_frame	0..(frame_count - 1)	Current animation frame, with the maximum defined in the object's animation_info.
company_colour	COLOUR_XXX	Colour used for the company colour mask. Refer to the table here for possible values.
owner	0..0x10	CompanyID of the owner of the object or 0x10 if it was build in the scenario editor
town_manhattan_dist		Manhattan distance to the nearest town
town_euclidean_dist		Euclidean distance to the nearest town
town_zone	town zone	The town zone of the current tile. The town zone from the closest town (measured in manhattan distance) is used.
view	0 .. num_views - 1	1.1 The view of the particular object. See also the num_views property.

Variables that require one or more parameters:

name	arguments	value range	comment
nearby_tile_object_type	x, y offset (-8..7)		ID of the object on a nearby tile, if defined by the same grf. OBJECT_TYPE_OTHER_GRF if the object is defined by a different grf (or none at all). OBJECT_TYPE_NO_OBJECT if the tile does not contain an object.
nearby_tile_random_bits	x, y offset (-8..7)		Random bits of the given tile
nearby_tile_slope	x, y offset (-8..7)		See tile_slope
nearby_tile_is_same_object	x, y offset (-8..7)	0 .. 1	Is the given tile part of the same object?
nearby_tile_is_water	x, y offset (-8..7)	0 .. 1	Is the given 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)	0 .. 120	The minimum height of the given tile. 8 units correspond to one height level
nearby_tile_class	x, y offset (-8..7)	Tile class
nearby_tile_animation_frame	x, y offset (-8..7)		See animation_frame
object_count	object id [, grfid]	0..0xFFFF	Number of objects with the given object id currently on the map. Grfid is the grfid of the newgrf you want to check the object count of (default is current grf). Use the builtin function str2number() to convert a grfid to its numeric representation.
object_distance	object id [, grfid]	0..0xFFFF	Manhattan distance to the closest object of the given type. Grfid is the grfid of the newgrf you want to check the minimum object distance of (default is current grf). Use the builtin function str2number() to convert a grfid to its numeric representation. If the given object type is not yet built, this will return 0xFFFF

Object callbacks

callback	return value	comment
default	Sprite layout	Normal graphics for an object placed on the map
purchase*	Sprite layout	Graphics shown in the build menu
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 contains random bits if the object flag OBJ_FLAG_RANDOM_ANIMATION is set. Returning a sound effect in the high byte will cause that sound effect to be played (e.g. return (sound("mysound.wav") << 8) | CB_RESULT_NEXT_FRAME;).
anim_control	Next animation frame or CB_RESULT_XXX	Called whenever an object 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. extra_callback_info1 contains random bits if the object flag OBJ_FLAG_RANDOM_ANIMATION is set. extra_callback_info2 contains the reason to trigger the animation, see the table below. Returning a sound effect in the high byte will cause that sound effect to be played.
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.
colour	colour2*16 + colour1	Called once, just after construction. Variable extra_callback_info1 contains the colour scheme of the constructing company in the same format as the return value, or random colours if not available (scenario editor). If OBJ_FLAG_2CC is not set, colour2 is zero. This callback can be used to alter the colour scheme of an object. Refer to the table here for possible colour values.
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.
tile_check*	Same as for the location_check industry callback	Parameters: extra_callback_info1 contains the slope in bits 0..4 (see below), all other bits are reserved and should be and-masked out. extra_callback_info2 contains the location of the tile within the object as 16*y + x. If this callback is not implemented or fails, the default behaviour is to allow building the object if it can be placed on a flat surface. This means that steep slopes are not allowed and that the highest corner of each tile of a multi-tile object should have the same height. Additionally, all tiles must be flat if "build on slopes" is disabled.
additional_text*	String	Additional text to show in the purchase menu

* These callbacks are called when the object is not yet built, so object- specific variables cannot be accessed. Trying to do so will result in undefined behaviour.

Animation triggers

Animation trigger	Description
ANIM_TRIGGER_OBJ_BUILT	Object is built (all tiles at the same time)
ANIM_TRIGGER_OBJ_TILELOOP	Object tile is processed in the tileloop (at different times for different tiles)
ANIM_TRIGGER_OBJ_256_TICKS	Every 256 ticks (all tiles at the same time)